Setting up SSO via the FirstSpirit SAML login module
General information on SAML 2.0
| Table of contents |
The Security Assertion Markup Language (SAML) in version 2.0 is an XML-based framework which enables security-related information to be exchanged based on a browser. This means that information regarding identity, attributes, and permissions of an entity (usually a user) can be used jointly within a company or even between companies. Among other things, single sign-on can be implemented in conjunction with other tools. SAML V2.0 was developed by OASIS (Organization for the Advancement of Structured Information Standards). A technical overview of SAML V2.0 can be found here: Technical overview of OASIS.
Module description
Graphical overview of the login process (simplified)
The FirstSpirit SAML login module supports “single sign-on” (SSO) login in FirstSpirit via the SAML V2.0 standard. This means there is no direct login via FirstSpirit, as was previously the case. Instead, login takes place via an identity provider supported by the SAML login module.
If the user wants to connect to FirstSpirit (--> service provider) in the browser, the authentication request is forwarded to the SAML login module. Here, a SAML request is established and forwarded to an identity provider via the browser. This provider handles the request. If the user is already logged in via a valid session, a SAML response is sent to the SAML login module via the browser. If the user is not logged in, authentication is carried out via the identity provider, then the SAML response is sent. The response is then processed by the module and the user is logged into FirstSpirit. The data containing the response is saved in FirstSpirit and, if necessary, the user is recreated here.
Restrictions
A number of restrictions need to be taken into account when using the module:
- When using the SAML login module, it is important to note that only the login process is carried out. There is no communication between the module and the identity provider regarding the user logout process. This means that if the user logs out of the identity provider, this will have no direct impact on their FirstSpirit login. Likewise, if the user logs out of FirstSpirit, they will not be logged out of the identity provider and their session will also not become invalid.
- The API used, OneLogin's SAML Java Toolkit, only offers “single group / role attributes”.
- Only one identity provider can be configured via the FirstSpirit Server in each case. Different identity providers cannot be configured for each project.
- Parsing and generating (service provider or identity provider) SAML XML metadata is not implemented.
Installing and setting up the module
Installing via ServerManager
First, the required version of the module is installed via ServerManager (see also Modules).
fs-saml.conf configuration
Configuration can be carried out via the “Configure” button in FirstSpirit ServerManager or directly via the fs-saml.conf file.
Configuring global web apps
Once the module has been installed, the web component still has to be added to the global web apps (see also Web applications).
Setting up authentication via JAAS
FirstSpirit uses the Java standard JAAS (Java Authentication and Authorization Service) to authenticate its users. Several JAAS login modules are already integrated in FirstSpirit and provide various methods of user authentication.
To use the SAML login module, the fs-jaas.conf configuration file has to be adapted (see also Login process configuration (fs-jaas.conf)):
/* FirstSpirit start page with SSO: ContentCreator, SiteArchitect */
websso {
de.espirit.firstspirit.server.authentication.FSTicketLoginModule sufficient;
de.espirit.firstspirit.server.authentication.LdapLoginModule optional section="LDAP";
de.espirit.firstspirit.server.authentication.FSUserLoginModule optional;
de.espirit.firstspirit.authentication.saml.SamlLoginModule sufficient;
};
The fs-jaas.conf file contains all login modules which have been configured for this application. If several login modules are entered, these are processed in the specified order until the user is authenticated successfully. In addition, the overall authentication behavior can be controlled via the specified login modules using the required, sufficient, optional, and requisite flags.
 |
The SAML login module must be in the last position in the fs-jaas.conf file! |
Background: The SAML login module executes a redirect in the browser. The SAML request is forwarded to the identity provider via the browser. This redirect should only take place if authentication (via another login module) has not previously been successful.
For the example specified above, this means:
- First, login via the FSTicketLoginModule is attempted. An authorization ticket that was previously generated by the FirstSpirit Server is sufficient for authentication. The ticket is generated during login on the FirstSpirit start page and forwarded via the web browser. This method is the standard method following FirstSpirit installation. The sufficient flag ensures that the other login modules no longer run if login is successful. If login fails, an attempt is made using the next login module.
- The LdapLoginModule (authentication against an external LDAP server) followed by the FSUserLoginModule (authentication against the FirstSpirit-internal user database) are run in the next step. The optional flag ensures that the next login module in the list is called irrespective of whether login is successful or fails here.
- SamlLoginModule (sufficient): Lastly, the authentication request is forwarded to the SAML login module. If the previous modules have not executed a successful login, a SAML request is established via the SamlLoginModule and forwarded to an identity provider via the browser. This provider handles the request. If the user is already logged in via a valid session, a SAML response is sent to the SAML login module via the browser. If the user is not logged in, authentication is carried out via the identity provider, then the SAML response is sent. The response is then processed by the module and the user is logged into FirstSpirit. The data containing the response is saved in FirstSpirit and, if necessary, the user is recreated here.
Configuration parameters
Variable substitutions are made in the module configuration:
# The following variable substitutions are available in parameter values:
# ${saml:NameID} - the NameId of the SAML login
# ${saml:NameIDFormat} - the NameId format of the SAML login
# ${saml:SessionIndex} - the SessionIndex of the SAML login
# ${saml:SessionNotOnOrAfter} - the SessionNotOnOrAfter value of the SAML login, ISO-8601 compatible
# ${saml:attributeName} - a SAML assertion attribute value
# ${fs:propertyName} - a FirstSpirit server configuration property
# ${request:URL} - current HTTP request URL. The returned URL contains a protocol, server name, port number, and server path, but it does not include query string parameters.
# ----- ----- ----- ----- -----
# Signatures and encryption is only available if a keystore and the key parameters are configured
These variables either come from the FirstSpirit Server configuration or are attributes of the SAML login process.
In the configuration, the keystore should be uploaded (“Update keystore file” button – see also Configuring the keystore), and ID and URL parameters for the identity and service providers should be configured (see Configuring the identity provider). Any lines with variable substitutions that are not required should be commented out.
|
Further points of reference for the individual configuration can also be taken from the SAML metadata. |
There are two types of configuration parameter:
The variables described previously mainly relate to the user-specific parameters and are evaluated during every login process. This also means that the user attributes are updated in FirstSpirit with respect to the SAML attributes.
Global parameters
Brief description | Parameter name | Possible values * |
|---|---|---|
Keystore password | keystore.password | String |
Identity provider public certificate alias | key.idp.alias | String |
Keystore type | keystore.type | jks / pkcs12 |
Service provider private key and public certificate alias | key.sp.alias | String |
Service provider private key password | key.sp.password | String |
Identity provider identifier | idp.entityid | String |
Identity provider single sign-on service url | idp.sso.url | String |
Service provider identifier | sp.entityid | ${fs:URL} |
Service provider assertion consumer service url | sp.assertion.url | ${fs:URL} / ${request:URL} |
Algorithm used for service provider signing purposes | saml.signature.algorithm | rsa-sha1 / dsa-sha1 / rsa-sha256, rsa-sha384 / rsa-sha512 |
If the service provider expects a NameID | saml.want.nameid | true / false |
NameID format | saml.nameid.format | urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified |
If the service provider expects a NameID to be encrypted | saml.want.nameid.encrypted | true / false |
The requested AuthNContext sent in the AuthNRequest by the service provider, comma separated list, empty for none | saml.requested.authncontext | urn:oasis:names:tc:SAML:2.0:ac:classes:Password |
The AuthNContext comparison parameter, defaults to 'exact' | saml.requested.authncontext.comparison | exact |
If the service provider expects assertions to be encrypted | saml.want.assertions.encrypted | true / false |
If the service provider expects assertions to be signed | saml.want.assertions.signed | true / false |
If the service provider expects messages to be signed | saml.want.messages.signed | true / false |
Create or update user from the SAML attributes (true) / Authenticate existing FirstSpirit user only (false) | import.user | true / false |
(*) Note: The values listed here serve as examples only. In an individual configuration, any values that deviate from these examples are possible and logical.
User-specific parameters
Brief description | Parameter name | Possible values * |
|---|---|---|
User login mapping | user.login | ${saml:NameID} |
User email mapping | user.email | ${saml:email} |
User phone number mapping | user.phone | ${saml:phone} |
User abbreviation mapping | user.abbreviation | ${saml:initials} |
Full user name mapping | user.realname | ${saml:givenName} ${saml:surname} |
User groups mapping, comma separated list of group names | user.groups | ${saml:groups} |
Match mode for external group names | group.match.mode | contains (default) |
External group name mapping, allows you to add a prefix or suffix to a SAML group name | group.name | ${saml:groupName} |
User section information mapping | user.section | ${saml:SessionIndex} |
(*) Note: The values listed here serve as examples only. In an individual configuration, any values that deviate from these examples are possible and logical.
Further configuration
Configuring the identity provider
To ensure that the SAML authentication works, the configuration of the identity provider must always be adapted. To set up a trust relationship between the service provider (here: FirstSpirit) and an identity provider:
- at least the client ID (freely selected in the configuration) and
- the URL of the FS root web application must be communicated to the identity provider.
It is not possible to provide a full manual at this point.
Please consult the manual for the identity provider being used.
Configuring the keystore
The SAML request and SAML response must be signed. The certificates required must be stored in the configuration of the identity provider and the configuration of the service provider.
The certificate and the private key of the service provider can either be created with Java Keytool or with a function that the identity provider offers itself. Certain identity providers, such as Keycloak, provide a function for creating, exporting, and using the keystore directly.
Detecting and rectifying problems
Activating debugging
For debug logging, Java-Util-Logging (JUL) is used. It must be activated at the point where the login is processed. This is either the web server itself (e.g., Tomcat, logging.properties file in conf directory) or, if using the Jetty module, the FirstSpirit Server (fs-server.conf):
#SAML
de.espirit.firstspirit.authentication.saml.level = FINE
com.onelogin.level = FINE
If debug logging is activated, each SAML request and each SAML response is issued in the corresponding log file (e.g., in catalina.*.log under tomcat/log or fs-server.log when using Jetty).
|
For debugging, encryption of SAML messages should be disabled. If HTTPS is used, a second encryption is usually not necessary. After successful commissioning, the encryption can be reactivated. |
Support from the SAML Developer Tools
If authentication is not successful via the FirstSpirit SAML login module, there may be various reasons for this. When searching for the cause of the error and analyzing the debug outputs (SAML request and response), the following SAML Developer Tools can provide assistance:
https://www.samltool.com/online_tools.php
- Step 1) Base64 Decode + Inflate
- Step 2) XML Pretty Print
Possible causes of errors
If the response does not arrive
When the debug outputs are analyzed, the following happens when the authentication request is made to the SAML login module:
- a SAML request is established and
- it is forwarded to an identity provider via the browser (in this case, the login form is visible in the browser),
- but the SAML response does not arrive in Tomcat
Possible causes of errors:
1) The configuration of the identity provider is missing or is incorrect (see Configuring the identity provider)
2) The configuration of the proxy and/or the firewall is missing or is incorrect
If the response arrives but does not contain any assertions
When the debug outputs are analyzed, the following happens when the authentication request is made to the SAML login module:
- a SAML request is established and
- it is forwarded to an identity provider via the browser (in this case, the login form is visible in the browser), and
- the SAML response also arrives in Tomcat, but instead of the assertions (user attributes), it only contains a status code with an error message
Possible causes of errors:
1) The configuration of the identity provider is missing or is incorrect (see Configuring the identity provider)
2) The attribute mapping of the SAML assertions to FirstSpirit is incorrect. In this case, it helps to look at the assertions of the SAML response and then to adapt the mapping configuration in FirstSpirit accordingly.
If the signature check of the request and response fails
Possible causes of errors:
1) The configuration of the keystore is missing or is incorrect (see Configuring the keystore)
2) The certificates for signing are not stored in the configuration of the identity provider and/or in the configuration of the service provider.