This guide covers setting up Single Sign-on (SSO) with Ardoq using the SAML protocol. Topics covered, in order:

  1. Requirements and supported features

  2. What information should be sent to Ardoq and where to find it

  3. List of preconfigured applications that can be used as a template

  4. How to set up SAML manually using Active Directory as an example

  5. Troubleshooting FAQ (for when things go wrong)

Requirements and supported features

To use this sign-in method, your organization must have a dedicated subdomain (example: https://<your-organization>.ardoq.com).

This method supports "Just-in-time provisioning", which means that users will have an Ardoq account created automatically the first time they log in, and they will be assigned a default role.

This method also optionally supports role assignments from the identity provider. If the SSO-application has been configured to provide Ardoq with a user's "assignedRoles", Ardoq can be configured to leverage this information instead of always assigning the default role to new users.

If "assignedRoles" are provided, it is also possible to fully manage user roles on the identity provider side instead of doing so within Ardoq.


Information to send to Ardoq

When you’re done configuring the SAML integration, send the identity provider metadata file (also called the “federation metadata XML file”) to your Customer Success Manager and/or support@ardoq.com. We will then make the necessary configuration on our end and get back to you within one or two working days. If you have multiple organizations (for example a sandbox environment), also let us know which organization you want to set up SSO for.

Where to find the metadata file

In Active Directory, this file is called a Federation Metadata XML-file and can be found here:

In Okta you can find the Identity Provider metadata file here:


List of preconfigured applications

Ardoq provides preconfigured applications that simplify the process of setting up SSO using SAML:

Contact support@ardoq.com and request an application for your identity provider!


Manually setting up an application with SAML single sign-on

If no application exists for your identity provider, it’s also possible to set up the integration manually. This guide uses Active Directory as an example, but the concepts should be similar in other identity providers as well.

Overview

  1. Create new enterprise application

    1. When creating, select “Integrate any other application you don’t find in the library”

  2. Go to “Single sign-on” to configure SAML

  3. Upload metadata file that can be found at https://<your-org-subdomain>.ardoq.com/saml/metadata/v2.

  4. Set up the necessary attributes

  5. Optional: Set up Ardoq roles for the application

  6. Send metadata file to Ardoq so that we can finalize the setup

1. Create new enterprise application

2. Configure SAML sign-on for the new application

3. Upload metadata file to configure relevant URLs

Visit https://<your-domain>.ardoq.com/saml/metadata/v2, save the page as XML, and then upload it to automatically add the required URLs:

4. Setting up attributes

NB: This step can be skipped when using the preconfigured Ardoq-application from the app gallery.

Ensure that the following attributes are provided. Also ensure that the “namespace URI” is left blank.

Attribute name

Description

Example mapping in Active Directory

displayName (optional)

The user’s name. If omitted, the user will be created with a blank name

user.displayname

email (required)

The user’s email address.

user.mail

id (required)

A unique identifier for the user.

user.userprincipalname

assignedRoles (optional)

If you want to assign roles to users in Active Directory, then ensure that this attribute is provided

user.assignedroles

firstName (optional)

If your identity provider does not provide a “displayName”, you can optionally assign “firstName” and “lastName” instead

user.givenname

lastName (optional)

If your identity provider does not provide a “displayName”, you can optionally assign “firstName” and “lastName” instead

user.surname


In the above images, you see an example of how we can set up the "lastName" attribute in Active Directory. Note that the "namespace"-field is left empty.


5. Optional: Setting up roles

If you want to manage user roles in Active Directory, you must use the "app registrations"-experience to add roles that can then be assigned to users or groups (read more about that here).

We support the following roles. Ensure that the “value” matches the expected values listed below. There are no special requirements for the display name and description fields.

Role

Expected value

Administrator

admin

Writer

writer

Reader

reader

Contributor

contributor

Below is an illustration showing how you can add a role to the application:

Troubleshooting FAQ

When logging in for the first time, a white screen shows with the message "Invalid <Assertion> signature"

This indicates that the certificate is incorrect. Typically, this happens because the IDP Metadata-file was submitted to Ardoq and then some reconfiguration caused the certificate to change in the identity provider.

This can be solved by submitting the up-to-date metadata file again so that we can make the necessary adjustments


When logging in with Active Directory, I get a warning about the user "not being assigned a role with the application"

Example of what this error looks like:

This is an error in the configuration in Active Directory, indicating that the SSO-application has been configured to require user assignment, but the user has not yet been assigned to the application.

This can be solved either by:

  • Changing the "User assignment required?" setting to "No" (can be found on the application properties page in the "Enterprise applications" experience in Active Directory)

  • Assigning the user to the application either directly or as part of a group. Please note that this error does not mean that an "Ardoq role" (i.e. writer/reader) is required. It is sufficient that the user is present in the application's user-list (found in the "Users and groups"-section for the application in the "Enterprise applications" experience in Active Directory)

Did this answer your question?