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:

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

SAML is a secure XML-based communication mechanism for communicating identities between organizations. It's the acronym for Security Assertion Markup Language. The main use case that SAML solves is SSO, so it avoids the need to maintain multiple credentials in multiple locations, and it increases security while decreasing administration timing tasks.
Another benefit in using SAML is the possibility of a federated identity for 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 for referring 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 for authenticating users. For authenticating, the IdP may request some information from the user - such as user name and password (though it could be any authentication method). Then, the IdP generates an authentication assertion (i.e. a statement used by service providers to make access-control decisions), to indicate that a user has been authenticated.

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

In sum, the behaviour implies that, when there is no valid session, the user is redirected to the IdP login page. After logging in, the user is redirected to the application again. Within the same browser, when another Service Provider tries to login using the same IdP, if there is a valid session already, then the user will not be required 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 be connected.

In the following figure, Agesic has been used as an example:

image_20181112154720_1_png

Tab General

Basic identification information of the application in SAML 2.0. All this information should be completed following a service agreement with the SAML Provider. For 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 specific sections:

  • Login: In this section, configure the Service Provider Entity ID, which is an identifier of your application in the Identity Provider. It is configured in this field, as well as 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: the Single Logout Endpoint is configured in this section. It works just like the SAML Endpoint Location, except that, in this case, indicating the location to logout.

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

image_20181112154922_1_png

Force Authentication = TRUE means that every time that a login is required on a different Service Provider, the IdP will request the user to enter credentials again (SSO will not be used). It's supported by Agesic only. For further details on this item, take a look at the Agesic documentation, and search for ForceAuth.

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

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 may edit the server.xml file under the conf directory, and add the following Context tag (inside the Host tag), so that the real URL may 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

Using SAML authentication requires signature certificates. There are two Sections in this Tab:

  • Request Credentials: these are the credentials to access the Keystore that contains the signature certificates to make the request.
  • Response Credentials: just as we have keys to sign the request, the Identity Provider provides us with the keys to also validate its signatures. These keys must be added in a TrustStore. The credentials to access the TrustStore have been configured in this section.

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 should be completed in each field.

User Information tab

Once duly authenticated, the Identity Provider returns an assertion containing the user's data. Each provider returns the data according to varied 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 may add it by 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, in addition to the Attribute tag included in the assertion.

image_201811131254_1_png

Having an SSO behavior

If you have more than one Service Providers (apps), and all of them are in a web SSO system, you may implement the SSO by introducing some changes to the GAMSSOLogin object of the GAM Examples. In the Start event, it will verify whether there is a valid session or not. 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 may set the GAMSSOLogin object as the Login Object for Web, which is called automatically when the web session fails. If there is a valid session in the IdP, the user will not need to login again, and the local GAM session will be renewed. Otherwise, the user will be redirected to the IdP for login, and a local session will be created in GAM.
While the local GAM session is valid, the user will not be requested to login. The session timeout es governed by GAM (see Security Session Management in Applications using GAM).

Availability

As of 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 called "simplelogger.properties" under your servlet's server installation, at \WEB-INF\classes directory, with 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.