SCIM user management

Plan requirement

SCIM user management is available only for organizations on the Shopify Plus plan.

After you verify your domain and set up Security Assertion Markup Language (SAML) authentication for your organization, you can generate a System for Cross-domain Identity Management (SCIM) API token. Generating SCIM tokens for users is available only to organizations on the Shopify Plus plan.

Features

Providing the SCIM API token to your identity service provider allows you to take the following actions through your identity provider:

• Create users
• Assign or update groups
• Deactivate users

Requirements for SCIM management

Before you set up SCIM user management, you need to verify your domain and create a SAML configuration. You can only manage users who are associated with a domain that you've verified for your organization.

Considerations for SCIM management

Review the following considerations for using SCIM management for your users:

• Users created through SCIM don't receive an invitation email. The user must log in through the identity service provider to activate their account.
• After adding the API token, when you add a new user who didn't previously exist in Shopify either through your identity provider or Users settings, your new user is set to Pending status. If your user is required to log in using SAML, then they remain in Pending status until they log in using your identity provider.
• The group name in your identity service provider and the group name in your Shopify admin must be identical. The group name in the identity service provider must match the optional custom Group attribute used to sync with Shopify, not the standard identity service provider Groups attribute.
• Store owners and organization owners can't be removed through an identity service provider. Both types of ownership must be transferred before the user can be removed. If you need to change the store owner, then you can do so from your Shopify admin. If you need to change the organization owner, then contact Shopify Plus Support.

Configure SCIM user management

To configure SCIM management, you need to generate an API token from your Shopify admin, and then complete the configuration in your chosen identity service provider.

1. From your Shopify admin, go to Settings > Users.

2. Click Security.

3. In the SCIM integration section, click Generate API token.

4. Click Copy to copy the generated token to your clipboard.

5. Provide the token to your identity service provider. The procedure for adding the token depends on which identity service provider you use.

Note

If you use an identity service provider other than Okta, OneLogin, or Entra, then you might need to provide a base URL in addition to an API token. If your identity service provider requests a base URL, then use https://shopifyscim.com/scim/v2/.

Okta

Complete SCIM configuration in Okta

1. Open the Shopify Plus app.
2. Click the Sign On tab.
3. Set the Application username format to Email.
4. Click Save.
5. Click the Provisioning tab.
6. Click Configure API Integration.
7. Select Enable API integration, and then paste the API token in the provided field.
8. Click Test API Credentials. If you encounter an error, then verify that you have correctly copied the API token. If you continue to encounter errors, then contact Shopify Plus Support.
9. Click Save.

OneLogin

Complete SCIM configuration in OneLogin

1. Open the Shopify Plus app.
2. Click the Configuration menu item.
3. In the SCIM Bearer Token field, paste the API token.
4. Click Save.
5. Click the Parameters menu item.
6. Set the SCIM Username default value to Email.
7. Click Save.

Entra

Complete SCIM configuration in Entra

1. Open the Shopify Plus app.
2. Click the Provisioning menu item.
3. Click Get Started.
4. In the Provisioning Mode menu, select Automatic.
5. In the Tenant URL field, enter the base url https://shopifyscim.com/scim/v2/.
6. In the Secret Token field, enter the API token.
7. Click the Test Connection button. If you encounter an error, then verify that you have correctly copied the API token. If you continue to encounter errors, then contact Shopify Plus Support.
8. Click Save.
9. Change the Provisioning Status switch to On.
10. Click Save.

Managing users with SCIM

After your API token has been added to your identity service provider, you can add or remove users through that service. Depending on the status of that user within Shopify and your identity service provider, this can change how they log in to Shopify.

Effects of creating a user in an identity provider

User status	Effect within Shopify
User already exists in your organization	If you add a user in your identity service provider, then the user is required to log in using SAML authentication if all the following are true: The user already exists in Shopify. The user already exists in your organization. You use Specific users enforcement. The effect of removing a user's access through your identity provider depends on their user status. If you remove an active user's access to Shopify using your identity service provider, then they're suspended in your organization. If you permanently delete a user using your identity service provider, then they might be deleted from your organization, depending on your identity provider setup.
User exists in Shopify, but not your organization	If you add a user in your identity service provider, then the user is added to your organization and required to log in using SAML authentication if all the following are true: The user already exists in Shopify. The user does not exist in your specific organization. You use Required or Specific users enforcement.
User does not exist in Shopify	If you add a user in your identity service provider, then the user is added to your organization and is required to log in using SAML authentication if all the following are true: The user doesn't already exist in Shopify. You use Required or Specific users enforcement. Users created through SCIM don't receive an invitation email. The user must log in through the identity service provider to activate their account.

After adding the API token, when you add a new user who didn't previously exist in Shopify either through your identity provider or Organization settings, your new user is set to Pending status. If your user is required to log in using SAML, then they remain in Pending status until they log in using your identity provider.

Group assignment in SCIM

After you complete SCIM configuration, you can optionally assign groups to SCIM users through your identity service provider. Before you assign a group to a user, verify that the group exists in your organization. If the group hasn't been created in your Shopify admin, then existing SCIM users aren't updated.

Assigning groups in supported identity service providers

Okta Group Push isn't supported with Shopify Plus. For more information, review the official Okta integration page.

Group assignment is supported in the Entra, OneLogin, and Okta apps. Group name creation and assignment differs for each identity provider.

Note

The group field might be labelled Role or Role name in the identity service provider, but this field accepts a group from your Shopify admin, not a role. The label will be updated to Group at a later time by the identity service provider.

Before you assign a group to a user, verify that the group exists in your Shopify admin.

Okta

Assign groups in Okta

1. Open the Shopify Plus app in Okta.
2. Click the Assignments tab.
3. Click Assign to add a user or edit an existing user's attributes.
4. In the modal that opens, add or update the Shopify group name in the Role Name (Optional) field.
5. Click Save.

Note

If the Role Name (Optional) field isn't displayed in Okta, then you need to reconfigure API integrations. Repeat the third step of completing SCIM configuration for Okta.

OneLogin

Assign groups in OneLogin

1. Open the Shopify Plus app in OneLogin.
2. In the navigation bar, click Users.
3. Click New User to add a user, or click a user to edit or add the group name.
4. Under User info in the side navigation bar, find the Custom Fields section.
5. Add the group name in the Role Name (Optional) field.
6. Click Save User.

Entra

Assign groups in Entra

1. Sign in to the Entra portal.
2. Create a role for your Shopify Plus app by following this guide provided by Microsoft. The role name must be the same as the group name in your Shopify admin.
3. Assign the role to users in your Shopify Plus app by following this guide provided by Microsoft.
4. To test that your group assignment works, provision the user on demand.

Note

If you've modified the default mapping in the Entra app, then you need to restore the mappings before you provision Shopify groups. For more information about mapping, refer to Microsoft's documentation.

Assigning groups in unsupported identity service providers

If your identity service provider doesn't have a Shopify Plus app, then you need to manually edit your SCIM configuration. Before you begin, verify that your identity service provider can add groups as a SCIM field.

The SCIM JSON body must include a key called roles. The roles key must be an array which includes a hash that stores the role name. If multiple role name hashes are provided, then only the last role name hash is used to assign a role. If the role name is invalid, or the SCIM JSON body doesn't match the above template, then groups aren't assigned or updated.

To assign or update a SCIM group, the JSON body in POST,PUT, and PATCH requests must include the following:

{
  "name": {
    "givenName": "given_name"
    "familyName": "family_name"
  },
  "userName": "email",
  "roles": [{"value": "role_name"}]
}

Unassigning groups

You can unassign a group from the Settings > Users page of your Shopify admin. Learn more about managing groups.

Remove SCIM integration

If you no longer require a SCIM integration, then you can remove it. This action can't be undone. If you need to reactivate your integration, then you need to generate a new API token.

Steps:

1. From your Shopify admin, go to Settings > Users.

2. Click Security.

3. In the SCIM integration section, click next to the API token.

4. Click Delete token.