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