Manage users and teams with SCIM and Okta

Configuring SCIM for your Sigma organization allows you to centralize management of users and teams through Okta. This document covers Okta-specific configuration considerations and tasks.

For a general overview of SCIM with Sigma, see Manage users and teams with SCIM.

System and user requirements

You must be assigned the Admin account type to initiate provisioning.
Your Sigma organization must already be authenticated with Okta using SAML. Your organization cannot use a password-based authentication method, such as SAML or password.

Limitations

Importing groups from Sigma teams is currently unsupported. Instead, create the group in Okta and push it to Sigma.
Importing users using the Link to an existing user in Okta option is currently unsupported. Instead, assign the Sigma app to the user you want to link.

Supported provisioning features

The following provisioning features are supported:


New users	New users added to the Okta app are automatically added as users in Sigma. If a Sigma account type isn’t specified in Okta, the default `View` account type is assigned.
User profile updates	Updates made to the user’s name and user type in their Okta profile are automatically pushed to Sigma.
Deactivate users	Deactivating a user through Okta deactivates the user in Sigma. The user’s profile information is maintained in Sigma as an inactive user. Ownership of any documents created by the user is transferred to the Admin user performing the deactivation. If your organization uses a service account to manage SCIM bearer tokens, the deactivated user’s documents are transferred to the longest-tenured admin in the organization, excluding the user being deactivated. If no other active admin user exists, you are blocked from deactivating the user.
Reactivate users	Sigma users can be reactivated by reactivating the corresponding account in Okta Reactivated users automatically regain their Sigma team memberships, if they were added to Sigma via an Okta group.
Push groups	Groups created in Okta are created as teams in Sigma.
Push group updates	Updates made to a group (group name and members) in Okta are pushed to the corresponding team in Sigma.
Deactivate groups	Deactivating a group in Okta deactivates the corresponding team in Sigma. Any documents located in the team’s workspace folder are automatically transferred to the My documents folder of the admin performing the deletion.

Considerations when transitioning to SCIM with Okta

If you have existing Sigma users and teams before setting up SCIM with Okta, the following considerations apply.

Existing users and teams created in Sigma

Existing users and teams remain in Sigma. However, they are no longer editable through the Sigma Admin portal. Instead, you must manage them through Okta:

Users: Okta lets you link to an existing user with the same email address in Sigma. The user’s work is not lost, and you then maintain Admin management of that user. Alternatively, you can import users from Sigma into Okta.
User account types: If you change management of a user originally created in Sigma over to Okta, Sigma uses the account type defined in Okta, regardless of what was originally set in Sigma.
Teams: Okta allows you to link a group in your application to an existing team in Sigma. When the link is created, any changes to group membership in Okta are automatically reflected in Sigma teams.

Existing users created in Okta with SAML

Okta requires that any users already assigned to the app be removed and re-added when provisioning is switched on for an existing application. This process does not result in the loss of any user work in Sigma.

Sigma recommends the following process:

When reassigning users, your users are temporarily removed from the application and can’t log in to Sigma. Select a time outside of business hours to reduce impact.

Create Okta groups for your users prior to removing them from your application. Creating groups instead of adding users individually is recommended because if you have a large user base, reassigning the temporarily removed users in groups reduces the period of time that the users are unable to log in to Sigma. You can also repurpose these groups when you push Okta groups to Sigma to create teams.
Unassign all users from your Sigma application in Okta.
Enable SCIM provisioning in Sigma.
Re-assign all users to your application.
Push groups to create Sigma teams.

Configure SCIM with Okta

To configure SCIM for your Sigma organization with Okta, perform the following steps:

Enable provisioning in Sigma

Enable user and team provisioning in Sigma. Refer to the steps in Enable provisioning in Sigma for SCIM generally, then follow the steps below for Okta-relevant steps.

Configure provisioning in Okta

Configure an Okta app integration for Sigma. See the Okta documentation on Configure provisioning for an app integration. When prompted for an API Token, enter the Bearer token that you received when setting up provisioning in Sigma’s Admin portal.

When configuring the app, ensure that the Provisioning to App setting, the Create Users, Update User Attributes, and Deactivate Users options are enabled.

Add users

Do not use SCIM provisioning for the same user across multiple IdPs. Users should be provisioned by a maximum of one IdP to avoid conflicts in information between IdPs.

Add users in Okta individually or by group. See the Okta documentation on Assign an app integration to a user or Assign an app integration to a group.

When adding users, ensure the following are configured:

Confirm that each user has a given name and family name configured in Okta.
The user type attribute is case-sensitive. When configuring default account types (Admin, Build, Act, Analyze, View), the value indicated should be lower case (e.g. “view”). Other account type configurations are also case-sensitive, and the value set in your IdP must match the value in Sigma exactly, or errors may occur when trying to provision users.

When assigning type attributes to a group in Okta, any users previously assigned a Sigma account type individually keep their existing account type, rather than inheriting their group-assigned account type.

Provisioning users and groups can take upwards of 30 minutes. You can verify that the new users have been added and assigned the correct account type by checking the Users page in Administration in Sigma.

Push groups

Groups in Okta are equivalent to teams in Sigma. After configuring provisioning in Okta, you can’t create new teams in the Sigma Administration portal. All new teams must be created as groups in Okta and pushed to Sigma. Existing teams created in Sigma prior to setting up provisioning remain accessible (but not editable) from the Sigma Administration portal.

See the Okta documentation on Enable Group Push (to create a team in Sigma) or Configure Group Linking (if a team with the same name already exists in Sigma).

Provisioning users and groups can take upwards of 30 minutes. You can see the push status of each group in Okta. Once marked Active, the group appears as a team in Sigma.

Push embed users with SCIM

You can use Okta (or other IdP) to push and sync both internal and embed users using SCIM through a custom user profile attribute in your IdP. This enables you to maintain separation of embed and internal users, while still managing them under the same IdP. Your internal users can access content from the native Sigma application or a Sigma embed, while your embed users can only access content from a Sigma embed. You must:

Configure Sigma authentication as SAML only.
Set up the web application hosting Sigma embed to leverage the same IdP.
Disable automatic embed user generation.
- Generate JWTs with the sub claim only.

The following is an example using Okta to add a custom user profile attribute. To configure your user profile attributes:

In your Okta Admin Console access the Apps section of the Profile Editor page.
Select the user profile you want to apply a custom attribute for.

Configure these values on the custom attribute to differentiate internal and embed user:

Field	Description
Display name	UserKind or User Kind. It’s recommended that you use this as a naming convention, as it matches the fields in the Sigma API.
External namespace	Use this schema extension for embed users `urn:sigma:scim:schemas:extension:2.0:User`
Enum	Select this checkbox to display and add attribute members.
Attribute members	Add your display names and values. Sigma expects these values to be: `internal` `embed` `guest`
Attribute members	Select the Personal option

Save the attribute to return to the Profile Editor page. Select the Mappings option.
Select the new custom attribute from the drop down menu.
Select the Apply mapping on user create and update option from the drop-down menu to apply the new custom attribute to the user profile.
Click Save Mappings.

For more information on applying new or custom account types, see Adding New Custom Account Types to Okta Using SCIM.

Troubleshooting

Some common issues and questions when configuring SCIM with Okta and possible solutions:

Error while trying to push profile update for {email address}: Bad Request

If you encounter the following error, remove all existing user types in Okta, then re-add the user types in Okta again, matching the Sigma account types found in Sigma.

Error while trying to push profile update for {email address}: Bad Request. Errors reported by remote server: Request is malformed: Error: Expecting string at 0.1.userType but instead got: null.

For a step-by-step guide for troubleshooting common issues when integrating Sigma with Okta using SAML and SCIM, see Authentication Troubleshooting Guide for Okta Integration with SAML & SCIM in the Sigma Community.

For additional assistance, contact Sigma Support.