Skip to content

Quick configuration of the SAML plugin

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. Create keystore and SP metadata;
  3. IDP configuration and metadata retrieval;
  4. Application configuration;
  5. Start Squash TM with its new configuration;
  6. Trouble shooting;
  7. Validate SAML deployment once a user logs in and their metadata is correctly entered in Squash TM when their account is created, if this is automatic.

1. Deploying the binary

From the .zip or .tar.gz package containing the plugin, copy the .jar file from the plugins folder and paste it into the folder of the same name in the Squash TM application $SQUASH_HOME/plugins/.

2. Creating the keystore and SP metadata

Creating the keystore

The keytool command is available with Java JVMs or JDKs.

The following command creates an RSA key pair for Squash TM with the SHA256withRSA signature algorithm valid for ten years (adjust the duration if necessary): 

keytool -genkeypair -keyalg rsa -keysize 2048 -sigalg SHA256withRSA -alias squashtm -keystore keystore.jks -validity 3650`

where squashtm is the key alias and keystore.jks is the keystore name. If it does not already exist, the keystore will be created immediately, in which case you will need to answer the questions required to create it. Be sure to write down the passwords for the keystore and the key.

Export certificate for import into metadata

You can export a certificate from the keystore using the following command: 

keytool -export -rfc -keystore keystore.jks -alias squashtm -file squashtm.cer

Configuring the SP metadata file

The easiest way is to re-use the sp.xml file supplied as an example with the plugin.

The following fields need to be modified:

  • EntityID: the Squash instance identifier; must be unique among all service providers known to the IDP;
  • SP X.509 Cert (for signature and encryption): the Squash TM certificate that can be obtained as explained in Export a certificate.

Default values can be retained for other fields.

3. IDP configuration and metadata retrieval

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 Squash TM needs it to get started.

Make sure that the entityID is correctly declared on the IDP, as defined in the sp.xml 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 Squash TM read access to the file.

URL declaration

  1. Retrieve URL;
  2. Test it from the Squash 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. Squash TM 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 deactivated 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.metadata.url: The location of the Service Provider's metadata. The protocols file://, http:// and https:// are allowed. For example: file:///opt/squash-tm/conf/saml/sp.xml;

saml.keystore.url: The location of the keystore. Only the file:// protocol is allowed. For example, file:///opt/squash-tm/conf/saml/keystore.jks;

saml.keystore.password: The keystore password;

saml.keystore.credentials.<?>: The alias of a public/private key pair for Squash TM's encryption needs. The question mark ? represents an alias. The property value is the password for this key. This property can be repeated once for each key. If the procedure has been followed, set the value to squashtm;

saml.keystore.default-key: The key alias that Squash TM should use whenever a private key is required, unless another key is specified for this situation in the configuration file. The default key must of course be present in the list of identifiers. If the procedure has been followed, set the value to squashtm.

Advanced configuration

Squash TM 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 Squash TM

Start Squash TM and monitor the logs.
The logs should display a few lines containing the word “SAML” and end with “Squash TM Started in XXXms”.

6. Trouble shooting

  • It is sometimes necessary to import the IDP certificate into the keystore (Certificate formatting help): 

    keytool -import -trustcacerts -alias adfs -file $SQUASH_HOME/plugins/saml/adfs.cer -keystore $SQUASH_HOME/plugins/saml/keystore.jks`

  • The FederationMetadata.xml metadata file must be encoded in UTF-8 without BOM, otherwise it may cause problems reading it when Squash TM starts up (error message indicating empty IDP metadata).

    file FederationMetadata.xml or file -i FederationMetada.xml

    apt install icu-devtools

    uconv -f utf-8 -t utf-8 --add-signature FederationMetadata.xml > idp.xml

Conventions

File path format

Metadata and keystore can be retrieved for reading as local files or remotely via HTTP(S) calls using the properties saml.idp.metadata.url, saml.sp.metadata.url and saml.keystore.url.

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 Squash TM. Example: saml/idp.xml becomes $CONF_DIR/saml/idp.xml.