SCIM user management for your organization
After you've verified your domain and set up SAML authentication for your organization, you can generate a SCIM API token.
On this page
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 user roles
- Deactivate users
Requirements
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.
Configure SCIM user management
- In your Shopify organization admin, go to Users > Security.
- In the SCIM integration section, click Generate API token.
- Click Copy to copy the generated token to your clipboard.
- Provide the token to your identity service provider. The procedure for adding the token depends on which identity service provider you use.
Complete SCIM configuration in Okta
- Open the Shopify Plus app.
- Click the Sign On tab.
- Set the Application username format to Email.
- Click Save.
- Click the Provisioning tab.
- Click Configure API Integration.
- Check Enable API integration, and then paste the API token in the provided field.
- Click Test API Credentials. If you encounter an error, then verify that you have correctly copied the API token from your Shopify Plus admin. If you continue to encounter errors, then contact Shopify Plus support.
- Click Save.
Complete SCIM configuration in OneLogin
- Open the Shopify Plus app.
- Click the Configuration menu item.
- In the SCIM Bearer Token field, paste the API token.
- Click Save.
- Click the Parameters menu item.
- Set the SCIM Username default value to Email.
- Click Save.
Complete SCIM configuration in Azure
- Open the Shopify Plus app.
- Click the Provisioning menu item.
- Click Get Started.
- In the Provisioning Mode menu, select Automatic.
- In the Tenant URL field, enter the base url
https://shopifyscim.com/scim/v2/
. - In the Secret Token field, enter the API token.
- Click the Test Connection button. If you encounter an error, then verify that you have correctly copied the API token from your Shopify Plus admin. If you continue to encounter errors, then contact Shopify Plus support.
- Click Save.
- Change the Provisioning Status switch to On.
- Click Save.
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.
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:
|
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:
|
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:
|
After adding the API token, when you add a new user who did not previously exist in Shopify either through your identity provider or the organization admin, 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.
Role assignment in SCIM
After you complete SCIM configuration, you can optionally assign roles to SCIM users through your identity service provider. Before you assign a role to a user, verify that the role exists in your organization. Existing SCIM users aren't updated if the role hasn't been created for your organization.
Assigning roles in supported identity service providers
Role assignment support has been added to the OneLogin and Okta apps. Support for the Azure app will be added later. To assign or update a SCIM user role in OneLogin or Okta, change the role name for an existing SCIM user in the identity service provider's provisioning portal.
Assigning roles 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 roles as a SCIM field.
To assign or update a SCIM user role, 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"}]
}
The SCIM JSON body must include a key called roles
. roles
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 roles are not assigned or updated.
Unassigning roles
To unassign a user role, use the Shopify organization admin. Learn more about unassigning user roles in Shopify.
Removing 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:
- In your Shopify organization admin, go to Users > Security.
- In the SCIM integration section, click ... beside the API token.
- Click Delete token.
Restrictions
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.