Classic file types are no longer available for use as of January 2021. You can transition your classic files or download a PDF. Learn More

Manage and provision users with SCIM

  • Last updated on
This article is for:
  • Org Security Admins

 

Overview of SCIM

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

 

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.

 

Step 1: Create provisioning

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

  1. In Organization Admin, click Security > Provisioning.
  2. Click Add Identity or Api.
  3. Select Identity Provider in the dropdown.
    Select Identity Provider
  4. 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 will be attributed to the user you select, and API credentials will also be generated for the user. We recommend creating a dedicated SCIM API user with the Org User Admin, 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: This account needs to have a valid email address for generating tokens.
      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.
    • 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.
  5. Click Create Provisioning to finish.

create provisioning.png

 

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.

id and url.png

 

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.
    email address valid.png
  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.

  1. Log in to your Okta org as an admin.
  2. Open the admin portal.
  3. Open your Workiva app instance.
  4. Go to the Provisioning tab.
  5. In the Settings section, click Configure API Integration.
  6. Enter the URL and ID values that you saved from Step 2: Obtain ID and URL values.
  7. Depending on the credential type that you selected in Step 1: Create provisioning, enter the Basic Auth or Bearer Token that you obtained in Step 3: Obtain Basic Auth or Bearer Tokens as the Password.
  8. Click Test API Credentials. If successfully tested, click Save.
  9. Click To App and scroll down to select the provisioning features that you want to enable. We recommend enabling Create Users, Update User Attributes, and Deactivate Users. Leave the Okta default user attribute mappings as is.
  10. Click Save. You’re now ready to automatically provision and deactivate users through Okta to the Workiva organization level via the Assignments tab.

 

Optionally, to utilize Okta’s Push Groups feature for managing user roles, workspace memberships, and workspace group memberships:

  1. Go to the Push Groups tab and click the settings icon.
  2. Deselect the Rename app groups to match group name in Okta setting. Click Save. This removes the chance of renaming a group in Workiva when linking.
  3. Click Refresh App Groups to update any imports or changes that occurred in Workiva, and ensure that all groups from Workiva are represented in Okta.
  4. Click the Push Groups dropdown and select Find groups by name.
  5. To sync user roles, workspace memberships, and workspace groups from Okta to Workiva, link the Okta groups to the Workiva groups. This will need to be completed for each user role, workspace membership, and workspace group membership that you want Okta to control.
    Note: Okta must push/pull SCIM groups by their display names, following the specific convention as described in Step 5: Manage user roles and groups.
    Note: Only linking Okta groups to SCIM groups is supported.
  6. Click Save.
  7. The push groups will then appear in the push groups list with an Active status if linking is successful.
  1. Create a custom application for provisioning, as the Workiva gallery app doesn’t support SCIM at this time. Click Create your own application and enter Workiva as the name. Select the Integrate any other application you don’t find in the gallery (Non-gallery) option, and then click Create.
  2. Once the custom application has been created, log in to your Azure org as an admin.
  3. Open the admin portal.
  4. Open your Workiva app instance.
  5. Go to Provisioning, and click Get started.
  6. Set the Provisioning Mode to Automatic.
  7. Enter the URL that you saved from Step 2: Obtain ID and URL values in the Azure Tenant URL field.
    Note: There is a known issue in Azure with managing groups. To work around this issue, append "?aadOptscim062020" to the end of the Tenant URL. See here for more details.
  8. Enter the Bearer Token that you obtained in Step 3: Obtain Basic Auth or Bearer Tokens in the Azure Secret Token field.
  9. Click Test Connection. If successfully tested, click Save.
  10. In the Mappings section, click Provision Azure Active Directory Users.
  11. On the Attribute Mapping page, set Enabled to Yes.
  12. Under Target Object Actions, select Create and Update. Do not select Delete, as Workiva won’t delete user profiles, but will only deactivate them.
  13. Set the Attribute Mappings as shown in the following table:
    customappsso Attribute Microsoft Entra ID Attribute
    userName mail
    active Switch([IsSoftDeleted], , “False”, “True”, “True”, “False”)
    displayName displayName
    title jobTitle
    emails[type eq “work”].value mail
    preferredLanguage preferredLanguage
    name.givenName givenName
    name.familyName surname
    externalId mailNickname

 

Optionally, to utilize Azure’s Push Groups feature for managing user roles, workspace memberships, and workspace group memberships:

  1. In the Provisioning > Mappings section, click Provision Azure Active Directory Groups.
  2. On the Attribute Mapping page, set Enabled to Yes.
  3. Add two scoping filters to the Source Object Scope field. This Source Object Scope allows Azure to create an overall Workiva group that won’t be synced as a group in order to mitigate errors in the logs.
    • For the first scoping filter:
      • Set Source attribute to description.
      • Set Operator to INCLUDES.
      • Set Clause value to workspace:
      • Enter the Scoping Filter Title as Workspace Filter.
    • For the second scoping filter:
      • Set Source attribute to description.
      • Set Operator to INCLUDES.
      • Set Clause value to role:
      • Enter the Scoping Filter Title as Role Filter.
  4. Under Target Object Actions, select Update.
  5. Set the Attribute Mappings as shown in the following table
    customappsso Attribute Microsoft Entra ID Attribute
    displayName description*
    externalId objectId
    members members

    *This source attribute may change depending on environment and policies.

  6. To sync user roles, workspace memberships, and workspace groups from Azure to Workiva, Azure must push/pull SCIM groups by their display name, custom expression, or description (if policy allows), following the specific convention as described in Step 5: Manage user roles and groups. This process can be completed for each user role, workspace membership, and workspace group membership that you want Azure to control.
    Note: If policy allows Azure to modify the description attribute of an Azure security control group, then you can push/pull SCIM groups by their description. This allows Azure to keep the existing Azure group naming convention in the directory. To do this, set the attribute mapping to: customappsso Attribute displayName to Microsoft Entra ID Attribute description.
  7. Go back to Provisioning, and in the Settings section, set the Scope as Sync only assigned users and groups.
  8. Set Provisioning Status to On.
  9. Go back to the main Provisioning page under the Workiva app instance and click Provision on demand to test if the users are being provisioned correctly in Workiva.
    Note: There may be an error if you try to push a Workiva All Users group because Azure will try to push the group as a group, instead of as users.
  10. Once testing is successful, click Start provisioning, which will start Azure’s initial provisioning cycle. The provisioning interval is set to 40 minutes and may take a while depending on population size and push groups.

 

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.

Entitlement Display name format Details
Organization Role role:<role name>

Persons assigned to a group with this name will be assigned the organizational role specified.

For example, adding a user to the SCIM group ‘role:Org Security Admin’ will grant the user the ‘Org Security Admin’ organizational role.
Workspace Member workspace:<workspace name>

Persons assigned to a group with this name will be added as members of the specified workspace, and an email notification welcoming them to the workspace will be triggered.

For example, adding a user to the SCIM group ‘workspace:ABC Corp Internal Audit’ will grant the user access to the ‘ABC Corp Internal Audit’ workspace and the default ‘Workspace Member’ role.
Workspace Role workspace:<workspace name>:role:<workspace role name>

Persons assigned to a group with this name will be given the specified workspace role in the specified workspace. They must already be a member in the workspace. 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.

For example, adding a user to the SCIM group ‘workspace:ABC Corp Internal Audit:role:Manager’ will grant the user the ‘Manager’ role in the ‘ABC Corp Internal Audit’ workspace.
Workspace Group workspace:<workspace name>:group:<workspace group name>

Persons assigned to a group with this name will be added to the specified workspace group in the specified workspace. They must already be a member in the workspace. 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.

For example, adding a user to the SCIM group ‘workspace:ABC Corp Internal Audit:group:Editors’ will add the user to the ‘Editors’ workspace group in the ‘ABC Corp Internal Audit’ workspace.

 

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.
    org roles.png
  • 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

Old message New message Cause of error Solution
'{ATTRIBUTE NAME}' not found Invalid '{ATTRIBUTE NAME}' The provided value for  '{ATTRIBUTE NAME}' is invalid Check that the value for '{ATTRIBUTE NAME}' is correct
'{ATTRIBUTE NAME}' does not exist Invalid '{ATTRIBUTE NAME}' The provided value for  '{ATTRIBUTE NAME}' is invalid Check that the value for '{ATTRIBUTE NAME}' is correct
'{ATTRIBUTE NAME}' already exists The '{ATTRIBUTE NAME}' already exists The provided value for '{ATTRIBUTE NAME}' already exists Enter a unique value for '{ATTRIBUTE NAME}'
'{ATTRIBUTE NAME}' contains invalid whitespace characters The '{ATTRIBUTE NAME}' contains invalid whitespace characters The provided value for '{ATTRIBUTE NAME}' can't contain whitespace characters Remove whitespace characters
'{ATTRIBUTE NAME}' contains invalid characters '{ATTRIBUTE NAME}' contains invalid characters The provided value for '{ATTRIBUTE NAME}' is invalid Enter a valid value for '{ATTRIBUTE NAME}'
'{ATTRIBUTE NAME}' contains '=', which is not permitted '{ATTRIBUTE NAME}' contains the invalid character '=' The provided value for '{ATTRIBUTE NAME}' contains an invalid character Enter a valid value for '{ATTRIBUTE NAME}'
'{ATTRIBUTE NAME}' is too long '{ATTRIBUTE NAME}' can't be more than 255 characters The provided value for '{ATTRIBUTE NAME}' is too long Enter a value that's 255 characters or less
Endpoint does not exist Invalid endpoint The provided endpoint is invalid Check the schema definition
Method not allowed Unsupported HTTP method You tried using an HTTP method that is not supported by the endpoint Check which HTTP methods are supported by the target endpoint
Cannot modify role name Can't modify role name You tried to modify a role name Role names can't be modified
You've incorrectly formatted your group name by providing an invalid workspace identifier Invalid 'workspaceName' The provided workspace name is invalid Check that the workspace name is correct
Must be a well-formed email address Invalid email address The provided email address is invalid Enter a valid email address
Email domain not allowed The email domain has been restricted The provided email domain has been restricted Use a different email domain, or remove the email domain from the domain restrictions under Security > Access Restrictions > Email Domains.
Invalid timezone Invalid timezone The provided timezone is invalid Enter a valid timezone
Invalid locale Invalid locale The provided locale is invalid Enter a valid locale. The valid locales are "de_DE", "en_US", "es_AR", "es_ES", "es_MX", "fr_FR", "fr_CA", "it_IT", "nl_NL", "pl_PL", "zh_CN", "zh_TW", "ja_JP", "ko_KR", and "pt_BR".
OfficePhone is too long Invalid phone number The provided phone number is invalid Enter a valid phone number, or contact Technical Support
Invalid comparison value at... Invalid 'filter' expression The provided filter expression is invalid Refer to https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2
Unexpected character '@' at position 18 for token starting at 0 Invalid 'filter' expression The provided filter expression is invalid Refer to https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2
Unexpected end of filter string Invalid 'filter' expression The provided filter expression is invalid Refer to https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2
Unknown filter property Invalid 'filter' expression The provided filter expression is invalid Refer to https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2
Core attribute '{ATTRIBUTE NAME}' is undefined for schema Undefined attribute '{ATTRIBUTE NAME}'. Check the schema definition. The attribute isn't defined in the schema definition Check the schema definition
Attribute '{ATTRIBUTE NAME}' does not have a multi-valued or complex value Attribute '{ATTRIBUTE NAME}' can't accept multi-values or complex values The attribute can't accept multi-values or complex values Check the schema definition for what the attribute expects
Must not be null target: '{ATTRIBUTE NAME}' A value for '{ATTRIBUTE NAME}' is required Values for required fields weren't provided Check the schema definition for the required fields
No '{ATTRIBUTE NAME}' provided A value for '{ATTRIBUTE NAME}' is required Values for required fields weren't provided Check the schema definition for the required fields
Must not be blank A value for '{ATTRIBUTE NAME}' is required Values for required fields weren't provided Check the schema definition for the required fields
The principal does not belong to workspace membership The user isn't a member of the workspace You tried adding a user to a group that belongs to a different workspace Add the user to the workspace first. Then add the user to the group.
Forbidden You don't have access. Contact Technical Support. You don't have access Contact Technical Support for access
Internal server error Something went wrong. Contact Technical Support. Something went wrong on our end Contact Technical Support

 

Need help?

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

Was this article helpful?
8 out of 14 found this helpful
This article is for: Org Security Admins   Overview of SCIM To configure SCIM support for your organization, y...