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 (SP) 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.

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.
 

SAMLConfGeneralTab

  • Local Site URL: Configure the URL used to register your application (Service Provider) in the IdP. The URL has to be of the format: protocol://domain:port/<virtual directory> (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" />

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

How to check the Service Provider Entity ID in the Provider's configuration? This is the <Issuer> of the SAML request.

  • In the Identity Provider Entity Id field, complete the Entity Id given by the Provider's (IDP). The completion of this field is necessary only for .NET applications.

How to get the Identity Provider Entity Id in my SAML Provider?  This is the <Issuer> of the SAML response.

  • Execute SAML Requests using GET

    How to get this information in the SAML Provider? It corresponds to the ProtocolBinding attribute of the requests. Furthermore, this property is directly associated with the http method with which the request is made to the IDP.

The General tab has two specific sections:

Login

  • There is the SAML Endpoint Location field, where the location of the Identity Provider's endpoint must be configured in order to login.

How to know the SAML Endpoint Location of my SAML Provider? Take a look at the Provider's documentation, and look for the "Destination". The Destination concept is explained in this link.

  • Name ID Policy format

    Some identity providers restrict the format of the NameID policy. Here select the correct value according to the requirements of the IDP.
     
  • 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 some identity providers only. 

How to know the Force Authentication of my SAML Provider? Look at this link where the Force Authn attribute is explained. Then you can go for that information at your SAML Identity Provider.

  • Authentication Context: Some possible values are SMARTCARD_PKI_AUTHN_CTX and PPT_AUTHN_CTX. The first value corresponds to SmartcardPKI, and the second to PasswordProtectedTransport. Check the provider's documentation to know the value to be configured in this property.

How to know the Authentication Context of my SAML Provider? Look at this link where the AuthnContext attribute is explained.

Logout

  • Disable Single Logout
    If this property is checked, Single logout (SLO) is not executed, which means that the logout is done in the SP exclusively (not at the IdP).
     
  • 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.


How to know the Single Logout Endpoint of my SAML Provider?  It's the Destination of the logout request. The Destination concept is explained in this link.

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

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.
    In the case of Java applications, these keys must be added in a TrustStore. The credentials to access the TrustStore have to be configured in this section in that case.


Java generated application example:

In the case of Java applications, the Response credentials have to be in a TrustStore so you have to open the "Advanced configuration" to set the TrustStore information.

image_2019314125444_1_png

.Net generated application example:

In the case of .NET apps, the Response credentials have to be a .cer file (without using a TrustStore).

image_2019314124740_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

Configuration in the Identity Provider

Basically, you need to configure:

Assertion Consumer Service Endpoint / Assertion Consumer Service Location / Single Sign On Service Endpoint (different names which can be used by the Provider)

  • Java:  https://<domain>/<base_url>/saml/gam/signin
  • Net: https://<domain>/<base_url>/Saml2/Acs

Single Logout Location  

  • Java or Net: https://<domain>/<base_url>/saml/gam/signout

Having an SSO behavior

See Howto: Having an SSO behavior using SAML Authentication

Availability

As of GeneXus 16 upgrade 1 for Java only.

Since GeneXus 16 upgrade 3 it's available for NET applications also. SAC 42156

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