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.

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


The meta data can be configured either via ULR or via file.

Configuration Key (saml →)DescriptionExample ValueDefault Value
enabled
Whether SAML authentication should be used or not
true
false
metadata → url
URL to the Identity Provider (IdP) metadata
http://idp.company.com/idp-meta.xml
n/a
metadata → file
Path relative to APP_HOME to an XML file containing the idp metadatameta-idp.xmln/a
metadata → timeout
Timeout in milliseconds50005000
metadata → idpEntityId

The Identity Provider (IdP) entity ID

(warning) must match your metadata XML entity

https://idp.company.com
n/a
metadata → 
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.


Since: 3.1.18 / 3.4.0

http://www.w3.org/2001/04/xmldsig-more#rsa-sha256http://www.w3.org/2001/04/xmldsig-more#rsa-sha1
entityId
The Service Provider (SP) entity ID
http://valsight.company.com/sp
n/a
entityBaseUrl

The URL under which the Valsight app (Service Provider, SP) is reachable from the IdP
(Note: must not contain a trailing slash; when the app UI is normally accessed under "http://valsight.company.com/app/index.html", enter "http://valsight.company.com/v1" here)

(warning) the v1 is important!

http://valsight.company.com/v1

n/a

keyStore → location

The location of the Service Provider (SP) keystore file (PKCS#12 format). The value should start with "file:" and may reference a path that is relative to the server's working directory (which is the install directory). Using the default value of this key, you may place the keystore file under "<install dir>/conf/saml/samlKeystore.p12"

file:./conf/saml/samlKeystore.p12
file:./conf/saml/samlKeystore.p12
keyStore → storePassword
The password of the PKCS#12 keystore file
n/a
keyStore → alias
The alias of the certificate inside the PKCS#12 keystore file
n/a
keyStore → password
The password of the certificate inside the PKCS#12 keystore file
n/a
loginSuccessfulUrl

The absolute URL (starting with http(s)) of the application's main page. The user will be redirected there after a successful login.

Since: 2.18.0 / 2.17.5

https://valsight.company.com/
n/a
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

Since: 5.0.0

preferred_usernameSAML user ID
userProfileMapping email

This SAML response attribute that contains the user's e-mail address.


*Optional

Since: 5.0.0

emailn/a
userProfileMapping fullName

The  SAML response attribute that contains the user's full name.


*Optional

Since: 5.0.0

namen/a
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

Since: 5.0.0

Example Configuration

YML
mandatoryAttributes:
	group: groupName
	role: roleName
n/a
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 a an attribute name of a 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


Since: 3.5.0

groupsInSAMLResponsen/a
maxAuthenticationAgeHow many seconds the application considers the SSO authentication to be valid. If it the between the log in into the SSO system and the log in into the application is greater than this value, the login into the application will be denied.30007200
addOrganizationData

Adds organization info and contact persons to the service provider's generated metadata XML file

Since: 4.3.0

truefalse
ignoreIDPSessionDuration

Controls whether the users' session expires after the identity provider's predetermined time or if we use the application's session expiry logic. This flag has no effect if the identity provider does not define the session expiration.

Since: 4.3.1

truefalse

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 →)DescriptionExample ValueDefault 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

(warning) without protocol (https://) or path.

valsight.company.com

n/a

reverseProxy → port
The public port of the reverse proxy
443
443


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.

JavaScript errors detected

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

If this problem persists, please contact our support.