Workiva Support Center

Overview of SCIM

Important: To configure SCIM support for your organization, you must 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.

Supported SCIM features

The following provisioning features are supported:

• Create new users
  New users assigned in the identity provider will also be created in the Workiva platform
• Deactivate unassigned users
  Unassigning users in the identity provider will suspend the user in the Workiva platform
• Deactivating users
  Deactivating users in the identity provider will suspend the user in the Workiva platform
• Profile updates
  Updates made to a user's profile through the identity provider will be updated in the Workiva platform
• Import new users
  New users created in the Workiva platform can be imported into the identity provider and mapped to existing or new users
• Reactivate users
  Reactivating a user or reassigning a user in the identity provider will activate that user in the Workiva platform
• Group push
  A user’s Workiva entitlements, including Organization Roles, Workspace Memberships, Workspace Roles, and Workspace Group Memberships, can be managed by existing identity provider groups.

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.

Important: Please confirm all Workiva usernames have a consistent naming convention and are aligned with how the SCIM tool will be creating users.

Step 1: Create provisioning

To create the identity provisioning and generate the SCIM API credentials:

1. In the top right, click the user icon and select Admin from the dropdown.
2. Then select Organization admin from the dropdown.
   
3. On the Organization Admin page, Select Security in the left menu pane and then select the Provisioning tab. 
   
4. Click Add Identity or API.
   

5. Select Identity Provider in the dropdown.
   

   The following instructions are for an Identity Provider. For an API Grant, refer to Create and manage API grants in Organization Admin.

6. Enter the required fields:
   • Set a Full Name for your association. This name should describe the system which will be sending user information to Workiva, like ‘Okta Production’.

   • Set a Workiva username. SCIM actions in the Activity Log are attributed to this user, and API credentials are generated for them.

     We recommend creating a dedicated SCIM API user with the following roles:

     • Org User Admin (required to create, deactivate, and update users)
     • Org Security Admin (required if SCIM manages Security Admin roles)
     • Org Workspace Admin (required if SCIM manages Workspace memberships, roles, and groups)
     • Workiva AI User (required if SCIM manages AI roles)
     • Org Chain Security Admin (required if SCIM manages Chains roles)

     SCIM can only assign and manage roles that this user already has.

     This account must have a valid email address to generate API tokens. If you later change the Workiva username, the current secret becomes invalid, and only the new user can access the new secret.

     Only this user can view the identity provider secret in My profile > Security.

     Note: If the SCIM API user does not have a role, SCIM cannot assign or manage that role for other users. For example, to provision Workiva AI User or Org Chain Security Admin roles through SCIM, assign those roles to the SCIM API user first.

     Learn how to Update an organization role and view what roles need to be assigned.

   • Set a Credential Type. Consult your identity provider’s documentation to determine which to use.
     • The Workiva application in OIN only supports Basic Auth.
     • A custom app built in Okta can support Bearer Token.
     • If using Azure, select Bearer Token.
   • Optionally, enter a Description for this identity provisioner.
   • Under the Administrator Contact, enter the Full Name and Email Address of a technical contact within your IT department whom we can contact in the event of issues or to communicate future feature enhancements.
7. Click Create Provisioning to finish.

Step 2: Obtain ID and URL values

You’ll need the identity provisioning ID and URL values for Step 4: Configure your identity provider. To obtain these values:

1. In Organization Admin, go to Security > Provisioning.
2. Under the Identity Provider section, find your provisioning and copy the ID and URL values.

Step 3: Obtain Basic Auth or Bearer Tokens

To obtain the new Basic Auth or Bearer Tokens, you’ll need to log into the Workiva application with the SCIM user’s Workiva Username that you specified in Step 1: Create provisioning:

1. Ensure that the SCIM user account has a valid email address that can be accessed, and that the SCIM user has been added to a workspace. This is because a verification email will be sent to the SCIM user’s email in order to log in.

   Note: If SAML SSO is required, you’ll need to add this SCIM user as a SAML SSO bypass user in order to log in with username and password.

   

2. Go to the Workiva login screen, and sign in with the SCIM user’s Workiva username and password (if you’ve previously been using SAML SSO to log in, you’ll first need to click Change User).
3. In the Workiva platform, click on the profile icon in the top right and go to My Profile > Security.
4. In the Identity Provider section, click on the Actions dropdown arrow next to your identity provisioning and click Regenerate.
5. Confirm by clicking Regenerate.
6. You’ll see the Basic Auth Secret and Bearer Token Secret. Copy these secrets down in a secure place, as you won’t be able to see these secrets again.

Step 4: 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.

• 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’.

See the below steps for how to configure common identity providers, or consult your provider’s documentation and support channels if you need assistance.

Step 5: 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 (or descriptions, if using Azure and if policy allows), following a specific convention described below.

Limits and best practices

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

• We highly recommend creating a dedicated API user account for the provisioning since the SCIM service will operate on behalf of that user. SCIM actions in the Activity Log are attributed to the user you select and are required to have the Org User Admin, Org Workspace Admin, and Org Security Admin roles.
  
• Password sync isn’t supported.
• Users invited into the organization from another organization (e.g. auditors or external counsel) can’t be managed by SCIM. If your organization desires to have complete control over third-party users within your Workiva organization, you’ll need to create an identity provider account for them instead of adding the user from another organization.
• First name, last name, display name, and email address fields are required for all users.
• Diacritics aren’t allowed in the name fields. If you have users that have those characters in their name, we recommend modifying the mappings to replace them.
• 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 Step 5: Manage user roles and groups for more details). If they’re 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’re 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.

Error messages

Need help?

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