GeneXus Access Manager (GAM) allows you to authenticate using any SAML 2.0 provider.
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 of 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.
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 (for example: a statement used by service providers to make access-control decisions), to indicate that a user has been authenticated.
For more information, read SAML v2.0 Technical overview.
In sum, the behavior 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.
First, define a new GAM Authentication Type SAML 2.0. It requires a detailed configuration of the protocol, following the documentation of the Identity Provider to which you wish to be connected.
Note: The values specified in the images below are merely illustrative and may change depending on the identity provider.
To configure a SAML 2.0 Authentication Type, open the GAM Web Backoffice and follow these steps:
- Go to Settings.
- Open Authentication Types.
- Click ADD and select SAML 2.0.
This opens the configuration window described below (General, Credentials, Signin, User Information, Roles, and Signout tabs).
This section contains the basic identification information for the application in the SAML 2.0 flow. You should complete these fields according to the service agreement you establish with the SAML provider.
Service Provider Entity ID: 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.
- IDP Entity ID: Entity Id given by the Provider's (IDP).
- Assertion Consumer Service (Callback URL): Configure the URL used to register your application (Service Provider) in the IdP.
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" />
- Custom redirect URL?: Specifies whether you will implement a custom callback URL.
This tab allows you to configure the certificates and keys required to sign requests and validate responses during the SAML 2.0 authentication flow.
- Use base64's private key: Specifies a Base64-encoded private key for signing SAML requests, if enabled, do not specify a value in the KeyStore Path property.
- KeySore path: Defines the location of the KeyStore file (.jks for Java with absolute path, .pfx for .NET with absolute or relative path to /web directory) containing the private key and certificate for signing SAML authentication requests.
- Keystore Password: Password required to access the KeyStore file (required for protected .jks or .pfx files).
- Key alias credential: Identifies the key entry alias used for signing (mainly relevant for Java KeyStores that may contain multiple certificates).
- Use IDP's base64 certificate: Enables the use of the Identity Provider's public certificate in Base64 format, used to verify the authenticity and integrity of SAML responses received from the IDP, if enabled, do not specify a value in the Certificate Path property.
- Certificate Path: Specifies the path to the IDP's certificate file (alternative to Base64 format) used to validate SAML response signatures.
Below is an example of GeneXus code on how to obtain the base64 private key from a .pkcs12 file. The code is analogous to a file with the extension .jks, .pfx, or .p12.
&Path= "<path_to_file>\sha256_cert.pkcs12"
&PrivateKey.LoadPKCS12(&Path, "1", "dummy")
&b64 = &PrivateKey.ToBase64()
msg("base 64: " + &b64, status)
&Certificate.LoadPKCS12(&Path, "1", "dummy")
&b64cert = &Certificate.ToBase64()
msg("base 64 cert: " + &b64cert, status)
This tab defines how the application communicates with the Identity Provider during the SAML 2.0 sign-in process.
- Saml Endpoint Location: Defines the IDP's Single Sign-On endpoint URL where SAML authentication requests are sent (found in IDP metadata).
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.
- Policy format: Specifies the NameID format that determines how the IDP should identify the user in SAML responses (for example: email address, persistent identifier). Some Identity Providers restrict the format of the NameID Policy. Here select the correct value according to the requirements of the IDP.
- Force Authentication: If enabled 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.
Allows to configure the mapping between SAML assertion attributes from the IDP and GAM user properties. This configuration is essential because the Identity Provider sends user data as claims/attributes in the SAML response, and each IDP may use different attribute names for the same information (for example: 'email' vs 'emailaddress' vs 'mail').
These mappings define how user information from the authentication response is automatically stored in the corresponding GAM user fields.
It is also possible to map custom user attributes, in case the standard fields do not include user information necessary for the business.
This tab defines the SAML attribute name in the authentication response that contains the user's roles, enabling automatic role assignment in GAM based on IDP group memberships.
In the configuration shown, 'roles' is specified as the Role External ID Tag. This means GAM will search the SAML response for <saml:Attribute Name="roles"> and extract its values.
For example, if the XML contains:
<saml:Attribute Name="roles">
<saml:AttributeValue>Admin</saml:AttributeValue>
<saml:AttributeValue>Manager</saml:AttributeValue>
</saml:Attribute>
GAM will automatically assign both 'Admin' and 'Manager' roles to the authenticated user.
Note: If you want to map external roles, you must specify “Authentication and Roles” in the general configuration of the authentication type.
The signout tab allows you to configure Single Logout (SLO) settings for SAML, enabling users to log out from both the application and the Identity Provider simultaneously. When SLO is enabled, the application sends a logout request to the IDP's Single Logout endpoint, ensuring the user's session is terminated across all federated services.
- Enable SLO?: Specifies whether Single Logout functionality is enabled, determining if logout requests should be sent to the Identity Provider when users sign out from the application.
- Single Logout Endpoint: Defines the IDP's Single Logout Service URL where SAML logout requests are sent to terminate the user's session across all federated applications.
- Verificate signature: Indicates whether the signature of SAML logout responses from the IDP should be validated to ensure authenticity and prevent tampering.
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.
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)
- https://<domain>/<virtual_directory>/
saml/gam/callback
Single Logout Location
- https://<domain>/<virtual_directory>/
saml/gam/callback
Having an SSO behavior
See HowTo: Have an SSO behavior by using SAML Authentication.
HowTo: Generate certificates for authentication using SAML 2.0 GAM Authentication
HowTo: Configuring SAML 2.0 GAM Authentication type using SAP
HowTo: Configuring SAML 2.0 GAM Authentication type using Agesic
HowTo: Configure SAML 2.0 GAM Authentication type using Okta
Useful tool to inspect the SAML assertions: SAML Chrome panel