Applications that use GeneXus Access Manager can be Identity Providers. In a scenario with an Identity Provider and one or more client applications, the applications will use GAM Remote Authentication Type to authenticate using the Identity Provider (from now on, the server).
Each client application must be connected to a different GAM database and have Integrated Security enabled. It's required that each client application has its own GAM database so it can be specified a unique (1)Call Back URL. This is necessary to comply with the security specifications of an Identity Provider.
When the client authenticates, its behavior is the same as when an application authenticates to Facebook or Twitter, because a session is generated in the Identity Provider and used by the application while it continues to be valid.
That's why this functionality is very useful for implementing Single Sign On in applications. SSO works only in WEB applications.
The necessary configuration for GAM Remote Authentication Type is explained below.
First, define a GAM application on the server for each web application that is going to be client of the Identity Provider.
The GAM applications defined on the server will have the same Client Id and Client Secret information that they have on the client.
When the GAM Web Backoffice is used, applications are added using the Application menu item. Go through Applications, "Add" button - that calls the Web panel GAMExampleEntryApplication:
Next, complete the information of the screen as shown below.
The client application information that must be provided is as follows:
The "Allow remote authentication" check box must be selected to enter the following information (*):
- Local Login URL. URL of the server application login (e.g: /TestGAMSSOServer.NetEnvironment/gamremotelogin.aspx). The format is: /<BaseURL>/[<package>.]gamremotelogin. The GAMRemoteLogin object is distributed in the GAM Examples.
- (1)Call Back URL. URL of the client application (e.g: http://server:8080/TestGAMRemoteJavaSQLServer). The format is: Http://<Server>:<Port>/<BaseURL>. For Java, do not include "/servlet".
- Image URL. URL of the image logo of the client application.
- Private Encryption Key. By using this private encryption key, we encrypt the communication between client applications and the server application; however, the use of HTTPs is recommended.
(*) If "Allow remote authentication" is not checked, the following error is thrown when the user tries to authenticate to the Identity Provider:
Remote authentication is not allowed in this application. Please contact the administrator. (GAM230)
On the client, we must configure the GAM Remote Authentication Type.
By using the GAM Web Backoffice, we may add the authentication type through the Authentication Types menu item.
Picture #4. Defining GAM Remote Authentication Type. Web panel GAMExampleEntryAuthenticationType.
- Client ID. Client ID of the client application. The same as the one specified in Picture #2.
- Client Secret. Client Secret of the client application - the same as the one specified in Picture #2. Both (Client Id and Client Secret information) may be found using the GAM Web Backoffice on the client.
- Local Site URL. URL of the client application - the same as the one specified in the Call Back URL in picture #2.
- Additional Scope. The only valid additional scope is "gam_user_additional_data". By using this additional scope, we send the extended attributes of the GAM Users to the GAM client.
If no additional scope is added, the following basic information is transferred from the server to the client: Guid, Username, EMail, First_Name, Last_name, External_id, Birthday, Gender, Url_image, Url_profile, Phone, Address, City, State, Post_code, Language, Timezone. To send additional data, we must check the option "Get user additional data" in the server application. See the picture #2.
- Remote Server URL. URL of the server application (e.g: http://server/TestGAMSSOServer.NetEnvironment). The format is: Http://<Server>:<Port>/<BaseURL>. For Java, do not include "/servlet".
- Private Encryption Key. By using this private encryption key, we encrypt the communication between client applications and the server application. It must be configured with the same value as the one specified for the GAM application defined in the Identity Provider (the server). If they are different, an error "javax.servlet.ServletException: java.lang.InternalError: invalid key" is thrown.
See GAM Remote Authentication type for Smart Devices
- When authenticating through the Identity Provider, the user is created or updated in the client GAM database using the same GAM User GUID from the GAM of the Identity Provider. The password is stored only in the GAM of the Identity Provider.
- The default data transferred from the Identity Provider database to the client is: Guid, Username, EMail, First_Name, Last_name, External_id, Birthday, Gender, Url_image, Url_profile, Phone, Address, City, State, Post_code, Language, Timezone.
- When additional data must be passed (such as dynamic attributes of GAM User), we must then add "gam_user_additional_data" additional scope to the configuration.
- The password GAM Security Policies applicable are those of the Identity Provider GAM.
- The applicable security policies not related to the password are those of the client GAM database.
- The information required must be completed on the server and also on the client. So, if the email address is required by the server security policies, its entry will be requested. Likewise, when any other data is required in the client GAM, we will be asked to complete it as well.
Logging out from the client does not log out from the server.
The Identity provider may use any of the following authentication types:
The solution of GAM Remote Authentication is based on OAuth 2.0.
Single Sign On in applications using GAM
Managing Roles in applications using SSO