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.

The example values below assume that "idp.company.com" is the Identity Provider (IdP), and "valsight.company.com" is the Valsight app (Service Provider, SP).

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 cookies 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 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

Then configure the SAML connection values as follows:

Configuration Key (….registration.SAML →)	Description	Example Value	Default Value
entity-id	The Identity Provider (IdP) entity ID ⚠ must match your metadata XML entity	https://idp.company.com	n/a
signing → credentials → private-key-location certificate-location	Location of the private key used to sign SAML authentication requests and the location of the relying PartX509Certificate shared with the identity provider for SAML authentication requests. Both take the form of a file path or class path. Note if class path is used the root folder is the resources folder in the rest-service. Note this can be a list of paired keys and certificates. The “-” character is required before each “private-key-location” value	private-key-location File path: file:./conf/saml/signing_key.key Class path: classpath:credentials/signing_key.key certificate-location File path: file:./conf/saml/signing_cert.crt Class path: classpath:credentials/signing_cert.crt	n/a
decryption → credentials → private-key-location certificate-location	Location of the private key used for decrypting the SAML authentication request and the location of the relying PartX509Certificate shared with the identity provider for SAML authentication requests. Both take the form of a file path or class path. Note if class path is used the root folder is the resources folder in the rest-service. Note this can be a list of paired keys and certificates. The “-” character is required before each “private-key-location” value	private-key-location File path: file:./conf/saml/signing_key.key Class path: classpath:credentials/signing_key.key certificate-location File path: file:./conf/saml/signing_cert.crt Class path: classpath:credentials/signing_cert.crt	n/a
assertingparty → metatdata-uri	URL to the Identity Provider (IdP) metadata Can take the form of a URL, file path or class path. Note if class path is used the root folder is the resources folder in the rest-service.	URL: http://idp.com/idp-metatdata.xml File path: file:./conf/saml/idp-metatdata.xml Class path: classpath:metadata/idp-metatdata.xml	n/a
valsightSamlProperties → name-id-format	The name id format to use when communicating with the idp Must be one of the following: 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 urn:oasis:names:tc:SAML:2.0:nameid-format:transient _Optional*	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress	n/a
valsightSamlProperties → loginSuccessfulUrl	The absolute URL (starting with http(s)) of the application's main page. The user will be redirected there after a successful login. _Optional*	https://valsight.company.com/	n/a
valsightSamlProperties → userProfileMapping → username	The SAML response attribute used to uniquely identify an user. It must always be present in the response and unique per user. _Optional*	preferred_username	SAML user ID
valsightSamlProperties → userProfileMapping → email	This 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 → attribute: attributeValue	This is used to customize the requested presence and values of SAML response attributes. Each attribute configured here must be present in the provider's response and also have the specified value. If attribute has multiple values in the response (e. g. a list of groups the users belongs to) then one of the values in the response must be an exact match to the configured value. _Optional*	Example Configuration CODE `mandatoryAttributes: group: groupName role: roleName` Note that these are both example attributes and values. It is possible to input any attribute name and value presuming they are included in the SAML token attributes.	n/a
valsightSamlProperties → groupsAttribute	This configuration option enables SAML to determine which groups users belong to. If this field is not present or if it is empty, the groups must be managed internally in the application. If we set a value of 'groupsAttribute' we turn this functionality on. The value of 'groupsAttribute' should be an attribute name of the SAML response (https://docs.oasis-open.org/security/saml-subject-id-attr/v1.0/cs01/saml-subject-id-attr-v1.0-cs01.html#_Toc536097223) that contains the SAML provided groups. The group matching happens as follows: read groups from the SAML response create groups that are missing in the application add user to all groups from the response remove user from all groups not in the response Important: this functionality never automatically deletes groups in the application _Optional*	groupsInSAMLResponse	n/a
valsightSamlProperties → signingAlgorithms → RSA	Which signing algorithm should be used to sign XML requests created by the Valsight application. List of possible values: https://www.w3.org/TR/xmldsig-core1/#sec-SignatureAlg You can replace the 'RSA' key with any of the listed signature methods. The 'signingAlgorithms' key also allows multiple signature method configurations at the same time. _*Optional	http://www.w3.org/2001/04/xmldsig-more#rsa-sha256	http://www.w3.org/2001/04/xmldsig-more#rsa-sha1

Configuration Key

A Configuration Key for fullName and email is not supported in SAML authentication.

When the Valsight app is running behind a reverse proxy and the app server's port is not exposed directly (e.g. for purposes of HTTPS configuration), the following additional configuration is required:

Configuration Key (saml →)	Description	Example Value	Default Value
^{reverseProxy → enabled}	Whether to enable reverse proxy support	^true	^false
^{reverseProxy → scheme}	The URL scheme under which the app is exposed	^https	^https
^{reverseProxy → serverName}	The public server name of the reverse proxy without protocol (https://) or path.	^{valsight.company.com}	n/a
^{reverseProxy → port}	The public port of the reverse proxy	⁴⁴³	⁴⁴³

How to Setup a Java KeyStore for a SAML Configuration

Goal

Create a KeyStore for implementing signed requests for SAML authentication.

Prerequisites

A Public Certificate available from the Identity Provider server. Typical file formats for this are .cer and.crt.

Identify these variables for usage in the environment:

SERVICE_PROVIDER_ALIAS (i.e. valsightsaml)
IDENTITY_PROVIDER_ALIAS (i.e. externalsaml)
KEYSTORE_FILENAME (i.e. valsightsaml.keystore)

Step-by-step guide

1) Generate a new KeyStore and private key on the Valsight server by running this command:

^{keytool -genkey -alias <SERVICE_PROVIDER_ALIAS> -keyalg RSA -keystore<KEYSTORE_FILENAME>}

A password/passphrase for the new KeyStore file. This command will prompt for the following values:

Re-enter the same password to confirm.
Private Key identifying attributes such as Company name, Organization name, etc.

2) Verify that the <KEYSTORE_FILENAME> is successfully created on the file system.

3) Import the ID Provider Public Certificate into the KeyStore that was created.

^{keytool -import -alias <IDENTITY_PROVIDER_ALIAS> -file <IDENTITY_PROVIDER_CERTIFICATE_FILE> -keystore <KEYSTORE_FILENAME>}

4) Copy the <KEYSTORE_FILENAME> file to a known location on the server and ensure that the Linux file permissions allow the valsight user to read the file.

5) Edit the Valsight SAML configuration.

Input the KeyStore information including these values:

KeyStore Path (path to the <KEYSTORE_FILE>)
KeyStore Password (this was input during the first keytool command)
Service Provider Alias Name (<SERVICE_PROVIDER_ALIAS>)
Service Provider Passphrase (this was input during the first keytool command)

After enabling SAML you can disable the regular login with local user accounts as described at Common SSO Options.