Skip to content

Quick configuration of the SAML plugin

Major changes introduced in version 10.1.0

The 10.1.0 release makes important changes to the SAML plugin that require an update of the configuration. If you are upgrading from a lower version, please refer to Changes from version 10.1.0.

Info

This procedure is intended for regular users. Please refer to the main documentation page in case of problems.

Configuration

This section details the configuration steps required to install the SAML plugin. It covers the main actions to be performed, as well as the options available.

The steps required to install the plugin are as follows:

  1. Deploy the binary;
  2. Private key and certificate generation;
  3. IdP configuration and metadata retrieval;
  4. Application configuration;
  5. Start SquashTM.

1. Deploying the binary

From the folder $SQUASH_HOME/plugin-files/saml/security.saml-X.Y.Z/plugins, copy the file .jar and paste it into the same folder in the application SquashTM $SQUASH_HOME/plugins/.

2. Private key and certificate generation

Creation of the private key in format PKCS8

Starting with version 10, SquashTM no longer uses keystores to store private keys and certificates. It is therefore necessary to generate a private key in PKCS8 format and a certificate for the configuration of the SAML plugin.

The following command generates a private key in format PKCS8: 

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private_key.pem

Export certificate for import into metadata

Then, the following command allows to export the private key as a certificate valid for one year (adjust the duration if necessary): 

openssl req -x509 -new -key private_key.pem -sha256 -days 365 -out squashtm.cer

3. IdP configuration and retrieval of its metadata

Connect to the IdP or ask the supplier for the URL of the IdP's metadata.

Either an XML file such as FederationMetadata.xml will be available, or a URL giving access to this file (often both). The latter must be retrieved, as SquashTM needs it to get started.

Make sure that the entityID is correctly declared on the IdP, as defined in the SP metadata file.

Using the "hard" file

  1. Download the file into $SQUASH_HOME/conf/saml/ with wget or curl and call it FederationMetada.xml if you have not already;
  2. Note the file path;
  3. Give SquashTM read access to the file.

URL declaration

  1. Retrieve URL;
  2. Test it from the SquashTM server (wget or curl);
  3. Save it for the next step.

4. Application configuration

Using a dedicated file

  1. Copy the file config/squash.tm.cfg-saml.properties and paste it in the already declared configuration directory, which is usually SQUASH_HOME/conf;

  2. Then edit the main configuration file SQUASH_HOME/conf/squash.tm.cfg.properties and associate it with the plugin configuration file, adding/editing the following property:

    spring.profiles.include=saml

If this property was already present, you can add saml to the list, separated by a comma.

(Alternative) Property integration

For convenience, you can simply copy and paste the contents of the plugin configuration file into the main configuration file, without having to add SAML to the list of profiles.

Minimum configuration

The configuration file contains many properties, but only some of them are mandatory. SquashTM will not start up / run correctly if these properties are left empty or not filled in correctly.

The properties listed below are required. Details (permitted values, etc.) are available in the comments of the squash.tm.cfg-saml.properties file, and later in this documentation.

saml.enabled: Main switch. This property allows the plugin to be activated or disabled without comment and without having to delete the jar file;

saml.idp.metadata-url: The location of the identity provider's metadata. The protocols file://, http://, and https:// are allowed. For example, file:///opt/squash-tm/conf/saml/FederationMetadata.xml or https://login.microsoftonline.com/entreprise.onmicrosoft.com/FederationMetadata/2007-06/FederationMetadata.xml;

saml.sp.registration-id: Unique identifier used to register your service provider (SP) in the plugin's SAML configuration. For example: google.

saml.sp.entity-id: Unique identifier of the SquashTM instance. This value must be unique within your authentication ecosystem and will be communicated to the IdP (identity provider). For example: urn:squash-tm:saml or https://squash-tm.your-organization.com/saml;

saml.sp.metadata.private-key: Private key in PKCS8 format used by the service provider (SP) to sign requests and decrypt messages;

saml.sp.metadata.certificate: Service provider (SP) X.509 certificate used for signature validation and encryption.

Advanced configuration

SquashTM is often behind a reverse proxy. If this is the case, use the following options:

  • saml.proxy.enabled: Set to true;
  • saml.proxy.server-name: Set URL to squash.domaine.fr;
  • saml.proxy.scheme: Set https in general;
  • saml.proxy.server-port: Set to 443 in general;
  • saml.proxy.include-port-in-url: Set to true.

5. Starting SquashTM

Start SquashTM and monitor the logs. The logs should display a few lines containing the word "SAML" and also the message "Started SquashTM in XX.XXX seconds";

6. Transmitting SP metadata to the IdP

Metadata from service provider is now generated automatically when the application starts and are accessible via the URL: /auth/saml/metadata/{registration-id} where registration-id is the value of the saml.sp.registration-id property.

Focus

You must pass this metadata to your identity provider for the SAML connection to work properly.

Conventions

File paths format

Metadata can be retrieved by reading it as local or remote files via HTTP(S) calls using the saml.idp.metadata-url property.

Via HTTP(S): the file path is the URL from which it can be downloaded. The protocol is either http:// or https://. Example: https://votre.idp/metadonnees.xml.

Via an absolute path: URL leading to a local file that works well as an absolute path. In this case, the protocol is file://. Example: file:///dev/squashtm/saml/idp.xml (under Linux), file://C:/dossierappli/squashtm/conf/idp.xml (under Windows).

Via a relative path to the configuration folder: Any path that does not have a defined protocol will be considered a relative path to the configuration folder. The location of the configuration folder may vary according to the environment and installation mode chosen for SquashTM. Example: saml/idp.xml becomes $CONF_DIR/saml/idp.xml.

Changes introduced in version 10.1.0

With the release 10.1.0, significant changes have been made to the SAML plugin configuration. These changes must be taken into account in order to ensure the proper functioning of the application, by updating the configuration file.

1. New mandatory properties

New properties are now required to allow the application to start:

Property Description
saml.sp.registration-id SAML Record ID (e.g.: okta, azure-ad)
saml.sp.metadata.private-key Private key in SP format PKCS#8 for signature and decryption
saml.sp.metadata.certificate SP Certificate X.509
saml.idp.metadata-url URL of the XML file provided by the IdP (replaces saml.idp.metadata.url)

2. End of keystore support

The use of a keystore JKS is no longer supported. Configuration is now based only on:

  • a private key (in PKCS#8 format) to sign the SAML requests sent to the identity provider and decrypt the encrypted assertions received.
  • a X.509 certificate communicated to the identity provider, allowing for verification of request signatures and encryption of assertions.

The identity provider's certificates are automatically retrieved from the XML metadata file provided by the identity provider.

Below how to extract your private key and certificate from a keystore.jks.

Step 1: Convert JKS to PKCS#12

keytool -importkeystore \
  -srckeystore keystore.jks \
  -destkeystore keystore.p12 \
  -deststoretype PKCS12 \
  -srcalias <alias> \
  -deststorepass <mot_de_passe> \
  -srcstorepass <mot_de_passe>

Step 2: Extract private key (PEM format)

openssl pkcs12 -in keystore.p12 -nocerts -nodes -out key.pem

Step 3: Convert private key to PKCS#8

openssl pkcs8 -topk8 -inform PEM -outform PEM -in key.pem -out private_key.pem -nocrypt

Step 4: Export certificate for import into metadata

Then, the following command allows to export the private key as a certificate valid for one year (adjust the duration if necessary): 

openssl req -x509 -new -key private_key.pem -sha256 -days 365 -out squashtm.cer

3. Transmitting SP metadata to the IdP

Metadata from service provider is now generated automatically when the application starts and are accessible via the URL: /auth/saml/metadata/{registration-id} where registration-id is the value of the saml.sp.registration-id property.

Focus

You must pass this metadata to your identity provider for the SAML connection to work properly.

4. Unique XML load for identity provider metadata

Overloading identity provider metadata configurations via properties is no longer supported. The identity provider configuration is based exclusively on the XML metadata file, all necessary information (certificates, endpoints, etc.) are automatically extracted from it.
As a result, all saml.idp.* properties except for saml.idp.metadata-url are no longer available.

5. SAML endpoints change

The SAML endpoints now require the presence of the parameter registrationId in the URL, the latter should correspond to the value of the property saml.sp.registration-id.

Former endpoint New endpoint
/auth/saml/login /auth/saml/login/{registration-id}
/auth/saml/SSO /auth/saml/sso/{registration-id}
/auth/saml/metadata /auth/saml/metadata/{registration-id}