Skip to main content
Skip table of contents

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:

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

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

Removed in 6.1.0

The application will now default to the one specified in the IdP’s metadata.

The name id format to use when communicating with the idp

Must be one of the following:

  1. urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

  2. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

  3. urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

  4. 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:

  1. read groups from the SAML response

  2. create groups that are missing in the application

  3. add user to all groups from the response

  4. 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

Removed in 6.1.0

The application will now default to http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

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

To get the application SAML metadata to share with the IdP use the URL: <server_url>/<contextPath>/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:

CODE
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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.