Using a SOAP web service as an external identity provider is not useful when you need to store and persist data in a web session related to the login and read this data when desired, from any other object of the application.
Suppose a .dll file which has been implemented for authentication purposes, and it has one method for authenticating the user and another one for viewing his account balance. The login method saves a web session, which needs to be read when the "ViewUserBalanceAccount" is executed. As web sessions do not persist if saved in web services, a web service is not useful for this scenario.
In this scenario, instead of using GAM External Web Services Authentication Type you may use GAM Custom Authentication Type, where the external program is not a SOAP service, but a program of the same platform of the application which uses GeneXus Access Manager (it can be a .dll, .rb, or .class developed using Genexus or not).
Using GAM Custom Authentication Type there are two possible versions of the external program supported, depending on the json format of the input and output parameters of the program, which are the following:
In those links you can download the XPZ containing the data types needed.
- in parameter: string.
It has to be a string in json format, which structure has to be the same as the GAMWSLoginInSDT structured data type.
- out parameter: string.
It has to be a string in json format, which structure has to be the same as the GAMWSLoginOUTSDT structured data type, or void.
For information about the data types see GAM External Authentication: version 1.0 or GAM External Authentication: version 2.0.
Parm(in:&StrInput, out:&StrOutput); //&StrInput and &StrOutput are varchar(256)
&Key = '03E1E1AAA5BCA19FBA8C42058B4ABF28'
&GAMWSLoginIn.FromJson(&StrInput) // &GAMWSLoginIn is &GAMWSLoginInSDT data type
&UserLogin = Decrypt64( &GAMWSLoginIn.GAMUsrLogin, &Key )
&UserPassword = Decrypt64( &GAMWSLoginIn.GAMUsrPwd, &Key )
&GAMWSLoginOut = New GAMWSLoginOutSDT() //&GAMWSLoginOut is &GAMWSLoginOutSDT data type
&GAMWSLoginOut.WSVersion = GAMAutExtWebServiceVersions.GAM10
&GAMWSLoginOut.User = New GAMWSLoginOutUserSDT()
&StrOutput = &GAMWSLoginOut.ToJson()
If &UserLogin = !"user"
If &UserPassword = !"password"
&GAMWSLoginOut.WSStatus = 1
&GAMWSLoginOut.User.Code = !"code"
&GAMWSLoginOut.User.FirstName = !"FirstName"
&GAMWSLoginOut.User.LastName = !"LastName"
&GAMWSLoginOut.User.EMail = !"firstname.lastname@example.org"
Do 'GetRoles' //optional
&GAMWSLoginOut.WSStatus = 3
&GAMWSLoginOut.WSStatus = 2
&GAMWSLoginOutUserRol = New()
&GAMWSLoginOutUserRol.RoleCode = "role_1"
&GAMWSLoginOutUserRol = New()
&GAMWSLoginOutUserRol.RoleCode = "role_2"
It has to be "Custom Authentication" Type.
As seen in figure 1, you have to specify some data of the authentication external program.
Function: You have to specify if the external program will be used for authentication and authorization purposes also. In case of specifying "Authentication and Roles", see Managing Roles through external authentication programs.
Json Version: Specify the external program version (1.0 or 2.0).
Private Encryption Key: The "Encryption Key" is useful in case of Genexus external authentication programs because the Encrypt64 function is used to encrypt the user name and password when passed to the program. Here you have to configure the Encryption key used in the external program for decrypting the user and password received.
File Name: Specify the name of the file which corresponds to the external program (dll/jar/class/rb). It's optional for java.
Package: Here specify the same value of Java Package Name Property (GeneXus X Evolution 2) in case of Java models, the value of .Net Application namespace property in case of NET models and the Code Namespace in case of Ruby. This property is optional and depends on the external program, if it has a package or not.
Class Name: This field is required. Here specify the name of the class of the external program.
See the sample object GAMExampleEntryAuthenticationType which is part of the GAM Web Backoffice in order to get an example code for adding and updating any Authentication Type.
The LoginExternal method of SDActions external object (X Evolution 3) is used. In this case the first parameter sent to the method must be "Custom".
GeneXus.SD.Actions.LoginExternal(GAMAuthenticationTypes.Custom, &User, &Password)
The following code is an example for executing the custom external login in web applications. In case of web panels the Login method of GAMRepository object is used. You need to define a variable of GAMLoginAdditionalParameters in order to specify the AuthenticationType which is going to be used.
See the GAMExampleLogin web panel (which is part of the GAM Examples), where this coded is used as an example:
&AdditionalParameter.AuthenticationTypeName = &LogOnTo //&LogOnTo is a combo box where the user selects the authentication type he wants to use.
// This is the name of the Authentication Type. Using the example shown in figure 1 it would be "custom1.0testjava".
&LoginOK = GAMRepository.Login(&UserName, &UserPassword, &AdditionalParameter, &Errors )//&Errors is collection of GAMError
1. In case that the external program was developed using Genexus, it will have a method named "execute".
If the program was developed using other tool than Genexus it may have any method used for authentication. In this case you have to declare the name of the method using the following line of code, when you define the Custom Authentication type:
&AuthenticationTypeCustom.Custom.Method = "myauthenticationmethod" //&AuthenticationTypeCustom is GAMAuthenticationTypeCustom data type.
See the sample object GAMExampleEntryAuthenticationType (which is part of the GAM Examples) for the complete example code.
2. Only one "Custom" Authentication Type can be defined for each GAM Repository.