GAM Custom Authentication Type

Official Content

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.

How to authenticate using GAM Custom Authentication Type

1. The external authentication program (.rb, .class., .dll) needs to meet some requirements.

  • 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.

Example of external authentication program version 1.0

Rules:

Parm(in:&StrInput, out:&StrOutput); //&StrInput and &StrOutput are varchar(256)

Source code:

&Key = '03E1E1AAA5BCA19FBA8C42058B4ABF28'
&GAMWSLoginIn.FromJson(&StrInput) // &GAMWSLoginIn is &GAMWSLoginInSDT data type
//Decrypt parameters
&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()
Do 'ValidUser'
&StrOutput = &GAMWSLoginOut.ToJson()

Sub 'ValidUser'
    If &UserLogin = !"user"
       If &UserPassword = !"password"
          &GAMWSLoginOut.WSStatus = 1
          &GAMWSLoginOut.User.Code         = !"code"
          &GAMWSLoginOut.User.FirstName    = !"FirstName"
          &GAMWSLoginOut.User.LastName     = !"LastName"
          &GAMWSLoginOut.User.EMail        = !"name2@domain.com"    
          Do 'GetRoles' //optional
       Else
          &GAMWSLoginOut.WSStatus = 3
       EndIf
    Else
       &GAMWSLoginOut.WSStatus = 2
    EndIf
EndSub

Sub 'GetRoles' 
    &GAMWSLoginOutUserRol = New()
    &GAMWSLoginOutUserRol.RoleCode = "role_1"
    &GAMWSLoginOut.User.Roles.Add(&GAMWSLoginOutUserRol) 
    &GAMWSLoginOutUserRol = New()
    &GAMWSLoginOutUserRol.RoleCode = "role_2"
    &GAMWSLoginOut.User.Roles.Add(&GAMWSLoginOutUserRol
EndSub

2. Define a new (Authentication Type) using GAM Web Backoffice.

It has to be "Custom Authentication" Type.

CustomAuthTypedef
Java Sample

CustomAuthTypedef2
.Net sample
Figure 1.

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.

3. Program "Custom Authentication" login in the smart devices application

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".

Event 'ExternalLogin'
    Composite
        GeneXus.SD.Actions.LoginExternal(GAMAuthenticationTypes.Custom, &User, &Password)
        Return
    EndComposite
EndEvent

4. Program "Custom Authentication" login in the web application

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

Note

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.




Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.