Manage and provision users with SCIM

Overview of SCIM

Follow the steps below to configure SCIM support for your organization. To configure SCIM, you need to be an Org Security Admin.

What is SCIM?

System for Cross-domain Identity Management (SCIM) is an open specification that is designed to make managing user identities simple and automatic. Using SCIM, you can manage the creation and suspension of Workiva users automatically through SCIM-enabled identity providers, such as Okta, SailPoint IdentityIQ, PingFederate, OneLogin, Azure Active Directory, and more.

Additionally, SCIM’s supports Groups to enable management of organization roles, workspace memberships, workspace roles, and workspace groups. This allows you to manage the entire user lifecycle from your preferred identity provider.

SCIM uses the latest version of the standard, SCIM 2.0, published in 2015. The service is reached over HTTPS, just like your browser does today, and requires no new firewall rules or network modifications.

Note: Workiva only supports and helps troubleshoot configurations for commercially or freely-available SCIM clients.

SCIM and SAML single sign-on

SCIM should be used in conjunction with SAML-based single sign-on (SSO), which provides access to Workiva through your identity provider (IdP). Before you configure SCIM settings, make sure you’ve reviewed Basics of SAML single sign-on and Configuring SAML single sign-on.

Step 1: Add an identity provider

First, you need to configure an identity provider in your organization. To add an identity provider:

1. In Organization Admin, click Security.
2. Click Provisioning.
3. Click Add Identity or Api.
4. Select Identity Provider in the dropdown.

Step 2: Enter identity provider info

Now you are ready to create a new identity provider:

1. Set a Full Name for your association. This name should describe the system which will be sending user information to Workiva, for example ‘SailPoint Production’.
2. Set a Workiva Username that the SCIM service will operate on behalf of. SCIM actions in the Activity Log are attributed to the user you select, and API credentials are generated for the user as well. We recommend creating a dedicated user with the Org Security Admin and Org Workspace Admin roles for this purpose. Only this user will be able to view this identity provider’s secret in My profile > Security.
   

   Note: For security purposes, if you later change the Workiva Username, the current secret will become invalid, and only the new user will have access to the new secret.

3. Set a Credential Type. Consult your identity provider’s documentation to determine which to use. If your identity provider supports both, we recommend using Bearer Token.
4. Optionally, enter a Description for this identity provider.
5. Under the Administrator Contact, enter the name and email address of a technical contact within your IT department who we can contact in the event of issues or to communicate future feature enhancements.
6. Click Create Provisioning to finish.

Step 3: Configure your identity provider

After you create an identity provider, you can then configure your cloud-based or on-premise identity provider software to connect to Workiva. The exact steps required depend on your identity provider; please consult your provider’s documentation and support channels if you need assistance.

• Ensure you are setting up a connection with SCIM 2.0, as we do not support previous versions of the SCIM protocol.
• If you are utilizing the Basic Auth credential type, be aware that references to ‘username’ in your Identity Provider software is synonymous with ‘ID’ and ‘password’ is synonymous with ‘credential’.

Only the user who’s listed in the identity provider’s details can view their identity provider’s secret by going to My Profile, selecting the Security tab, then clicking Regenerate in the Actions dropdown next to the identity provider. The user can only view the secret once, so they’ll need to copy down the secret in a secure place. If they lose the secret, they’ll need to regenerate the secret again.

Step 4: Manage User Roles and Groups

You can assign organization roles, workspace memberships, workspace roles, and workspace groups through SCIM groups. To use SCIM groups for managing membership and roles, your identity provider must push/pull SCIM groups by their display names, following a specific convention described below.

Limits and best practices

As you work with users, roles, and groups SCIM, here a few things to keep in mind:

• When using SCIM groups to add a user to a workspace role or workspace group, the user being added must already be a member in the workspace (see the table above for more details).
• If they are not already a member in the workspace, our system will hold for up to 30 seconds before failing while we wait for your identity provider to request the user be added to the workspace. If they are added before time runs out, this action will be resumed and completed successfully.
• When performing bulk assignments of users (20+) into workspace roles or workspace groups, best practice is to ensure that the users are first given a workspace membership, and then assigned with workspace roles or workspace groups in subsequent calls from your identity provider. This order of operations ensures that users have been properly added to a workspace before additional changes, such as workspace role additions, are attempted.

Need help?

If you run into any issues or need help setting up an identity provider, you can contact Support for assistance.