Skip to main content

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:

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:

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:

User attributes subsection

Attributes​

The following attributes can be configured:

AttributeDescriptionMulti-valued
TypeThe user's type, i.e. if the user is a Creator or a Viewerno
First nameThe user's first nameno
Last nameThe user's last nameno
E-mailThe user's e-mail addressno
LanguageThe user's preferred language, if supported by a given knowledge graphno
RolesThe user's rolesyes

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:

User attribute mapping

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:

OperatorNameDescription
==EqualityEvaluates to true if the lefthand-side is equal to the righthand-side
!=Non-equalityEvaluates to true if the lefthand-side is not equal to the righthand-side
INContainmentEvaluates to true if the lefthand-side is contained in the righthand-side
NOT INNon-containmentEvaluates to true if the lefthand-side is not contained in the righthand-side
AND
&&
ConjunctionEvaluates to true if both the lefthand-side and righthand-side evaluate to true
OR
||
DisjunctionEvaluates to true if either of the lefthand-side and righthand-side evaluate to true
NOT
!
NegationNegates 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:

Mapping example 1

β†’ The mapping matches and evaluates to abc

Mapping example 2

β†’ The mapping matches and evaluates to John

Mapping example 3

β†’ The mapping matches and evaluates to John

Mapping example 4

β†’ The mapping doesn't match

Mapping example 5

β†’ The mapping matches and evaluates to Creator

Mapping example 6

β†’ The mapping matches and evaluates to Creator

Mapping example 7

β†’ The mapping doesn't match

Mapping example 8

→ The mapping matches and evaluates to Français

Mapping example 9

β†’ 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:

Authentication test result

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.