Introduction / FirstSpirit Server configuration / Establishing SSO via the FS-SAML-Login-Module

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.

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

Important 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}

User section information mapping

user.section

${saml:SessionIndex}
${saml:SessionNotOnOrAfter}
${saml:NameIDFormat}

   

(*) 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

Before commissioning SAML, please activate logging for the FirstSpirit SAML login module.

Debug logging must be activated at the point where the login is processed. This is either the web server itself (e.g., Tomcat) or, if using the Jetty module, the FirstSpirit Server:

#SAML
log4j.logger.de.espirit.firstspirit.authentication.saml.SamlLoginModule=DEBUG
log4j.logger.com.onelogin=DEBUG

If debug logging is activated, each SAML request and each SAML response is issued as XML in the corresponding log file (e.g., in the Tomcat log).

Important 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

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.

© 2005 - 2023 Crownpeak Technology GmbH | All rights reserved. | FirstSpirit 2023.2 | Data privacy