Skip to content

Configure Authentication Plugins

Squash TM plugins related to authentication must be further configured when it comes to the server. This page details all the required configurations for the following plugins: LDAP, Active Directory, and SAML.

LDAP and Active Directory

LDAP and Active Directory connectors allow you to externalize the management of authentication to Squash TM. The management of user permissions remains inside of Squash TM.

Configure LDAP and AD

LDAP and AD connectors support both simple and multi-domain configurations. You can find examples of standard configurations in the following files, in the plugin's 'config' folder:

  • Simple domain: squash.tm.cfg.properties

  • Multi-domain: multi-ldap(or ad).squash.tm.cfg.properties

After installing the LDAP or AD .jar files in Squash TM's 'plugins' folder, you must copy and paste this standard configuration in the file squash.tm.cfg.properties to complete it. You can find this file in Squash TM's 'conf' folder.

LDAP Connector Properties

The LDAP connector allows for a more advanced configuration thanks to the following properties:

  • authentication.ldap.server.url: directory URL. Can be ldap:// or ldaps:// for a secured connection
  • authentication.ldap.server.managerDn: ID with the permission to browse the directory when it cannot be browsed in anonymous mode
  • authentication.ldap.server.managerPassword: password of the user who has the permission to browse the directory
  • authentication.ldap.user.searchBase : location where you can find the users who will be able to connect to Squash
  • authentication.ldap.user.searchFilter : allows you to search the user's attribute, which will be their login in Squash

Use the LDAP Connector with an AD

You can use the LDAP connector to connect it to an AD and enjoy more advanced configuration options.

The configuration you must enter for an AD or LDAP connector is basically the same.
The main difference lies in the authentication property ldap.user.searchFilter:

  • For an AD, it generally is the attribute samAccountName or UserPrincipalName
  • For a LDAP directory, there are more possibilities: it can be uid, id, uniqueMember, etc.

Operate the Connection

To connect to Squash TM, you must create at least one user in the LDAP directory or AD with a login that is identical to the one of the default Squash TM administrator: "admin". With this user, you can then connect to Squash TM with an administrator profile. The administrator will then be able to add permissions for the other users.

Info

When you first use Squash TM, an administrator account is created. The login is "admin".

For other users to be able to connect to Squash TM using the LDAP connector or AD, they must be in the directory:

  • If the user is missing from the LDAP directory or AD, they cannot authenticate to Squash TM. The connection is impossible.

  • If the user is already in the LDAP directory or AD, they can authenticate to Squash TM. The password is managed by the directory, whereas project permissions are managed in Squash TM. Two cases are then possible:

    • The user already has a user account in Squash TM: when they log in, they will have the permissions that go with their account

    • The user does not have any user account in Squash TM: when they first log in, a user account is automatically created in Squash TM, but they will have no permission granted to them. Subsequently, permissions can be granted to them by a Squash TM administrator.

Focus

When authentication is delegated to a directory, passwords can no longer be managed in Squash TM. The options [Reset] password (administrator) and change [Local password] (user) are deactivated.

Multi-Sources Authentication

You can authenticate into Squash TM using multiple sources (directory + local)

For this:

  • Install and configure the LDAP or AD plugins

  • In the file 'squash.tm.cfg.properties', complete the following property by adding 'internal' as an authentication source:

    authentication.provider=ldap,internal
    

Users will then be able to connect to the app using accounts that are in the directory and Squash TM local accounts.

Autoconnect to Bugtrackers

In the precise case where the Squash TM and bugtrackers logins credentials are managed by the same directory service, you can activate autoconnect to bugtrackers in Squash TM. In the 'System Parameters' available from Squash TM's administration, you must activate the option that is in the block 'Automatic authentication to bugtracker at login".

Autoconnect

Once the option is activated, Squash TM tries to authenticate automatically the user on the different bugtrackers they are linked to via the projects they are authorized. The information saved in the "My Account" workspace are then ignored. If that option is deactivated, there is no attempt to automatically connect to the bugtracker. The login credentials taken into account are the ones entered in "My Account".

Uninstall LDAP and AD

To uninstall the plugins LDAP and AD, you have to:

  1. Stop Squash TM

  2. In the file 'squash.tm.cfg.properties', delete or comment using a # the specific configuration lines of the plugins

  3. Remove plugin .jar files from Squash TM's 'plugins' folder

SAML

Overview

The plugin SAML for adds a new authentication entry point for Squash TM. It brings the benefits of a centralized, secure authentication service and SSO facilities. It does not replace the default entry point (the login form) and users/administrators can keep using the former interface (which also can still benefit from AD/LDAP security plugins) if they need to.

SAML version is 2.0.

Requirements

SAML Plugin 1.2.0 requires Squash-TM version 1.19 and java 8.

Features

The following features are supported:

  • Web SSO,
  • Web SSO with holder-of-key profile,
  • SP or IDP-initiated SSO,
  • HTTP-POST, HTTP-Redirect, SOAP, PAOS and Artifact Binding profiles
  • Trust management using Metadata Interoperability or PKIX,
  • Metadata loading by local file or HTTP,
  • Support for scoping and authentication contexts,
  • Publication of SP metadata

Endpoints

The SAML Plugin exposes the following new endpoints:

  • /auth/saml/login : the SAML user authentication interface
  • /auth/saml/SSO : endpoint for SSO profiles, aka the Assertion Consumer Service (ACS)
  • /auth/saml/SSOHoK : endpoint for SSO Holder-of-Key profile
  • /auth/saml/metadata : the URI of the SP metadata
  • /auth/saml/SingleLogout : single logout URL

Remember that the application context path still applies, e.g. in the stock Squash-TM deployment the final URL would look like http://someserver:8080/squash/auth/saml/login

Limitations

SAML Plugin supports only one Service Provider and one Identity Provider metadata. Because of that there are no IDP discovery services: users are automatically redirected to the (only) known IDP. Finally, the plugin embeds no tools for SP metadata generation, you must use third-party tools for that.

Integrating Squash + SAML plugin to the environment

This figure illustrates the actors and resources involved in SAML interactions:

Interactions

Users: The users want to access business resources detained by the Service Provider, after successful authentication by the Identity Provider.

Identity Provider: The Identity Provider (IDP) holds the user directory. It is responsible for actually authenticating the users and, if successful, delivering authentication assertions if this occurred within a SSO conversation. The list of SAML services supported by the IDP are compiled and published in a file called IDP metadata, that defines which data will be traded and how.

Service Provider: The Service Provider (SP) is the actual server the user intend to interact with, in our case Squash-TM. It completely delegates authentication concerns to the IDP but still hold the authorizations. Like the IDP, it publishes its supported SAML features in the SP metadata.

SP/IDP Metadata: These files publish the SAML features supported by the server they describe. Their content notably list the endpoints, the preferred SSO bindings (HTTP-POST, redirect etc), which user information are expected (and their format), and certificates used for encryption and signature.

Keystore: The SAML plugin uses its own keystore, which is a regular JKS (PKCS#12) keystore yet distinct of that of the JVM. It holds the private keys for Squash TM usage, and the public keys of all other involved third-parties : the IDP, proxies (SSL offload) etc. Finally, it also contains root and CA involved in PKIX verification.

When starting up Squash first accesses the keystore, the SP metadata and the IDP metadata. The metadata for both SP and IDP can be retrieved either locally or remotely by HTTP(s) connection. In our example the SP metadata are available locally while the IDP metadata are downloaded directly from the Identity Provider. On the other hand the keystore can only be accessed locally. Ideally it should be hosted on the same machine.

The following step is metadata validation. This step mostly includes syntactic validation and metadata signature check, and optionally the certificates can also be checked for trust path and revocation (or you can simply assume them to be valid if you trust the source).

When all checks are done and good, Squash-TM sign its SP metadata and publish them for consumption by third parties. This is a good time to configure the Identity Provider and declare the instance of Squash-TM as a valid source of authentication requests and feed it with the SP metadata if necessary.

At this stage the plugin is operational. Squash-TM will interact with the Identity Provider directly or indirectly (via the user’s browser), depending on the SSO binding profile of choice. Squash-TM can also be configured to work with proxies if one sits between the two servers and direct communication is required (not shown).

Usage

Users can now authenticate on Squash-TM by the login form interface (/login) or the SAML SSO interface (/auth/saml/login). The configuration allows to designate either of them as the main interface. By default, unauthenticated users are automatically redirected to that main interface. If a user wishes to use the other interface (s)he can do so by explicitly accessing its URL.

On successful SAML authentication, the user context is created assuming the NameID transmitted with the authentication assertion as the login name (as defined in the metadata). The corresponding user account will be bound, otherwise it will be created with empty authorizations.

A user authenticated on Squash-TM with SAML cannot change his/her password in the user account preference page. However, an admin can define one for him/her in the user administration page. A user authenticated with the login form can change his/her password normally.

Configuration

This section details the configuration step for installing the SAML Plugin. Here we will focus on the main configuration actions and options. More is available for finer customization of metadata and SSO handling, those will be covered in the next section.

The necessary steps for installing the plugin are:

  • Deploying the binary,
  • Creating the keystore and SP metadata,
  • Configuring the application.

Deploying the binary

From the plugin zip package, copy the jar file located in the plugins directory and paste it in the same folder in Squash-TM.

Creating a keystore

SAML Plugin uses its own keystore, that centralize all cryptographic material used in SAML use-cases1. The keystore must include at least one public/private key pair for Squash-TM. Depending on the need of your PKI, the certificates of involved third parties and/or root and intermediate CA are also welcomed.

The tool of choice for that purpose is the keytool shipped with your jdk (ie $JAVA_HOME/bin/keytool). In this section we assume that the jdk provider is Oracle Hotspot. The full documentation is available at https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html.

Note: the key aliases for the certificates you install or create should be a non-blank, contiguous string of letters or digits, with hyphens or underscores as separators. In short, they should match [a-zA-Z0-9-]+.

Creating a public private key pair for Squash-TM

The following command will create a 2048 bytes RSA key pair for Squash TM with signature algorithm SHA256withRSA, valid for one year:

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

where ‘squashtm’ is the alias of the key and ‘keystore.jks’ is the name of the keystore. The keystore will be created on the fly if it doesn’t exist, in which case you need to answer the questions of the keystore creation utility. Remember to note down the passwords for the keystore and the key.

Info

You can define more than one key pair. The plugin allows using different keys for different usages (e.g., signing and encryption).

At this point the associated certificate is still self-signed. If this is fine by your policy, you can proceed to Exporting a certificate.

If you need the approval from a CA you can issue a CSR for that certificate by the following:

keytool -certreq -alias squashtm -keystore keystore.jks -file squashtm-csr.csr

then forward the request to the relevant authority. Once the request was processed, install the signed certificate as indicated in Importing a certificate.

(Optional) Install an external private key

In case the private key Squash-TM should use was generated elsewhere need to import it instead. The key must be provided as a .p12/.pfx file.

keytool -importkeystore \
    -srckeystore imported.p12 -srcstoretype PKCS12 -srcstorepass imported_pass \
    -srcalias key -srckeypass key_pass \
    –destkeystore keystore.jks -deststorepass dest_store_pwd \
    -destalias squashtm -destkeypass squashtmpassword
Exporting a certificate

You can export a certificate from your keystore with the following command:

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

Mostly you need this when generating the SP metadata (see below) and use it as the certificate used by Squash TM for signing/encryption purposes. Note the use of option -rfc, which outputs the certificate as a PEM (a plain base 64 text file of which you can copy/paste the content).

Importing a certificate

Third parties certificate can be imported as .cer/.crt files. Those include for example the root and intermediate certificates, or your CA-signed certificate if you obtained one. It also works for PKCS#7 bundles (.p7b files).

keytool -importcert -alias certname -file certificate.cer -keystore keystore.jks

Service Provider Metadata

The SAML Plugin is not shipped with Service Provider Metadata utilities. You will have to generate it using external tools.

Basic configuration

The following example uses the online OneLogin tool (https://www.samltool.com/sp_metadata.php), which offers basic metadata generation options. It can provide you with a template that you can build on top of later: adding or changing the assertion consumer service, adding name ID formats etc.

Here is a sample SP metadata generation form:

Sample Metadata Generation

In this example we supplied the following information:

  • EntityID: the identifier of your Squash instance. Must be unique among all the Service Providers known to the IDP.
  • Consumer Service endpoint: the endpoint where every SSO-related messages (assertions) should be sent to. Note that the endpoint path is /auth/saml/SSO.
  • Single Logout Service endpoint: the endpoint where the IDP can remotely initiate a logout. Note that the endpoint path is /auth/saml/SingleLogout.
  • NameID format: the preferred format for the username.
  • SP X.509 Cert (both for signing and encryption): Squash-TM certificate, that can be obtained as explained in Exporting a certificate.

The other inputs are optional and can be left blank if desired.

You can now click on the button Build SP Metadata on the lower part of the page and obtain the metadata as an XML file. The SAML services published are minimal yet functional and can be used as is in most environments.

Focus

The tools also offer you the possibility of signing the metadata by supplying a public and private key. You should not do that yet because:

  • It implies to send a private key over the Internet,
  • You cannot change the metadata unless you sign it again after modification,
  • Squash TM can sign it at runtime before publicly exposing it.
Advanced configuration

The tool introduced above has limitations, for instance you are forced into using the HTTP-POST binding profile for the SSO endpoint. The details of finer SAML metadata are beyond the scope of this documentation. If you need to produce a specific metadata file here are a few details of interest:

  • the list of endpoints is stated in Endpoints
  • the user NameID will be the login name in Squash TM
  • Squash-TM doesn’t check additional user information (mail address etc) beside the name (<RequestedAttribute> are ignored).

For more information

Please refer to the SAML Specification for additional details

Configuration

Using a dedicated file

The SAML Plugin proposes many configuration properties and the configuration file is rather large (compared to other plugins for Squash-TM). As of Squash-TM 1.18 you can configure the plugin in its own file then reference it from the main configuration file, instead of inlining the content like former plugins would need to.

To do so, copy the file config/squash.tm.cfg-saml.properties and paste it in the home configuration directory. In the standalone distribution of Squash-TM that directory is usually SQUASH_HOME/conf. Then edit the main configuration file SQUASH_HOME/conf/squash.tm.cfg.properties and link the plugin configuration file by adding/editing the property:

spring.profiles.include=saml

If this property was already set you can just append saml to the list, separated by a comma ‘,’.

(Alternate) By inlining the properties

If this is more convenient to you, you can simply copy and paste the content of the plugin configuration into the main configuration file. No need to add or append saml to the profiles list.

Minimum configuration

The configuration file proposes many properties but only a few of them are required. Squash-TM will not boot or function correctly if those are left blank or are set incorrectly.

The properties listed here are required. You will find details about them (allowed values etc) in the comments of the file squash.tm.cfg-saml.properties. More is also available further in this documentation.

saml.enabled: this is the plugin master switch. It allows you to disable (or enable) the plugin without commenting out everything and physically removing the jar file.

saml.idp.metadata.url: the location of the Identity Provider metadata. Protocols file:// and http:// are allowed.

saml.sp.metadata.url: the location of the Service Provider metadata. Protocols file:// and http:// are allowed.

saml.keystore.url: the location of the keystore. Only protocol file:// is allowed.

saml.keystore.password: the password of the keystore.

saml.keystore.credentials.<?>: the alias of a public/private key pairs for the cryptographic needs of Squash-TM. The question mark ‘?’ stands for an alias. The value of the property is the password for that key. This property can be repeated once per key.

saml.keystore.default-key: the alias of the key Squash-TM should use any time a private key is needed, unless another key is specified for that situation in the configuration file. The default key must of course be listed among the credentials list.

Other actions

The instance of Squash-TM needs to be registered at the Identity Provider along with the SP metadata to initiate the trust relationship. The specifics of this step depend on your SAML provider, please refer to its documentation.

Suggestion of configuration layout

Advanced Configuration

The previous chapter introduced you to the general concerns of the Squash-SAML setup. In many cases the resulting configuration should fit in your environment. However, the plugin offers several options for further customization, for example advanced cryptographic requirements or to account for the layout of your network. This chapter covers these extra options and revisit a few elements introduced in the previous chapter.

Info

If the purpose of some elements discussed here are unclear you may find useful hints in the Appendixes.

Conventions

File path formats

The metadata and the keystore can be retrieved by reading them as local files or remotely by HTTP(s) calls, using the properties saml.idp.metadata.url, saml.sp.metadata.url and saml.keystore.url.

By HTTP(s): the file path is the plain URL where it can be downloaded. The protocol is either http:// or https://. Example: https://your.idp/metadata.xml

By the absolute path: URL pointing to a local file act effectively as absolute paths. The protocol in this case is file://. Example: file:///dev/squashtm/saml/idp.xml (for Linux), file://C:/appfolders/squashtm/conf/idp.xml (for Windows).

By path relative to the configuration folder: a path that defines no protocol will be regarded as paths relative to the configuration folder. The location of the configuration folder may vary depending on the environment and how Squash-TM was installed. Example: saml/idp.xml -> resolves to $CONF_DIR/saml/idp.xml

Trust anchors

In some contexts, you may define which certificates among those present in the keystore should be considered a trust anchor. These contexts are SP metadata validation, IDP metadata validation and inbound IDP messages.

When a property (usually named *.trusted-keys) is encountered, the following values are acceptable :

  • all: all certificates in the keystore count as trust anchor
  • (blank): if no value defined, will count as ‘all’
  • none: no certificate in the keystore will be trusted, and certificates must then be backed by the trust CA certs keystore of the JVM.
  • A comma-separated list: the explicit list of keys in the keystore separated by a comma ‘,’. Namely :
    context.trusted-keys = anchor1, anchor2, anchor3
    

Of course, if you only need one anchor it would be wise not to name it ‘all’ nor ‘none’.

Property namespaces

The properties are grouped by namespaces that relate to actors (e.g. the idp) or resources (e.g. the metadata). They are listed with the namespace omitted for the sake of conciseness, with the namespace stated on top of the related table. This form is convenient in the context of a documentation, however when editing the configuration file remember to state the fully qualified name of the property.

Main entry point

As introduced in the chapter Usage, users can choose to log in either authentication system (the usual login form page or the SAML entry point), however one of them is set as the main entry point and if the user expresses no preference (s)he will be redirected there for authentication.

Squash-TM default sets the login form page as the main entry point. This can be overridden in the configuration.

Options

Namespace: squash.security

Property Comments
preferred-auth-url This property drives Squash-TM behavior regarding unauthenticated users’ requests.
It defines to which URL such users should be redirected, i.e. the main entry point.
If that property is set to /auth/saml/login, SAML will effectively become the main entry point.
Note that this property belongs to Squash-TM Core realm and is not specific to the SAML Plugin.
If you use other authentication plugins, check their respective configuration to prevent possible conflicts over this.
Default value: /login (the default login form page)

Handling of the metadata

The metadata, both for Squash-TM own file (as the Service Provider) and the Identity Provider, can be retrieved locally or remotely (see section above). Because of the sensitive nature of those files the content should be closely inspected. There are two approaches for this:

  • Either the metadata are signed and the signature is checked,
  • Either the source of the metadata is trusted and verified by other mechanisms (e.g. served by https, or a very private folder).

Focus

In case you opt for fetching the metadata via an https connection, the TLS channel is backed by the keystore of the JVM, in plain terms the default Java keystore. This is the only exception to the plugin-dedicated keystore paradigm (see Keystore). If the metadata provider has its distinct certificate be sure it is installed in the default keystore. Apologies for this discrepancy from the canon of this plugin.

IDP metadata options

Namespace: saml.idp.metadata

Property Comments
url (required) The url where the metadata can be found. It follows the conventions stated in section File path formats.
Default value: not applicable
require-signature Indicates whether Squash-TM expects the signed metadata. If set to true, unsigned metadata will be rejected.
Default value: false
check-signature If the metadata are signed, the signature will be checked. This involves checking the metadata digest and whether the trust in the certificate. This behavior is independent of the property above. If the metadata aren’t signed this property has no effect.
Default value: true
check-certificate-revocation If the signature of the metadata is verified, choose whether to check for certificate revocation too. Note that it merely enables the behavior but the specific mechanism (CLR, OSCP) cannot be configured here. Since we rely on the JCE provider of your JDK this would be driven by system properties instead and how the keystore was configured on that matter (at least for SUN JCE).
Note that the CRLs manually added to the keystore will be honored regardless of this property.
Default value: false
trusted-keys Among all the certificates installed in the keystore, defines which will be considered as trust anchors. Format is defined in section Trust anchors.
Default value: all
SP metadata options

They are strictly the same, with the namespace: saml.sp.metadata

Exposing the Service Provider metadata

Squash-TM will expose its SP metadata at the url /auth/saml/metadata. It will sign them too if desired, unless they were signed already (the metadata won’t be signed twice).

The algorithms involved in the signature are defined in the XML-Security specification. Note that the full URI must be specified, and the algorithm must be supported by the JCE provider of your JDK. The private key used for that usage is defined elsewhere, see property saml.sp.signing-key.

Options

Namespace: saml.sp.metadata-exposition

Property Comments
signed The exposed metadata will be signed by Squash-TM itself, however if the metadata were already signed the original signature will be preserved.
Default value: false
signing-algorithm The algorithm for signing the metadata. Examples:
- http://www.w3.org/2000/09/xmldsig#rsa-sha1
- http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
Default value: if empty, the algorithm associated to the key resolved by saml.sp.signing-key
digest-algorithm The algorithm for generating the digest. Examples:
- http://www.w3.org/2000/09/xmldsig#sha1
- http://www.w3.org/2001/04/xmldsig-more#sha224
Default value: if empty, http://www.w3.org/2000/09/xmldsig#sha1

Keystore

Info

All properties here were already introduced in Minimum configuration. They are presented here again for completeness.

The keystore is the locus of the PKI as far as Squash-TM is concerned. The SAML plugin uses a dedicated keystore, in addition of that of the JVM itself. Cryptographic operations involved in SAML use-cases will be backed by the dedicated keystore, with the only exception of TLS connection that downloads the metadata (see Handling of the metadata). Use cases include: encryption, decryption, signing and verification, certificate validation, and eventual direct TLS connection between both parties.

The keystore must hold the Root and Intermediate CA certificates that vouch for signed certificates, plus the self-signed certificates. It must also hold at least one key pair for Squash-TM usage. Optionally multiple key pairs can be defined, each for their distinct usage (see Service Provider messages).

Options

All the options listed here are required.

Namespace: saml.keystore

Property Comments
url The URL where the keystore can be loaded. The URL follows the conventions described in section File path formats, with the restriction that only file:// or the relative path formats are supported.
Default value: not applicable.
password The password that opens access to the keystore.
Default value: not applicable.
credentials.<?> The list of all key alias/password for the public/private key pairs that Squash-TM needs for signing, encrypting or initiating TLS connections. The format is such as the question mark ‘?’ represents the alias. The value should be the password. At least one key must be declared that way. This property can be declared multiple times (once per key).
The key aliases should be named sensibly, otherwise the property could be misinterpreted. It should contains only letters, digits, and hyphens or underscores, and be non-blank ( [a-zA-Z0-9-_]+ ).
Example: saml.keystore.credentials.thekey = thepassword
Default value: not applicable
default-key The default key used by Squash-TM when it needs a private key for a given task, unless a specific key was configured for that task (e.g. saml.sp.signing-key).
Default value: not applicable

SSO

The options listed here relate to the SSO process itself. You can tweak here the elements and conditions of the message exchanges. If the SP metadata exposes several alternatives for the same clause (like the ), you can also instruct here the plugin which value should be used instead of the default for that clause.

In some instances, the property value must be picked from the SAML specification. Here are a few useful links:

Standard options

Namespace: saml.sso

Property Comments
force-authN If enabled, the user will have to reauthenticate with the IDP every time it needs to authenticate with Squash. This ensures that the user authentication assertion is update to date. However, this can be annoying if the authentication process on the IDP involves a human interaction: this would effectively disable the SSO mechanism.
Default value: false
provider-name A human-readable name that will be included in messages sent to the IDP, useful for logging purposes.
Default value: blank
binding Which binding Squash TM would use to initiate SSO with the IDP. That binding should be available in the IDP metadata. Examples:
- urn:oasis:names🇹🇨SAML:2.0:bindings:HTTP-POST
- urn:oasis:names🇹🇨SAML:2.0:bindings:HTTP-Redirect
In practice you would need to extract the desired value from the IDP metadata.
Default value: the first binding method listed in the clause of the IDP metadata.
assertion-consumer-index Will ask the IDP to send its responses to the given consumer service. The list of available consumer services can be found in the clauses in the SP metadata. The consumer services order are listed by the attribute “index” within the tag.
Default value: if blank, will use the default (with the attribute “isDefault”, or with “index”=0).
nameID Which NameID should be returned by the IDP, and which will be used as the Squash user principal name (its login). Examples:
- urn:oasis:names🇹🇨SAML:1.1:nameid-format:emailAddress
- urn:oasis:names🇹🇨SAML:2.0:nameid-format:transient
Default value: the IDP will choose among those specified in its copy of the SP metadata.
allow-create Notifies the IDP that creating new user is permitted when unknown. Note that here we are referring to the creation of a user on the IDP. It merely is Squash-TM opinion on what the IDP should do, yet the IDP retains the final decision.
In any case, when a user successfully authenticates on the IDP, Squash-TM will create a user account for him/her if doesn’t exist as explained in section Usage. The present property has nothing to do with it.
Default value: false
passive If enabled Squash TM will inform the IDP that it doesn't consider user interaction necessary for authentication, which could spoil the user experience. Note that the IDP may (understandably) disagree.
Default value: false.
relay-state An arbitrary token to be sent back and forth to the IDP. It's part of the SAML specification but Squash TM has no concrete use case for it. The value can be anything.
Default value: blank
Scoping

The use of message Scoping allows for advanced SSO conversations. For instance, you can ask for guarantees over the quality of the user authentication on the IDP’s end (by specifying an auth context), or restrict which IDPs are trusted in a multi-layered IDP architecture.

The following properties will be processed only if scoping is enabled.

Namespace: saml.sso (same as for the standard options)

Property Comments
include-scoping The master switch for the scoping. If false, the other options listed here will be disabled.
Default value: false
allowed-idps This property configures the clause <IDPList>. In a multi-layered IDP architecture, this list defines which IDPs are allowed to process an authentication request. The value is a comma-separated list of IDP entityIDs.
Default value: empty (no restrictions)
proxy-count Maximum proxy hops allowed for authentication messages. In this context a proxy means an IDP within a multi-layered architecture. A value of 0 forbids the use of proxies: the IDP that receives the authentication request cannot delegate and must authenticate the user itself.
Default value: 2
authn-contexts A comma-separated list of authentication contexts that should be honored by the IDP when it authenticates the user. Useful when the default IDP authentication challenge is not deemed sure enough and Squash-TM asks for guarantees of a more stringent process. Examples or possible values:
- urn:oasis:names🇹🇨SAML:2.0🇦🇨classes:SmartcardPKI
- urn:oasis:names🇹🇨SAML:2.0🇦🇨classes:MobileTwoFactorContract
Default value: blank (no specific requirements)
authn-context-comparison Additional requirements about the handling of the credentials presented by the user during authentication on the IDP. The allowed values are: exact | minimum | maximum | better.
Default value: exact.

Service Provider messages

The SP metadata describe most of Squash-TM behavior in a SAML context. The properties here allow you to complement the metadata or override it in part, for instance you could need to change the preferred NameIDFormat without touching the metadata.

Several options here refer to the usage of private keys. When undefined, the default key of the keystore will apply (see section Keystore).

Options

Namespace: saml.sp

Property Comments
signing-key If the signing-key is different from the default-key, indicates the alias of the private SP key for signing outbound SAML messages.
Default value: undefined, in which case the default key applies.
encryption-key If the encryption key is different from the default-key, indicates the alias of the private SP key for decrypting inbound SAML messages.
Default value: undefined, in which case the default key applies.
tls-key If a direct HTTPS connection is necessary (eg HTTP-Artifact) and Squash-TM as a client must authenticate using a certificate, indicates the alias of the private SP key to use.
Default value: undefined, in which case the default key applies.
require-logout-request-signed If the IDP initiates a logout, indicates that Squash-TM requires that such requests should be signed.
Default value: true
require-logout-response-signed If Squash-TM initiates a logout, indicate that the response to the logout request should be signed.
Default value: false
signature-security-profile The policy for signature verification. The allowed values are metaiop or pkix, see section Certificates for details about those policies.
Default value: metaiop
ssl-security-profile The policy for checking SSL/TLS certificates when direct HTTPS connection is required. The allowed values are metaiop or pkix, see section Certificates for details about those policies.
Default value: pkix
ssl-hostname-verification In addition to certificates, the hostname of the IDP can also be verified in case of direct HTTPS connection. The accepted policies are: default, defaultAndLocalhost, strict or allowAll. Note that allowAll effectively disables the hostname verification.
Default value: default

Identity Provider messages

The handling of the messages sent by the Identity Provider is primarily driven by the IDP metadata that Squash-TM knows of. However, in some instances the metadata may be incomplete, or perhaps you need to override them temporarily. As an example, consider an IDP that signs its message, but no certificate for usage of signing was specified in the metadata: you can supply that missing piece of information by defining the property saml.idp.signing-key.

In addition of tweaking how the inbound messages are handled, the following properties let you also define several traits about the IDP, such as what content is expected from Squash-TM in outbound messages.

Options

Namespace: saml.idp

Property Comments
signing-key The key for verifying the signature of a message inbound from IDP.
Default value: the certificate with usage of signing declared in the IDP metadata.
encryption-key The key for encrypting messages outbound to IDP.
Default value: the certificate with usage of signing declared in the IDP metadata.
trusted-keys If Squash-TM must perform PKIX verification on the certificates of inbound messages, defines which keys are considered as trust anchors. Format is defined in the section Trust anchors.
Default value: all
require-logout-request-signed Indicates that the IDP requires that any logout request initiated by the SP must be signed, when Squash-TM is the initiator.
Default value: true
require-logout-response-signed Indicates that the IDP requires that any responses to IDP-initiated logout requests must be signed.
Default value: false
require-artifact-resolve-signed If enabled, HTTP-Artifact resolution messages will be signed.
Default value: true
allow-idp-initiated-sso Indicate that this IDP is permitted to initiate SSO on its own. Squash-TM can still initiate SSO as usual.
Default value: true
Direct connection options

If the profile HTTP-Artifact is enabled for SSO conversations, a direct connection between Squash-TM and the Identity Provider will be necessary for the artifact resolution.

In case a proxy sits between both servers, you can configure the proxy-related information with the following properties.

Namespace: saml.idp (same as for the standard options)

Property Comments
proxy-host The host of the proxy. This property enables the other properties below.
Default value: undefined.
proxy-port The port of the proxy.
Default value: 8080
basic-username If the IDP challenges the connection with Basic-Authentication, this is the username to use.
Default value: blank
basic-password The password for Basic-Authentication challenges.
Default value: blank

Authentication expiration

Periodically Squash-TM will invalidate an authentication assertion unilaterally if it reaches an expiration duration set in its configuration (just as the Identity Provider can set an expiration date on its own assertions). The user must then reauthenticate on the Identity Provider. This can lead to loss of unsaved work if this occurs and the server was unable to save the failed requests. For this reason, users are encouraged to reauthenticate on their own on the Identity Provider at the time of their choosing.

Focus

The user must reauthenticate on the Identity Provider even when their session on the IDP is still valid because Squash will reject the authentication if the same assertion is presented.

Options

Namespace: saml.session

Property Comments
max-auth-time Defines the lifetime in seconds of an authentication assertion before the user must reauthenticate on the Identity Provider.
Default value: 864000 (about 10 days)

Proxy

If Squash-TM is served through a reverse-proxy or a load balancer, the modifications applied to URLs and schemes can induce mismatches between the actual and expected requests. You can declare in the configuration that proxy, to instruct Squash-TM how to account for these rewrites when exchanging messages with the Identity Provider.

Options

Namespace: saml.proxy

Property Comments
enabled The master switch that enable the proxy the other options below.
Default value: false
server-name The hostname of the reverse proxy. This property has no default value and must be provided.
Default value: blank
scheme The scheme used by the reverse proxy for outbound communications.
Default value: https
server-port The port used by the reverse proxy for outbound communications.
Default value: 443
context-path The context path of the application, as served by the reverse proxy.
Default value : /squash
include-port-in-url Whether the port number should be explicitly included in the request URL (even when a default port is used and could be omitted).
Default value: true

User Account Information

Depending on the configuration of the IPD server, the assertions in response to authentication requests may contain additional information regarding the user account. In the document of the assertion those extra attributes are listed under the <AttributeStatement> tag. The properties listed below allow Squash-TM to use them.

Please note that Squash-TM will not ask for those attributes by the mean of a Requested Attributes clause (see SAML Protocol Extension for Requesting Attributes per Request), because that feature is not always supported and depends on the IDP implementor. Instead, you should make sure that the IDP will attach those attributes to the assertion unconditionally.

Options

Namespace: saml.user-mapping

Property Comments
alternate-username Uses the value of that attribute as the username in Squash-TM instead of the nominal NameID. It allows you to work around the limitations of the IDP if it cannot provide with the NameIDFormat you need (eg older versions of Azure).
Default value: none (feature disabled)
first-name Maps one of the extra attribute values as the first name of a user account in Squash-TM. This feature is used only when user account is to be created (a new user): pre-existent user account will not be updated this way.
Default value: none
last-name Maps one of the extra attribute values as the last name of a user account in Squash-TM. This feature is used only when user account is to be created (a new user): pre-existent user account will not be updated this way.
Default value: none
email Maps one of the extra attribute values as the email of a user account in Squash-TM. This feature is used only when user account is to be created (a new user) : pre-existent user account will not be updated this way.
Default value: none

Logging

If you experience troubles using SAML you can enable finer logging to find out what is going wrong. To do so add the following lines to the configuration:

logging.level.org.squashtest.tm.plugin.saml=TRACE
logging.level.sqsaml.org.springframework.security=TRACE
logging.level.org.springframework.security.web.authentication=TRACE
logging.level.org.opensaml=TRACE

TRACE is the finest logging level available. If this is too verbose you can use the DEBUG level instead.

Focus

Squash-TM must be rebooted to account for your new configuration.

Appendix A: about cryptography

This chapter briefly covers a few concepts used in SAML scenario. It attempts to clarify minute details of the involved mechanisms for the unfamiliar reader. We will keep this section concise as the goal here is not to explain those mechanisms, but merely to explicit what the options listed in the previous chapter are referring to.

Usage

The data exchanged between actors of SSO conversations make a significant use of cryptographic material. The goals are to ensure that:

  • messages content remained hidden from unwanted parties,
  • the content wasn’t tampered with,
  • they were sent by the intended origin,
  • the said origin is indeed what it claims to be.

The first concern of the list is covered by encryption, which make the data undecipherable except for the recipient of the message. The second concern is addressed by the signature of the content, an encrypted digest of the content which can be compared with the received message for error detection. The third concern is addressed by the certificate of the sender, which binds the identity of the sender to the key that generated the signature. The fourth concern is covered by the certificate path validation, which establishes a chain of trust between the certificate and a certification authority.

Public/private key pairs

Encryption and signature rely on the use of public/private key pairs, used in somewhat (though not exactly) symmetric roles. The public key is wrapped in a certificate stating who owns it, then published to anyone interested with it. The corresponding private key, on the other hand, is known only by its owner. Each server involved, in our case Squash-TM and the Identity Provider, possess one or more of such key pairs and certificates.

Encryption

To encrypt a message, the sender applies an encryption algorithm on the message with the recipient public key.

Once encrypted, the recipient can recover the original content using its recipient private key. Since only the recipient owns that private key, only it can access the content.

Signature

To sign a message, the sender first generates a digest of the message with a digest algorithm. Then the result is encrypted with an encryption algorithm with its sender private key.

The recipient can then verify the signature. To do so it first decrypts the signature with the sender public key. Then it applies the same digest algorithm on the received message. Finally, the two digests are compared. If they match perfectly we can conclude that:

  • whoever the sender is, it indeed owns the private key,
  • the message indeed comes from the expected sender, as stated by the certificate bound to the corresponding public key,
  • no third party altered the message after signature, because the digests match.

Info

Due to the close relation between a public key and the certificate the two words are often used loosely. This confusion is usually harmless and is used in this document too.

Certificates

The primary mission of a certificate is essentially to bind an identity to a public key. The standard certificate format in the Java world is X.509, which bear many information including:

  • the public key,
  • the identity (more than a mere name, it is a collection of information regarding the subject),
  • the Certification Authority that vouched for it and its signature,
  • the means of verifying the Certification Authority itself (in recent versions of the format),
  • the period of validity of the certificate…

The list is not exhaustive and the interested reader can find more literature publicly available over the Internet.

Since a certificate holds a public key and an identity, it allows for verification of signatures, of identity, or both. The verification of a signature has been covered in Signature and is solely a matter of computation. The verification of the identity involves the construction of a chain of trust, depending on whether a given certificate is a priori trusted or not by the server that receives it, and requires a PKI.

Public Key Infrastructure (PKI)

The PKI is the overall system that establishes trust between parties. An important part of the PKI is the hierarchy of Certification Authorities (CA). Higher level authorities vouch for authorities below them. Physically it is implemented as a family of certificates. A CA vouches for another certificate (whom owner is possibly another CA) by signing it with its own certificate.

The top-level CA is called Root CA and is trusted de facto within the organization. The other certificates below it that themselves act as authorities for other certificates are called Intermediate CA.

In a Java application, the keystore is the file in which all the CAs and otherwise trusted certificates are installed.

Certification path validation by PKIX

A Java server such as Squash-TM can check the authenticity of an unknown certificate by validating the certification path between that certificate and the Root CA. This process is known as the PKIX algorithm.

It basically consists of inspecting the certification path declared by the certificate under scrutiny and verify it against the keystore. If the declared path is consistent with the content of the keystore the certificate will be trusted.

The certification path is validated "bottom up" until the Root CA is encountered, or a trust anchor. A trust anchor is any certificate that is flagged as automatically trusted for a specific context. Different certificates can be used as trust anchors for different contexts, for instance validating an SSL certificate or a signature can rely on different trust anchors.

Additional checks also take place, including verification of expiration date, or premature revocation issued by a higher ranked CA.

If at some point a certificate declared in the path is absent from the keystore the validation fails. Therefore, all relevant certificates, CA etc for the implementation of Squash+SAML should be installed in Squash-TM keystore.

Signed certificates

Signed certificates are certificates that were submitted and approved by a Certification Authority. Approval means here that the authority ensured that the issuer of the candidate certificate is really who he claims to be before signing the certificate with its own certificate. The signed certificate can be checked later by consuming parties using certification path validation.

A signed certificate is inherently more secure than the self-signed variant.

Self-signed certificates

These certificates are common in private organizations because they are fast and cheap to create, as long as the risk of identity forgery is mitigated by other means in a controlled environment.

By definition a self-signed certificate doesn’t need to any upward certification path, so the identity cannot be verified by PKIX. Therefore, it must be installed and considered as trust anchor by the keystore of the consuming parties or identity validation will fail.

Info

A self-signed certificate is not necessarily a bad thing: after all the Root CA is itself a self-signed certificate and no other vouches for it.

Metadata Interoperability Profile (Meta IOP)

SAML metadata are obvious candidate for thorough inspection at boot time, but the case of message exchanges during SSO is disputable. According to the SAML Metadata IOP specification, certificate path validation for SAML messages could be outright skipped without compromising security:

" A signed metadata file conforming to this specification is semantically equivalent to an X.509-based public key infrastructure (PKI), hence there is little value in the additional layer of complexity provided by certificate validation as specified in [RFC5280] "

The rationale behind this is, as long as all the certificates involved in the SAML conversations are stated in the metadata and those metadatas have already passed security checks there is no point in checking them again each time a message is received. Encryption and signature checks are still necessary to ensure that the message was not compromised, but the sender will be trusted solely because it obviously holds the keys declared in the metadata.

Info

This approach is applicable to the SAML messages only. The https connection that convey them is a separate concern, which calls for its own security checks.


  1. The only exception will be covered in Handling of the metadata