Single Sign-on

The Single Sign-on page in Veezoo Admin lets you configure Veezoo to use Security Assertion Markup Language (SAML) to authenticate users.

Single sign-on with SAML is only available for Enterprise subscription plans. Check our pricing and get in touch with us to enable it!

Configure your identity provider

In a first step, you need to configure Veezoo as a service provider at your identity provider. Check our documentation on how to configure Microsoft Azure as an identity provider for Veezoo.

The information required and terminology used by your identity provider may slightly differ depending on the specific implementation used. You can view and extract Veezoo's service provider information from the Service Provider subsection:

Entity id

The entity id of the service provider, i.e. Veezoo.

This is a globally unique name identifying Veezoo as a service provider. Some identity providers might also call this the identifier, audience or similar.

Some identity providers might also call this the identifier, audience or similar.

Value: https://veezoo.com/saml

Assertion consumer service URL

The URL of the assertion consumer service (ACS) of the service provider, i.e. Veezoo.

This is the URL of the Veezoo endpoint where the identity provider should send SAML assertions to after an authentication. Some identity providers might also call this the callback URL, reply URL, destination or similar.

Value: https://<subdomain>.app.veezoo.com/saml/callback

Metadata

The metadata of the service provider, i.e. Veezoo.

This is an XML object containing all the necessary information to describe Veezoo as a service provier.

Enter your identity provider information

Veezoo needs to know about your identity provider, so it can send authentication requests to the right place. You can configure this information in the Identity provider subsection:

Metadata

The metadata of the identity provider.

This is an XML object containing all the necessary information to describe the identity provider. Identity providers typically let you download the metadata as a file.

Maximum authentication lifetime

The maximum lifetime of an authentication at the identity provider, specified in seconds.

SAML assertions returned by identity providers contain an AuthnStatement with an AuthnInstant attribute. The value of this attribute specifies the time at which the authentication took place at the identity provider. Veezoo rejects SAML assertions with an AuthnInstant value that is older than the configured maximum authentication lifetime.

Configure user attributes

When a user authenticates via single sign-on with SAML, a corresponding user gets automatically created in Veezoo. The User attributes subsection lets you configure some of the attributes of these users by defining user attribute mappings:

Attributes

The following attributes can be configured:

Attribute	Description	Multi-valued
Type	The user's type, i.e. if the user is a Creator or a Viewer	no
First name	The user's first name	no
Last name	The user's last name	no
E-mail	The user's e-mail address	no
Language	The user's preferred language, if supported by a given knowledge graph	no
Roles	The user's roles	yes

User attribute mapping

For each user attribute, you can define one or more mappings. After each user authentication, the mappings are evaluated and the corresponding user attributes updated accordingly.

Mappings are evaluated in order from top to bottom. For single-valued user attributes, the first matching mapping is applied. For multi-valued user attributes, all matching mappings are applied.

Each mapping consists of the following fields:

Value

The value to assign for the user attribute, if the condition holds

For some user attributes (e.g. type), the permitted values are predefined and can be selected using the provided dropdown. For other attributes (e.g. first name), the specified value must be either a string or a variable using the syntax of the mapping language.

Condition

The condition which determines if the mapping matches and should be applied (optional)

If set, then the mapping's value is only assigned to the user attribute if the condition is fulfilled, else the mapping is ignored. The specified condition uses the syntax of the mapping language.

Description

The description for the mapping (optional)

Mapping language

The mapping language uses a simple syntax to express values and conditions and allows referencing attributes included in the SAML assertions returned by the identity provider.

String

A string is enclosed in single quotes.

Example: 'abc'

Array

An array encloses a comma-separated list of strings in brackets.

Example: ['a', 'b', 'c']

Variable

A name references an attribute from the SAML assertion.

Simple variables start with an alphabetical character, followed by alphanumerical characters. If the name contains other characters, variables need to be enclosed in backticks.

Examples:

• firstName
• `first-name`
• `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`

Condition

A condition consists of a lefthand-side, an operator and a righthand-side.

The following operators are supported:

Operator	Name	Description
==	Equality	Evaluates to true if the lefthand-side is equal to the righthand-side
!=	Non-equality	Evaluates to true if the lefthand-side is not equal to the righthand-side
IN	Containment	Evaluates to true if the lefthand-side is contained in the righthand-side
NOT IN	Non-containment	Evaluates to true if the lefthand-side is not contained in the righthand-side
AND &&	Conjunction	Evaluates to true if both the lefthand-side and righthand-side evaluate to true
OR ||	Disjunction	Evaluates to true if either of the lefthand-side and righthand-side evaluate to true
NOT !	Negation	Negates the result of the condition

Conditions can be enclosed in parentheses, i.e. ().

Examples:

• Equality
  language == 'fr'
departmentCodes == ['D1', 'D2']
• Non-equality
  language != 'fr'
departmentCodes != ['D1', 'D2']
• Containment
  departmentCode IN ['D1', 'D2', 'D3']
'D1' IN departmentCodes
• Non-containment
  departmentCode NOT IN ['D1', 'D2', 'D3']
'D1' NOT IN departmentCodes
• Conjunction
  language == 'fr' && departmentCode IN ['D1', 'D2', 'D3']
• Disjunction
  language == 'fr' || departmentCode IN ['D1', 'D2', 'D3']
• Negation
  NOT language == 'fr'
! language == 'fr'
• Parentheses
  !(language == 'fr')
((a == '1' OR a == '2') AND NOT(b == '3'))

Remarks

• A string is considered to be equal to an array holding exactly that string
  e.g. 'a' == ['a'] holds true
• The lefthand-side of a (non-)containment condition can be an array
  e.g. ['b', 'a'] IN ['a', 'b', 'c'] holds true

Examples

Consider the following SAML assertion:

<samlp:Response ...>
  ...
    <saml:AttributeStatement>
      <saml:Attribute Name="firstName" ...>
        <saml:AttributeValue ...>John</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="departmentCode" ...>
        <saml:AttributeValue ...>D1</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="language" ...>
        <saml:AttributeValue ...>fr</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="roles" ...>
        <saml:AttributeValue ...>internal-admin</saml:AttributeValue>
        <saml:AttributeValue ...>veezoo-admin</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  ...
</samlp:Response>

The following examples illustrate some mappings and what they evaluate to given the above SAML assertion:

→ The mapping matches and evaluates to abc

→ The mapping matches and evaluates to John

→ The mapping matches and evaluates to John

→ The mapping doesn't match

→ The mapping matches and evaluates to Creator

→ The mapping matches and evaluates to Creator

→ The mapping doesn't match

→ The mapping matches and evaluates to Français

→ The mapping matches and evaluates to the empty string

Test and save the SAML configuration

After having completed the above steps to configure SAML, you can test and save your configuration. Click on the Test & Save button to perform an authentication test with the SAML configuration.

info

The authentication test is performed in an authentication popup window. Please make sure to instruct your browser to allow popups.

After a successful authentication test, a dialog displays the user attributes that resulted from applying the configured user attribute mappings:

You can now go ahead and save the configuration.

If the authentication test failed, please make sure your configuration is correct or contact us for support.

info

If you save a configuration which you enabled/disabled, or which is already enabled, the page will reload after the saving has completed. This is in order for the new authentication method to take effect (if you enabled/disabled the config) or to apply the user attribute mappings to your user (if the config is already enabled).

caution

If you save an enabled configuration which doesn't assign your user the Creator user type, you won't be able save the configuration. This is because after saving, the page would reload and your user (not being a Creator) would not have access to Veezoo Admin anymore.