Howto: sending and receiving properties set at the login

Official Content
This documentation is valid for:

At user login, it is possible to add user-related properties such as the company branch where the user works.

These properties, called "initial properties", may be saved in the GAMSession to be retrieved and used later, regardless of the GAM Authentication Type used.

For which cases is it recommended to use initial properties?

  • In GAM Local Authentication Type, GAM Remote Rest Authentication type (Oauth 2.0) or any other authentication type, it is possible to save user-related data at the user's login (for example, the company branch the user tries to access). Upon a successful login, the Repository_Login event is triggered, with the procedure subscribed to this event obtaining that information from the GAMSession, to verify the access for that company-branch. Otherwise, the login may be cancelled (see GAM Events subscription - Example III).
    In such case, apart from the benefits of cancelling the login, the information is persisted in the GAM database and cached. This is particularly useful for Smart Device apps.
     
  • In the case of a login with an Identity Provider (GAM Remote Authentication Type), the initial properties may be sent from the local login to the Identity Provider (IDP), and viceversa (the properties may be set at the Identity Provider's and sent to the client as well).
    A case for using initial properties could be setting the language in which the user prefers the Identity Provider's login panel. When the user selects the language at the client's login, you can then use an initial property to save the language in the GAMSession. That information may be retrieved at the Identity Provider's, to show the panel in the language selected by the user.
     
  • When GAM Remote Authentication Type is used at the client, and the Identity Provider uses any type of GAM External Authentication Type (GAM Custom Authentication Type or GAM External Web Services Authentication Type), you can set additional parameters for the authentication procedure (or web service) reading the initial properties set at the client login. The initial properties should then be retrieved at the IDP, and used to call the login. See HowTo: Pass additional parameters to external authentication programs using GAM.

Note that the concept of initial properties is different from the extended user attributes.  Initial properties relate to a user in the login and they are saved in the GAMSession and cached.
It's also different from the SetApplication data and GetApplicationData method of GAMSession object (1).

The initial properties may be retrieved from the GAM session using the method below:

GAMSession.InitialProperties

Example (Web)

Notice the GAMExamplelogin object (of the GAM Web Backoffice) where the login is executed (Enter event). 
The initial properties are loaded into a variable of the GAMProperty data type and added to the properties collection of the GAMLoginAdditionalParameters -parameter of the login method.

 
&CustomProperty = new()  //&CustomProperty is GAMProperty data type
&CustomProperty.Id        = "branch"
&CustomProperty.Value    = "120"
&AdditionalParameter.Properties.Add(&CustomProperty) //&AdditionalParameter is GAMLoginAdditionalParameters data type
//These properties are saved in the session when the user authenticates
&AdditionalParameter.AuthenticationTypeName = &LogOnTo  //GAM Remote Rest
&LoginOK = GAMRepository.Login(&UserName, &UserPassword, &AdditionalParameter, &Errors )

The code above must be added in the event that corresponds to the login, which will depend on the Authentication Type used. For example, in the case of the GAM Remote Authentication type, it must be added in the 'SelectAuthenticationType' event of the GAMexamplelogin panel.

Example (SD)

In this case, the properties are assigned to a collection of LoginExternalAdditionalParameters data type.

Event 'LoginGAMLocal'
Composite
     &LoginExternalAdditionalParameters = new()
      &LoginExternalAdditionalParameters.AuthenticationTypeName = !"local"
      &LoginExternalAdditionalParameters.Repository = !"85a3006c-0606-41d2-980e-223f88463ec2"
      &LoginExternalAdditionalParametersProperty = new()
      &LoginExternalAdditionalParametersProperty.Id = !"branch"
      &LoginExternalAdditionalParametersProperty.Value = !"22-sd"
      &LoginExternalAdditionalParameters.Properties.Add(&LoginExternalAdditionalParametersProperty)
      &LoginExternalAdditionalParametersProperty = new()
      &LoginExternalAdditionalParametersProperty.Id = !"job"
      &LoginExternalAdditionalParametersProperty.Value = !"12-sd"
      &LoginExternalAdditionalParameters.Properties.Add(&LoginExternalAdditionalParametersProperty)
      GeneXus.SD.Actions.LoginExternal(GAMAuthenticationTypes.GAMLocal, &User, &Password, &LoginExternalAdditionalParameters)
      Return
EndComposite
Endevent

In all cases, initial properties may then be retrieved from the GAM session, using the following method:

GAMSession.InitialProperties

Where to retrieve the information

Initial properties may be retrieved using the Repository_Login subscription event. In the case of GAM Remote Authentication and GAM Remote Rest Authentication type (Oauth 2.0), it can be the Repository_Login event at the Identity Provider and at the client.
In all cases, the initial properties are obtained using the GAMSession.InitialProperties method.

Note the following example code, which belongs to a procedure subscribed to the Repository_Login event.

Parm(in:&EventName, in:&jsonIN, out:&jsonOUT);

do case
    case &EventName = GAMEvents.Repository_Login
        &GAMSession.FromJsonString(&jsonIN)
        for &GAMProperty in &GAMSession.InitialProperties
              /////
        endfor
........................
endcase

GAM Configuration in the case of GAM Remote Authentication type

In the case of GAM Remote Authentication Type, the properties may be retrieved in the GAMRemoteLogin object using the method below:

GAMRepository.GetGAMRemoteInitialProperties()

For example, this may be the code in the Enter Event of the GAMRemoteLogin object:

&GAMProperties = GAMRepository.GetGAMRemoteInitialProperties()
&AdditionalParameter.Properties = &GAMProperties
//Here you can add new properties if you want:
&GAMProperty = new()
&GAMProperty.Id = "section"
&GAMProperty.Value = "98"
&AdditionalParameter.Properties.Add(&GAMProperty)    
&AdditionalParameter.AuthenticationTypeName = &LogOnTo
&LoginOK = GAMRepository.Login(&UserName, &UserPassword, &AdditionalParameter, &Errors )

Note, in the example above, that the initial properties set at the client login were retrieved, and more initial properties were added as well.

1. At the client, you must configure that it will receive the initial properties from the server. Using the GAM Web Backoffice in the Authentication Type's entry panel (GAMWCAuthenticationTypeEntryGeneral), you must check the "Add gam_session_initial_prop scope?" option. See Client Configuration for GAM Remote Authentication.

The corresponding code is as follows:

&AuthenticationTypeGAMRemote.GAMRemote.AddSessionInitialPropertiesScope = TRUE

2. In the Identity Provider's Application configuration, you must enable the Application for it to send the initial properties to clients. Using the GAM Web Backoffice, you must check the  "Can get session initial properties?" option in the Application. See Identity Provider Configuration for GAM Remote Authentication.

The code is the following:

&GAMApplication.ClientAllowGetSessionInitialProperties = TRUE

GAM Configuration in the case of GAM Remote Rest Authentication type

In the case of GAM Remote Rest Authentication type (Oauth 2.0), the properties may be received at the server, but no more properties may be added there (as it happens with GAM Remote Authentication). 
The following properties are for receiving, at the client, the same properties that were set at the client before the login (they are sent to the server and then sent to the client again, if the following properties are activated).

1. At the client, you must configure that it will receive the initial properties from the server. Using the GAM Web Backoffice, you must check the "Add gam_session_initial_prop scope?" option. See Client side configuration for GAM Remote Rest Authentication type.

The code is as follows:

&AuthenticationTypeGAMRemoteRest.GAMRemoteRest.AddSessionInitialPropertiesScope = TRUE

2. At the Identity Provider's Application configuration, you must enable the Application to send the initial properties to the clients. Using the GAM Web Backoffice, you must check the  "Can get session initial properties?" option. See Server side configuration for GAM Remote Rest Authentication type.

The code is as follows:

&GAMApplication.ClientAllowGetSessionInitialPropertiesRest    = TRUE

Note

Using GAM Custom Authentication Type or GAM External Web Services Authentication Type, you can also consider the following solution: HowTo: Pass additional parameters to external authentication programs using GAM.

(1)There's a difference between the "initial properties" concept and SetApplication data and GetApplicationData method of GAMSession object. Both are used to save data associated with the user's session, but the initial properties may be recorded only at the time of login; and they may not be changed afterwards. These are also structure-predefined by ID-Token-Value (GAMProperty).
The ApplicationData may be recorded n times during a user's session. The developer defines an SDT for his needs and sends, to the SetApplicationData, an &SDT.ToJSon() parameter, with a free style structure.

Availability

As from GeneXus 16 upgrade 7