GAM SAML 2.0 Authentication type

Official Content

GeneXus Access Manager (GAM) allows you to authenticate using any SAML 2.0 provider.

Some example Providers are as follows:

  • AGESIC
  • SAP 
  • Okta (https://developer.okta.com/docs/api/resources/idps)

SAML is a secure XML-based communication mechanism, for communicating identities beetwen organizations. It's an acronym from Security Assertion Markup Language. The primary use case that SAML solves is SSO. Therefore, it eliminates the need to maintain multiple credentials in multiple locations, so it increases security and decreases administration timing tasks.
Another benefit of using SAML is the use of a federated identity for the users. Users often have local user identities within the domains of each application. Identity federation provides a means for these applications to agree on a shared name identifier to refer to the user.

Summary

How does it work?


SAML is an XML-based framework for authentication and authorization between two entities: a Service Provider and an Identity Provider (IdP). The Service Provider agrees to trust the Identity Provider to authenticate users. The IdP may request some information from the user - such as a user name and password (but it can be any authentication method) - in order to authenticate. Then, the IdP generates an authentication assertion (i.e. an statement that service providers use to make access-control decisions), which indicates that a user has been authenticated.

For more information, see SAML v2.0 Technical overview.

In sum, the behavior is that, when there isn't a valid session, the user is redirected to the IdP login page. After he logs in, he is redirected again to the application. Within the same browser, if another Service Provider tries to login using the same IdP, and there is already a valid session, the user won't be asked to login again.

How to configure SAML 2.0 Authentication Type using GAM

First define a new GAM Authentication Type SAML 2.0. It requires detailed configuration of the protocol, following the documentation of the Identity Provider to which you wish to connect to.

In the following figure, Agesic is being used as an example:

image_20181112154720_1_png

Tab General

Basic identification information of the application in SAML 2.0. All these information should be completed after making a service agreement with the SAML Provider. In the case of Agesic, see Agesic: Integración con servicio de autenticación. For specific information, see HowTo: Configuring SAML 2.0 GAM Authentication type using Agesic.
For specific information on configuring SAML 2.0 Authentication type using SAP, see HowTo: Configuring SAML 2.0 GAM Authentication type using SAP.

This tab has two particular sections:

  • Login: In this section configure the Service Provider Entity ID, which is an identifier of your application in the Identity Provider. This is configured in this field and also in the Identity Provider itself. There is also the SAML Endpoint Location field, where the location of the Identity Provider's endpoint must be configured, in order to login.
     
  • Logout: In this section the Single Logout Endpoint is configured, which works in the same way as the SAML Endpoint Location, but it indicates the location to logout.

    Note: All these information is agreed in the contract with the IdP.

image_20181112154922_1_png

Force Authentication = TRUE means that each time a login is needed in a different Service Provider, the IdP will ask the user to enter the credentials again (SSO will not be used). It's supported by Agesic only. Take a look at the Agesic documentation and search for ForceAuth, for more details on this item.

Authentication Context: Leave it empty for SAP. For Agesic, use "Both". Take a look at the Agesic documentation and search for RequestedAuthnContext, for more details on this item.

Local Site URL: Configure the URL used to register your application (Service Provider) in the IdP (e.g.: http://testgamagesic.com:8080/gamlogin)

Tip: Using tomcat, you can edit the server.xml file under the conf directory, and add the following Context tag (inside the Host tag), so the real URL can be changed to what you have configured in the IdP. In this example, the TestGamAgesicJavaEnvironment servlet directory is changed to /gamlogin:
<Context reloadable="true" privileged="true" path="/gamlogin" docBase="TestGamAgesicJavaEnvironment" />

Credentials tab

To use SAML authentication, it is necessary to have signature certificates. There are two Sections in this Tab:

  • Request Credentials: These are the credentials to acces the Keystore that contain the signature certificates to make the request.
  • Response Credentials: Just as we have keys to sign the request, the Identity Provider gives to us the keys to validate his signatures also. These keys must be added in a TrustStore. In this section the credentials to access the TrustStore are configured.

image_20181112211452_1_png

See HowTo: Generating certificates for authenticating using SAML 2.0 GAM Authentication for information on how to generate the certificates and what to complete on each field.

User Information tab

Once authenticated correctly, the Identity Provider returns an assertion containing the user's data. Each provider returns the data using a different criteria. In this tab you must enter the mapping from the assertion data to the GAM data.

For additional user information returned in the IdP assertion - which is not listed under the User Information tab -, you can add it using the grid below the "Custom User Attributes" section. That information will be stored as extended properties for the GAM User.

You should add the Attribute Name that will be stored in the GAM database, plus the Attribute tag coming in the assertion.

image_201811131254_1_png

Having an SSO behavior

If you have more than one Service Providers (apps), all of them in a web SSO system, you can implement the SSO by doing some changes to the GAMSSOLogin object of the GAM Examples. In the Start event, it checks if there's a valid session, and if not, it should try to login automatically to the SAML Provider.

Take a look at this code (included at the Start Event):

&isRedirect = False
    //Gets last error in the GAM /////////////////////////////
    &Errors = GAMRepository.GetLastErrors()
    If &Errors.Count > 0  AND  &Errors.Item(1).Code <> GAMErrorMessages.UserMustBeAuthenticated
        Do 'DisplayMessages'
    Else
        &SessionValid = GAMSession.IsValid(&Session, &Errors)
        If &SessionValid and not &Session.IsAnonymous
            &URL = GAMRepository.GetLastErrorsURL()
            If &URL.IsEmpty()
                GAMApplication.GoHome()
            Else
                Link(&URL)
            Endif
        Else
            &AdditionalParameter.AuthenticationTypeName = !"SAML20"
            &LoginOK = GAMRepository.Login(&UserName, &UserPassword, &AdditionalParameter, &Errors )
            &Errors = GAMRepository.GetLastErrors()
            If &Errors.Count > 0
                Do 'DisplayMessages'
            Endif
        Endif
    Endif

You can set the GAMSSOLogin object as the Login Object for Web so as it's called automatically when the web session fails. If there is a valid session in the IdP, the user won't need to login again and the local GAM session will be renewed. Otherwise, the user is redirected to the IdP to login, and then al local session is created in GAM.
While the local GAM session is valid, the user won't be asked to login. The session timeout es governed by GAM (see Security Session Management in Applications using GAM).

Availability

Since GeneXus 16 upgrade 1 for Java only.

Considerations

By default, the Artech.Security.Saml.jar connector does not generate tracing information. In order to have tracing info, create a file named "simplelogger.properties" under your servlet's server installation, at \WEB-INF\classes directory, containing the following lines:

# It has to be one of these ("trace", "debug", "info", "warn", "error" or "off"). The default value is "info".
org.slf4j.simpleLogger.defaultLogLevel = debug

# The output can be writen to any file or to the standard output (the default is the standard output).
# org.slf4j.simpleLogger.logFile

org.slf4j.simpleLogger.showDateTime = true

# The date and time format to be used in the output messages. The pattern describing the date and time format is defined by SimpleDateFormat.
org.slf4j.simpleLogger.dateTimeFormat = dd-MM-yyyy hh:mm:ss

See also

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