# SAML URL: https://docs.valsight.ai/saml/ Description: 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 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](#credential-locations). | See [Credential locations](#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](#credential-locations). | See [Credential locations](#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](#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](#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](#mandatory-attributes). Optional. | See [Mandatory attributes](#mandatory-attributes) | n/a | | `valsightSamlProperties → groupsAttribute` | The SAML response attribute holding the groups the user belongs to. See [Group synchronization](#group-synchronization). Optional. | `groupsInSAMLResponse` | n/a | | `valsightSamlProperties → signingAlgorithms → RSA` | Removed in 6.1.0. See [Removed: signingAlgorithms](#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](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 groups the IdP provides. Group matching then happens as follows: 1. Read the groups from the SAML response. 2. Create groups that are missing in the application. 3. Add the user to all groups from the response. 4. 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](https://www.w3.org/TR/xmldsig-core1/#sec-SignatureAlg). 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: \//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](/reverse-proxy/)