This guide covers setting up Single Sign-on (SSO) with Ardoq using the SAML protocol. Topics covered, in order:
Requirements and supported features
What information should be sent to Ardoq and where to find it
List of preconfigured applications that can be used as a template
How to set up SAML manually using Azure Active Directory as an example
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:
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:
Azure Active Directory
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
Create new enterprise application
When creating, select “Integrate any other application you don’t find in the library”
Go to “Single sign-on” to configure SAML
Upload metadata file that can be found at https://<your-org-subdomain>.ardoq.com/saml/metadata/v2
If your Ardoq domain URL includes any of the following: US/UAE/AUS, please include the ".US/.UAE/.AUS after your-org-subdomain
Example: https://<your-org-subdomain.>.US.ardoq.com/saml/metadata/v2
Set up the necessary attributes
Optional: Set up Ardoq roles for the application
Send metadata file to Ardoq to support@ardoq.com 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.
When setting up attributes for SAML, ensure the attribute names are an exact match between the identity provider (e.g., Azure AD) and Ardoq, as they are case-sensitive. Additionally, make sure the required attributes are provided, and leave the "namespace URI" field blank.
Attribute name | Description | Example mapping in Azure Active Directory |
displayName (Recommended) | 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 |
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:
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:
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.