Provision organization users and organization user groups with SCIM (Preview)

A SCIM security integration in the organization account with a SCOPE of ORGANIZATION provisions organization users and organization user groups. For more information about these objects, see Organization users and Organization user groups. Run the following statements in the organization account.

For more information about setting up the identity provider, see Okta, Microsoft Entra ID, or a custom integration.

Create a role for the integration

The SCIM request runs as RUN_AS_ROLE. That role needs:

  • CREATE ORGANIZATION USER to create a user.
  • MANAGE ORGANIZATION USERS to read, update, delete, and list users.
  • CREATE ORGANIZATION USER GROUP to create a group.
  • MANAGE ORGANIZATION USER GROUPS to read, update, delete, and list groups.

The following example creates a role with these privileges:

USE ROLE GLOBALORGADMIN;
CREATE ROLE IF NOT EXISTS org_scim_provisioner;
GRANT CREATE ORGANIZATION USER ON ACCOUNT TO ROLE org_scim_provisioner;
GRANT MANAGE ORGANIZATION USERS ON ACCOUNT TO ROLE org_scim_provisioner;
GRANT CREATE ORGANIZATION USER GROUP ON ACCOUNT TO ROLE org_scim_provisioner;
GRANT MANAGE ORGANIZATION USER GROUPS ON ACCOUNT TO ROLE org_scim_provisioner;
GRANT ROLE org_scim_provisioner TO ROLE GLOBALORGADMIN;

If a role other than GLOBALORGADMIN creates the integration, grant org_scim_provisioner to that role.

Note

Unlike account-scoped SCIM, organization-scoped SCIM doesn’t require RUN_AS_ROLE to own the users and groups that it manages. With MANAGE ORGANIZATION USERS or MANAGE ORGANIZATION USER GROUPS, RUN_AS_ROLE can read, update, and delete an organization user or organization user group that any role created.

Create the security integration

To create an organization-scoped SCIM integration, set SCOPE to ORGANIZATION. SCOPE = ORGANIZATION is valid only in the organization account. SCOPE is set when you create the integration and can’t be changed. SYNC_PASSWORD isn’t supported on an organization-scoped integration. A create or alter statement that sets SYNC_PASSWORD = TRUE fails.

Okta:

CREATE OR REPLACE SECURITY INTEGRATION okta_provisioning
    TYPE = SCIM
    SCIM_CLIENT = 'OKTA'
    RUN_AS_ROLE = 'ORG_SCIM_PROVISIONER'
    SCOPE = ORGANIZATION;

Microsoft Entra ID:

CREATE OR REPLACE SECURITY INTEGRATION aad_provisioning
    TYPE = SCIM
    SCIM_CLIENT = 'AZURE'
    RUN_AS_ROLE = 'ORG_SCIM_PROVISIONER'
    SCOPE = ORGANIZATION;

Custom identity provider:

CREATE OR REPLACE SECURITY INTEGRATION generic_scim_provisioning
    TYPE = SCIM
    SCIM_CLIENT = 'GENERIC'
    RUN_AS_ROLE = 'ORG_SCIM_PROVISIONER'
    SCOPE = ORGANIZATION;

Authenticate requests

Send requests to the organization account. The base URL uses the organization account identifier. For more information, see Authenticating SCIM API requests.

Programmatic access tokens or External OAuth

Requests that use a programmatic access token or External OAuth authenticate as a service user. Create that user in the organization account, create a role for the user, and grant the role USAGE on the integration. In the following example, that role is scim_role.

RUN_AS_ROLE is a different role from the service user’s role. The RUN_AS_ROLE, such as org_scim_provisioner, needs the privileges in Create a role for the integration. The user’s role, scim_role, doesn’t need those privileges and only needs USAGE so the service user can call the integration.

The following example creates the service user and its role, and grants the role USAGE on the integration:

CREATE USER scim_idp_user
  TYPE = SERVICE;

CREATE ROLE scim_role;
GRANT ROLE scim_role TO USER scim_idp_user;
ALTER USER scim_idp_user SET DEFAULT_ROLE = scim_role;

GRANT USAGE ON INTEGRATION <integration_name> TO ROLE scim_role;

<integration_name> is the name of the integration you created, such as okta_provisioning.

To create the token, see Set up programmatic access tokens or Set up External OAuth.

Send programmatic access token and External OAuth requests to:

https://<organization_account_identifier>.snowflakecomputing.com/scim/v2/

If the organization account has more than one enabled SCIM security integration, add the integration UUID to the URL:

https://<organization_account_identifier>.snowflakecomputing.com/scim/v2/<integration_uuid>/

If you need the integration UUID, run DESC SECURITY INTEGRATION and copy SCIM_ENDPOINT_ID:

DESC SECURITY INTEGRATION <integration_name>;

SCIM access token

A SCIM access token doesn’t use a service user, and the caller doesn’t need USAGE on the integration. Generate the token for the organization-scoped integration you created:

SELECT SYSTEM$GENERATE_SCIM_ACCESS_TOKEN('<integration_name>');

For more information, see SYSTEM$GENERATE_SCIM_ACCESS_TOKEN and Authenticating SCIM requests with a SCIM access token.

Send SCIM access token requests to:

https://<organization_account_identifier>.snowflakecomputing.com/scim/v2/

With a SCIM access token, don’t add the integration UUID to the URL, even if the organization account has more than one SCIM integration.

Make provisioned groups available to regular accounts

SCIM doesn’t set VISIBILITY or IS_GRANTABLE on an organization user group. A request doesn’t change those properties.

Set visibility in the organization account

After SCIM creates an organization user group, set the group’s VISIBILITY in the organization account to specify which regular accounts can view and import the group.

Allow one account to import the group:

ALTER ORGANIZATION USER GROUP data_engineers_group
  SET VISIBILITY = ACCOUNTS qa_env;

Allow every regular account to import the group:

ALTER ORGANIZATION USER GROUP data_engineers_group
  SET VISIBILITY = ALL;

IS_GRANTABLE controls whether the role created from the group can be granted to another role in the regular account. Set it in the organization account:

ALTER ORGANIZATION USER GROUP data_engineers_group
  SET IS_GRANTABLE = TRUE;

For more information, see Make organization user groups available to regular accounts and ALTER ORGANIZATION USER GROUP.

Import the group in a regular account

In the regular account, an administrator can import the organization user group. By default, ACCOUNTADMIN can run this statement. To allow another role to import, grant that role IMPORT ORGANIZATION USER GROUPS.

The following statement imports the group:

ALTER ACCOUNT ADD ORGANIZATION USER GROUP data_engineers_group;

Import adds the group’s users to that account and creates a role with the group’s name. If the group’s name matches an existing role, or an organization user matches an existing user, that object isn’t imported. Resolve the conflict after the import. See Resolve conflicts after importing users.

For more information, see Import users in a regular account.

Manage an organization user in one place

After organization-scoped SCIM creates or updates an organization user or organization user group, Snowflake marks that object as being managed by organization SCIM. When a regular account imports the organization user group, account-scoped SCIM in that account can’t read or change the imported users and roles that are marked as managed by organization SCIM:

  • Requests that read or modify an imported user or role fail.
  • List requests don’t return those imported users and roles.
  • Requests that add an imported user or role to a group fail.

A DELETE for an organization user drops that user in the organization, which drops the corresponding user in every regular account that imported the user. See Removing users from all regular accounts.

Organization users and organization user groups that you create and manage only with SQL aren’t affected.

For attributes and the privilege each endpoint checks, see Organization SCIM API differences (Preview).