SAML

To configure the Valsight application as a Service Provider (SP) in a SAML infrastructure, edit conf/config.yml and restart the server after making changes.

To enable SAML login configure the following value:

Configuration Key (loginMethodConfigurations → saml →)	Description	Example Value	Default Value
enabled	Whether SAML authentication should be used or not	true	false

Note: In order for SAML to be enabled, the same-site attribute for session cookie should be set to “none” with secure: true

Configuration Key (server → servlet → session → cookie → )	Description	Example Value	Default Value
same-site	Restricts the usage of the cookie for the browser. The restriction is based on the originating event, which instructed the browser to send the cookie	none	strict
secure	Ensures that the cookie is only sent over HTTPS connections. If same-site is set to none, secure must be set to true	false	true

To configure a SAML connection enter the following configuration keys:

spring:
  security:
      saml2:
        relyingparty:
              registration:
                   SAML:
                   ........

Then configure the SAML connection values as follows:

Configuration key	Description	Example	Default
`entity-id`	The Identity Provider (IdP) entity ID. Must match your metadata XML entity.	`https://idp.example.com`	n/a
`signing → credentials`	Location of the private key used to sign SAML authentication requests, and of the RelyingPartyX509Certificate shared with the identity provider. See Credential locations.	See Credential locations	n/a
`decryption → credentials`	Location of the private key used to decrypt the SAML authentication request, and of the RelyingPartyX509Certificate shared with the identity provider. See Credential locations.	See Credential locations	n/a
`assertingparty → metadata-uri`	URL to the Identity Provider (IdP) metadata. Takes a URL, a file path or a class path. See Credential locations for how class paths resolve.	`http://idp.example.com/idp-metadata.xml`	n/a
`valsightSamlProperties → name-id-format`	Removed in 6.1.0. See Removed: name-id-format.	`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`	n/a
`valsightSamlProperties → loginSuccessfulUrl`	The absolute URL, starting with `http` or `https`, of the application’s main page. The user is redirected there after a successful login. Optional.	`https://valsight.example.com/`	n/a
`valsightSamlProperties → userProfileMapping → username`	The SAML response attribute used to uniquely identify a user. Must always be present in the response, and unique per user. Optional.	`preferred_username`	The SAML user ID
`valsightSamlProperties → userProfileMapping → email`	The SAML response attribute that contains the user’s e-mail address. Optional.	`email`	n/a
`valsightSamlProperties → userProfileMapping → fullName`	The SAML response attribute that contains the user’s full name. Optional.	`name`	n/a
`valsightSamlProperties → mandatoryAttributes`	Customizes which SAML response attributes must be present, and with which values. See Mandatory attributes. Optional.	See Mandatory attributes	n/a
`valsightSamlProperties → groupsAttribute`	The SAML response attribute holding the groups the user belongs to. See Group synchronization. Optional.	`groupsInSAMLResponse`	n/a
`valsightSamlProperties → signingAlgorithms → RSA`	Removed in 6.1.0. See Removed: signingAlgorithms.	`http://www.w3.org/2001/04/xmldsig-more#rsa-sha256`	`http://www.w3.org/2001/04/xmldsig-more#rsa-sha1`

Credential locations

The signing and decryption credentials each take a private-key-location and a certificate-location. Both accept either a file path or a class path. When a class path is used, the root folder is the resources folder in the rest-service.

Key	File path	Class path
`private-key-location`	`file:./conf/saml/signing_key.key`	`classpath:credentials/signing_key.key`
`certificate-location`	`file:./conf/saml/signing_cert.crt`	`classpath:credentials/signing_cert.crt`

Each of these can be a list of paired keys and certificates. The - character is required before every private-key-location value.

Removed: name-id-format

Removed in 6.1.0. The application now defaults to the format specified in the IdP’s metadata.

Before 6.1.0 this set the name ID format used when communicating with the IdP, and had to be one of urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified, urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent or urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

Mandatory attributes

Every attribute configured here must be present in the provider’s response and carry the specified value. Where an attribute has multiple values in the response — a list of the user’s groups, for example — one of those values must match the configured value exactly.

MIGRATETOKEN1ENDTOKEN

These are both example attributes and values. Any attribute name and value can be used, provided they are included in the SAML token attributes.

Group synchronization

Setting groupsAttribute turns on group synchronization. If the attribute is absent or empty, groups must be managed inside the application instead.

The value should be an attribute name of the SAML response (see the OASIS SAML subject-id attribute specification) that contains the groups the IdP provides.

Group matching then happens as follows:

Read the groups from the SAML response.
Create groups that are missing in the application.
Add the user to all groups from the response.
Remove the user from all groups not in the response.

This functionality never automatically deletes groups in the application.

Removed: signingAlgorithms

Removed in 6.1.0. The application now defaults to http://www.w3.org/2001/04/xmldsig-more#rsa-sha256.

Before 6.1.0 this chose the algorithm used to sign the XML requests the application creates. The possible values are listed in the XML Signature Syntax and Processing specification. The RSA key can be replaced with any of the listed signature methods, and signingAlgorithms accepts several signature method configurations at once.

To get the application SAML metadata to share with the IdP use the URL: <server_url>//saml2/service-provider-metadata/SAML

Full example YAML configuration

Below is an example of all the available configuration keys for SAML, with no values supplied except where stated:

server:
    servlet:
        session:
            cookie:
                same-site: none
                secure: true
spring:
    security:
        saml2:
            relyingparty:
                registration:
                    SAML:
                        entity-id:
                        signing:
                            credentials:
                              - private-key-location:
                                certificate-location:
                        decryption:
                            credentials:
                              - private-key-location:
                                certificate-location:
                        assertingparty:
                            metadata-uri:
                        valsightSamlProperties:
                            loginSuccessfulUrl:
                            userProfileMapping:
                                username:
                                email:
                                fullName:
                            groupsAttribute:
                            mandatoryAttributes:
                                #example value
                                group: groupName

Logging

To log more details you can set logging level to DEBUG for the following packages:

com.valsight.authentication
com.valsight.authentication.saml
com.valsight.services.authentication.SSOService
org.springframework.security
org.springframework.security.saml2
org.opensaml
org.opensaml.saml
org.springframework.web.client

Set the log level to DEBUG

Reverse proxy configuration

If the application is running behind a reverse proxy it will be required to configure the reverse proxy such that the SAML authentication flow can be performed A guide to doing this can be found here: Reverse Proxy