User provisioning (SCIM)

Customers using Single Sign-on also have access to user provisioning & de-provisioning via Dscout's implementation of industry standard SCIM API. This feature allows customers to use their identity provider (IdP) to securely create Dscout accounts for their users, keep their information (name, email, etc.) in sync, and revoke access to Dscout (de-provision) .

Your Dscout account owner and/or IdP administrator will manage access to Dscout. When your Dscout account is ready, they will provide login instructions.

If you're using Okta, refer to this guide.

If you're not using Okta, read on or click the links below to learn more:

• Generating an API key
• Using user provisioning (SCIM) exclusively
• What to do after provisioning
• API features
• Base URL and authentication
• Supported resources and attribute mapping
• Groups
• Special callouts for specific identity providers
• FAQs

Generating an API key

Dscout account owners may generate an API key on the Dscout settings page. Upon clicking “Generate API key” you will be prompted to name your key. You may then work with your organization’s IdP administrator to enter this key into your IdP’s authentication configuration for your Dscout connection.

Using user provisioning (SCIM) exclusively

Once your API key is generated and you’ve successfully connected your identity provider to Dscout, we strongly recommend toggling this setting on to only allow users to be managed via user provisioning (SCIM). Once this setting is on, you will no longer be able to add or remove users from the platform without first provisioning or de-provisioning them in your IdP.

What to do after provisioning

Users that are provisioned will be added to Dscout as a viewer. Inside Dscout you can choose the right role for new users by going to the Users page in account management. Additionally, you can add users to projects using either the “add users to projects” button on the projects page or using the “Add collaborators” button directly on the project.

API features

Dscout's SCIM API is based on the Open standard: System for Cross-domain Identity Management 2. Our implementation uses version 2.0 of the protocol. The API has been tested against Okta, OneLogin and Microsoft Entra ID (formerly named Azure Active Directory) and should work with any identity provider using the SCIM protocol.

Base URL and authentication

The API’s base URL is https://app.dscout.com/scim/v2. It expects the generated key to be provided in the requests header as a Bearer token.

# Curl example 
curl --request GET \ 
--url  https://app.dscout.com/scim/v2/Users \
--header 'Authorization: Bearer YOUR_API_KEY'

Supported resources and attribute mapping

Users

User attributes should be mapped as follows:

Dscout's API supports the following actions for users:

• List all provisioned users
• Create a new user
• Get a user by ID
• Replace user by ID
• Update user attribute by ID

Please note the absence of a delete user action. When it is time to revoke Dscout access for a user, our API expects SCIM clients to send a PUT or PATCH request with active=false. This action will make the user as deactivated, convert them to a free “viewer” seat and prevent them from logging into the platform. Additionally, your account manager can then choose to delete their record from user management in the account settings.

Special callouts for specific identity providers

Microsoft Azure Entra ID

Microsoft has documented several known issues with their compliance against the SCIM 2.0 specification. Dscout requires the addition of the their recommended query parameter
(?aadOptscim062020) in order for your integration to work properly. Your tenet URL should read as follows:

https://app.dscout.com/scim/v2?aadOptscim062020

Groups

Group attributes should be mapped as follows:

Dscout’s API supports the following actions for groups:

• List all groups
• Create a new group
• Get a group by ID
• Replace group by ID
• Update group by ID
• Add, remove, or replace group members by group ID
• Delete a group by ID

The primary use case for SCIM groups in Dscout is mapping group members to a specific role. When you create groups via SCIM, you’ll see them beneath your SCIM API key configuration. By default, all groups map to Dscout's “viewer” role. Optionally, you can change these mappings to other seat types. Now, when one of your users is added to that group, their role will update to the group’s specified role mapping.

A few callouts about groups, group members and role mappings:

• You can always override a user’s role by changing their role on the user’s page of account management.
• Dscout define’s the role hierarchy as Admin (highest), Researcher, Contributor, Viewer (lowest).
• Dscout’s API will never downgrade a user’s role. For example, if a user has an Admin role and is then added to a group with a Viewer mapping, they will continue to be an Admin.
• Conversely, Dscout’s API will upgrade a user’s role. For example, if a user has a Viewer role and is added to a group with an Admin mapping, their role will change to Admin.
• The account owner’s role will never change.
• Once your account has exhausted its purchased seats for a certain type, users will mapped to Viewer role.

FAQs

After enabled SCIM, will all of my current users assigned to the application be migrated to Dscout?

No. Only users updated or added after SCIM is enabled are added.

I’m an existing customer and have already added many users in Dscout. How do I sync them with my identity provider?

In your identity provider, simply assign all relevant users to Dscout. If the user does not already exist in Dscout, their account will be provisioned. If the user was previously added manually in Dscout, this process with sync those records (please confirm that user’s email in your identity provider matches the user’s email on their existing Dscout account).

Will newly provisioned users receive a notification or invite from Dscout?

No. Dscout will not notify new users upon provisioning. We leave their notification in your hands after you’ve made any necessary adjustments to their role and/or added them to any workspaces or projects.

I deprovisioned a user from Dscout in my identity provider, but they are still showing up in Dscout.

Our SCIM API accepts “deactivation” requests from your identity provider, but we do not delete the user from your account. Instead, we mark them as “deprovisioned” and disallow the user from accessing Dscout. You (or your account owner) can login to Dscout once the user is deactivated and remove them.

How can I learn more about SCIM?

There are many good references on the internet. Here are a few:

• Overview of SCIM
• Understanding SCIM - Okta
• SCIM: Core Schema
• SCIM: Protocol