Skip to content

SAML

Overview

The SAML plugin adds a new authentication entry point for Squash. 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 (it can also be disabled).

Squash supports SAML 2.0

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: SAML entry point for user authentication;
  • /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 is always required, e.g. in the stock Squash TM deployment, the final URL would look like http://someserver:8080/squash/auth/saml/login.

Limitations

SAML Plugin only supports metadata for a single Identity Provider (IDP) and a single Service Provider (SP). 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 TM 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 provide 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

By default, users can 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 he/she 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, the user will be created and be able to log on but will not be able to access any project on Squash TM.

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

It is possible to allow authentication only via the SAML SSO interface, see Authentication sources.
In this case, users cannot authenticate with their local account and they, or an admin, cannot change or define their local password.
If they are trying to access the /login page, they are redirected to the SAML SSO interface (auth/saml/login).

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

Install the SAML plugin in the pluginsdirectory (see Install plugins).

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 (i.e. $JAVA_HOME/bin/keytool). In this section we assume that the JDK provider is Oracle Hotspot. The full documentation is available here: Oracle Keytool Doc.

Info

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 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 does not 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 Export 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, it should be imported 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 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 party certificates 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, which offers basic metadata generation options. It can provide you with a template on top of which you can build 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;
  • Attribute Consume 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 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;
  • Squash does not 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). 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://, http:// and https:// are allowed.

saml.sp.metadata.url: the location of the Service Provider metadata. Protocols file://, http:// and htps:// 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.

Authentication sources

By default, users can either authenticate with their local Squash account or their SAML SSO account.

It is possible to allow authentication only with the SAML SSO account with the following property:

authentication.provider=saml

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 requirements for RSA encryption or to account for the layout of your network. This chapter covers these extra options and revisits 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 format 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 he/she 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 are not 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 will not 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 <NameIDFormat>), 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 would use to initiate SSO with the IDP. That binding should be available in the IDP metadata. Examples:
- urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
- urn:oasis:names:tc: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 <SingleSignOnService> 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 <AssertionConsumerService> 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:tc:SAML:1.1:nameid-format:emailAddress
- urn:oasis:names:tc: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 it does not exist as explained in section Usage. The present property has nothing to do with it.
Default value: false
passive If enabled Squash will inform the IDP that it does not 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 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: (blank, 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:tc:SAML:2.0:ac:classes:SmartcardPKI
- urn:oasis:names:tc:SAML:2.0:ac: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 (e.g. 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 used for signature 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 ten 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 implementer. 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 restarted to take into 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 was not 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 and the result is attached to the signed message.

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/she 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 does not 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 metadata 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.