In this guide we'll set up Single Sign-on (SSO) and user provisioning, by configuring the Ardoq App found in the Azure Active Directory (AAD) App Gallery.
User provisioning is a way to keep users that have been assigned to the Ardoq app in AAD in sync with the list of users found in the Ardoq app itself. If you're interested in how this magic is achieved, you can read more about the SCIM standard here.
If you're not interesting in provisioning, you can stop after configuring SSO. Ardoq supports Just-In-Time provisioning, where users bring with them their name and assigned role and other details as they log in to Ardoq, and that might be good enough in some circumstances. The downside to that approach is that the user list found in the Ardoq App can become out of sync with reality (as described in AAD) and manual cleanup will be required as employees e.g. leave the company.
Prerequisites
The steps detailed in this guide require administrator rights in both Azure AD and in Ardoq.
Time wise, you'll probably be able to finish about one unit of your favorite hot beverage.
Getting started with AAD App Gallery app for Ardoq
Log in to the AAD portal
Navigate to Azure Active Directory
Click on Enterprise Applications in the menu on the left
4. At the top of the screen click on New application:
5. Search for and select the Ardoq app:
6. Click on Create in the ensuing popup.
7. Take a sip of your beverage while the app is copied into your tenant ⏳
Configuring SSO
1. Click on Set up single sign on
2. Select SAML
3. Visit https://<YOUR-SUBDOMAIN>.ardoq.com/saml/metadata/v2
<YOUR-SUBDOMAIN> is the subdomain your organization has chosen to access Ardoq. This is the same URL segment you use when you access the Ardoq app. For example, if your organization accesses Ardoq at https://piedpiper.ardoq.com you'd fill in piedpiper. If you're in the US datacenter and you access Ardoq at piedpiper.us.ardoq.com then you'd fill in piedpiper.us.
5. Copy the content of this page into a program like Notepad (or your favorite editor) and save it (preferably with the file type XML) on your computer.
6. Then upload the file to automatically add the required URLs:
If you didn't save the preceding file in XML format, click All files to make it visible in the file selection popup:
7. After selecting the file, Click Add to upload.
8. You should now have something that looks like the screenshot below (except with URLs appropriate to your organization). Go ahead and hit Save.
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.
Configuring provisioning
1. Click on Provisioning in the menu on the left:
2. Then click on Provisioning again in the new menu on the left:
3. Change Provisioning Mode to Automatic
4. Next, we turn our attention to the Admin Credentials:
Fill in the tenant URL, using this template: https://<YOUR-SUBDOMAIN>.ardoq.com/api/scim/v2 (with a lowercase v) and replace the placeholder text <YOUR-SUBDOMAIN> like we did when configuring SSO a bit earlier in this guide.
5. To fill in the Secret token, we have to generate a bearer token that's used for authentication each time AAD communicates with Ardoq. Please reach out to us via support@ardoq.com or by using the in-app chat to enable SCIM token generation feature.
As a user with administrative rights, log in to Ardoq and:
Go to the Preferences menu
Select Organization settings and then Manage users
Navigate to the Manage SCIM token tab
Click the Generate new button.
The token will only be shown once. If you need to revoke the access token, hit the Revoke button. If you need to generate a new one, just hit the Generate new button again. There's only ever one SCIM token active per organization, so each time you generate a new token the old one stops working.
6. Copy the token you've generated in Ardoq and paste it into the admin credentials as the Secret Token in Azure AD:
7. Click the Test Connection button to verify that it is working correctly. You should see a successful notification in the top right corner:
8. Hit Save:
9. If you now go back to the Overview and then back to Provisioning (exactly where we were). Some new settings have appeared:
We recommend filling in an email address here to receive notifications if anything goes awry. Hit Save again and go back to the Overview page for provisioning.
That's it! You can now optionally test that SSO works as intended, or continue with the guide to also configure provisioning.
If you're ready to turn on provisioning for Azure AD hit Start provisioning. Provisioning runs only every 40 minutes, so it might take a little while before something happens, or before changes to user data are reflected in Ardoq. After the initial cycle has run, you might want to check the provisioning logs to make sure everything went well.
Note: Upon SCIM's request, Ardoq will terminate the user. At that point, we are unable to resolve any metadata information such as (created-by, modified-by, etc.) that links to that user.
To avoid this behavior, please remove access to the Ardoq app for that user. The user will be marked in Ardoq as "inactive" when SCIM notifies us of this. If at a later point the user is deactivated, no message will be sent to Ardoq through SCIM, because the user is no longer assigned to the Ardoq app.