All Collections
Administration of Ardoq
SSO Management
Setting up Single Sign-on using SAML
Setting up Single Sign-on using SAML

Learn how to get started with Single Sign-on using SAML, with an example from the identity provider Azure Active Directory/Microsoft Entra

Kristine Marhilevica avatar
Written by Kristine Marhilevica
Updated over a week ago

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

NOTE: Reach out to your CSM or ask support to create a subdomain or do the subdomain change. Remember to send the current organization's name in Ardoq and the subdomain you would like to use instead of "app" in the link https://app.ardoq.com. Please be aware that the links to earlier sent-out surveys and presentations, bookmarks to workspace, etc. will be inaccessible and will e.g. need to be changed manually by the end-user.

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 Azure Active Directory, this file is called a Federation Metadata XML-file and can be found here:

Ardoq finding metadata file in active directory

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

Ardoq finding metadata in Okta

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 Azure 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

    1. If your Ardoq domain URL includes any of the following: US/UAE/AUS, please include the ".US/.UAE/.AUS after your-org-subdomain

      1. Example: https://<your-org-subdomain.>.US.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 to support@ardoq.com so that we can finalize the setup

1. Create new enterprise application

Ardoq creating your own enterprise application
Ardoq creating your own enterprise application

2. Configure SAML sign-on for the new application

Ardoq configuring SAML-sign on

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:

Ardoq SAML-based sign on upload metadata file to configure relevant 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 Azure 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 Azure 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

Ardoq manage claim

Ardoq user attributes and claims active directory

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


5. Optional: Setting up roles

If you want to manage user roles in Azure 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.

NOTE: If you came here from the SCIM article for AAD make sure the "display name" matches the values enumerated below. Due to a long-standing bug in the AAD SCIM integration Microsoft will consistently send the "display name" instead of the "value" when role updates for users are sent to Ardoq.

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:

Ardoq adding a role to app registration
Ardoq adding a role to app registration
Ardoq adding a role to app registration

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 Azure Active Directory, I get a warning about the user "not being assigned a role with the application"

Example of what this error looks like:

Ardoq example sign in error Active Directory

This is an error in the configuration in Azure 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 Azure 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 Azure Active Directory)

After SSO set up, the Full Name field in Ardoq is not getting populated"

The name attribute can either be populated by configuring a claim for:
 - displayName
 - or firstName and lastName

Changing domain

Changing the domain will not cause an issue. As long as it doesn't conflict with an existing account, it should auto-update when they log in.

After how long is an inactive user logged out of the Ardoq app.

Sessions expires after an hour and currently this is not customizable.

Did this answer your question?