Managing Users & Groups with SCIM¶

This topic describes:

SCIM integrations with Snowflake.
SCIM use cases with Snowflake.
Using the Snowflake SCIM APIs to make requests to an identity provider.

SCIM Overview
SCIM Use Cases
Supported SCIM Integrations

SCIM Overview¶

SCIM is an open specification to help facilitate the automated management of user identities and groups (i.e. roles) in cloud applications using RESTful APIs.

These APIs use common methods (e.g. GET, POST) with key-value pair attributes in JSON format. The set of user attributes are unique to the user. Similarly, the set of group attributes are unique to the group

Currently, Snowflake supports SCIM 2.0 to integrate Snowflake with Okta and Microsoft Azure AD, which both function as identity providers. Snowflake also supports identity providers that are neither Okta nor Microsoft Azure (i.e. Custom). Users and groups from the identity provider can be provisioned into Snowflake, which functions as the service provider.

Important

The specific SCIM role in Snowflake must own any users and roles that are imported from the identity provider. If the Snowflake SCIM role does not own the imported users or roles, updates in the identity provider will not be synced to Snowflake. The Snowflake SCIM role is specific to the identity provider (IdP) and is as follows:

Okta SCIM Role: okta_provisioner
Azure AD SCIM Role: aad_provisioner
Custom SCIM Role: generic_scim_provisioner

For more information on how to use the Snowflake SCIM Role, see the SCIM configuration sections for Okta, Azure AD, and the Custom SCIM integration.

The identity provider uses a SCIM client to make the RESTful API request to the Snowflake SCIM server. Upon validating the API request, Snowflake performs actions on the user or group.

The authentication process uses an OAuth Bearer token and this token is valid for six months. Customers must keep track of their authentication token and can generate a new token on demand. During each API request, the token is passed into the header as an authorization Bearer parameter.

After the initial Snowflake SCIM configuration, you can use the Snowflake SCIM API to address the following use cases:

User Lifecycle Management
Map Active Directory Groups to Snowflake Roles

Caution

Currently, the Snowflake SCIM API allows administrators to manage users and groups from the Customer’s identity provider to Snowflake.

Therefore, if using the Snowflake SCIM API for user and group identity and access management administration, do not make user and group changes in Snowflake (because those changes will not synchronize back to the Customer identity provider).

SCIM Use Cases¶

The Snowflake SCIM API can address the following use cases.

Manage Users

Administrators can provision and manage their users from their organization’s identity provider to Snowflake. User management is a one-to-one mapping from the identity provider to Snowflake.

Manage Roles

Administrators can provision and manage their groups (i.e., Roles) from their organization’s identity provider to Snowflake. Role management is a one-to-one mapping from the identity provider to Snowflake.

Auditing

Administrators can query the rest_event_history table to determine whether the identity provider is sending updates (i.e. SCIM API requests) to Snowflake.

Managing Users with SCIM¶

Snowflake supports user lifecycle management with SCIM APIs. User lifecycle management is an administrative activity that coincides with the pathway the user takes throughout the organization. Common events in the user’s lifecycle include these activities.

Creating and activating a user.
Updating user attributes, such as email or password.
Deactivating a user upon termination.

In Snowflake, user lifecycle automation using SCIM requires passing user attributes in the body of the API request. A successful API request from the identity provider affects the user in Snowflake almost immediately.

User Attributes¶

User attributes are the key-value pairs that are associated with the user. These pairs are the information about the user, such as their display name and their email address. Identity providers sometimes define attribute keys differently, such as surname, familyName, or lastName, all of which indicate the user’s last name. Snowflake does not support multi-valued user attributes.

The Snowflake SCIM API passes user attributes in JSON format, which are shown in the corresponding User API examples.

Snowflake supports the following SCIM attributes for user lifecycle management. Attributes are writable unless otherwise noted.

Important

In the table, the Snowflake userName and loginName attributes are both mapped to the SCIM attribute userName. Snowflake supports different values for the Snowflake attribute of userName and loginName. This attribute value separation allows customers to have more granular control over which attribute value can be used to access Snowflake.

For more information, see the User API examples for POST and PATCH.

SCIM User Attribute	Snowflake User Attribute	Type	Description
`id`	`id`	string	The immutable, unique identifier (i.e., GUID) of the user in Snowflake. . Snowflake does not expose this value in the DESCRIBE USER or SHOW USERS output. . For certain request paths that contain this attribute (e.g. PATCH), the `id` can be found in the Snowflake table `rest_event_history`. . Check the IdP logs to ensure the values match.
`userName`	`userName`, `loginName`	string	The username the user uses to login.
`name.givenName`	`firstName`	string	The first name of the user.
`name.familyName`	`familyName`	string	The last name of the user.
`emails`	`email`	string	Only supports one email address.
`displayName`	`displayName`	string	The name the user interface displays for the user.
`externalID`	N/A	string	The unique identifier set by the provisioning client (e.g., Azure, Okta).
`password`	`password`	string	The password for the user. This value is not returned in the JSON response.
`active`	`disabled`	boolean	Disables the user when set to `false`.
`groups`	N/A	string	A list of groups to which the user belongs. The group displayName is required. The user’s groups are read-only and their membership must be updated with the SCIM Groups API.
`meta.created`	`createdON`	string	The time the user is added to Snowflake.
`meta.lastModified`	`lastModified`	string	The time the user is last modified in Snowflake.
`meta.resourceType`	N/A	string	Users should have a value of user.
`schemas`	N/A	string	A comma-separated array of strings to indicate the namespace URIs. Supported values include: . `urn:ietf:params:scim:schemas:core:2.0:User` . `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` . `urn:ietf:params:scim:schemas:extension:2.0:User`

Custom Attributes¶

Snowflake supports setting custom attributes that are not defined by RFC 7643, such as defaultRole, defaultWarehouse, and defaultSecondaryRole.

Currently, Snowflake supports using two namespaces to set custom attributes for the following POST, PUT, and PATCH API requests:

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

This namespace was part of the original SCIM implementation in Snowflake and can be used to set custom attributes for Okta SCIM integrations only.

This namespace is not supported to set custom attributes for Microsoft Azure SCIM integrations or custom SCIM integrations.

urn:ietf:params:scim:schemas:extension:2.0:User

This newer namespace can be used to set custom attributes for all SCIM integrations and must be used for custom attributes with either a custom SCIM integration or a Microsoft Azure SCIM integration.

User APIs¶

Snowflake supports the following APIs to facilitate user lifecycle management. You can obtain user information with filters and also create, update, deactivate, and delete users.

Purpose	Method & API	Notes
Check if user exists	GET scim/v2/Users?filter=userName eq “{{user_name}}”	Returns details of a user account with the given `userName` and with a 200 status code if successful.
Get details for a specific user	GET scim/v2/Users/{{user_id}}	Returns details of a user account with the given `user_id` and with a 200 status code if successful.
Get details for a specific user	GET scim/v2/Users?startIndex=0&count=1	Returns a sample user to allow the SCIM client to read the schema and with a 200 status code if successful.
Create user	POST scim/v2/Users	Creates a user in Snowflake and returns a 201 status code if successful. . If the user already exists or another conflict arises, Snowflake returns a 409 status code.
Update user with partial attributes	PATCH scim/v2/Users/{id}	Deactivates the corresponding user if the `active` key is set to false. To activate a currently deactivated user, set `active` to true. . PATCH requires an Operations key (i.e., `op`) with an array stating to replace an attribute value. . Returns a status code of 200 if successful or 204 (i.e., no content) if not successful.
Update user	PUT scim/v2/Users/{id}	Checks if a user with the given `id` exists. This operation fails if immutable attributes are requested to change. . Otherwise, it will replace the read-write or write-only attributes based on the request. . Returns a 400 status code if the immutable attribute values in the request body do not match the values in Snowflake.
Delete user	DELETE scim/v2/Users/{id}

For more information on SCIM API requests, see Making a SCIM API Request.

POST scim/v2/Users¶

Create a user with userName and loginName mapped to the same value.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:2.0:User"
        ],
    "userName": "test_user_1",
    "password": "test",
    "name": {
        "givenName": "test",
        "familyName": "user"
        },
    "emails": [{
        "value": "test.user@snowflake.com"
        }
    ],
    "displayName": "test user",
    "active": true
}

Create a user with userName and loginName mapped to different values.

If Okta is your identity provider, follow this procedure.

{
    "active": true,
    "displayName": "test user",
    "emails": [
        {
            "value": "test.user@snowflake.com"
        }
    ],
    "name": {
        "familyName": "test_last_name",
        "givenName": "test_first_name"
    },
    "password": "test_password",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "snowflakeUserName": "USER5"
    },
    "userName": "USER5"
}

PATCH scim/v2/Users/{id}¶

Update a user with userName and loginName mapped to the same value.

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "replace",
        "value": {
            "active": false
        }
    }]
}

Update a user with userName and loginName mapped to different values.

If Okta is your identity provider, follow this procedure.

{
    "Operations": [
        {
            "op": "Replace",
            "path": "userName",
            "value": "test_updated_name"
        },
        {
            "op": "Replace",
            "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.snowflakeUserName",
            "value": "USER5"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}

PUT scim/v2/Users/{id}¶

Update a user, including setting the "defaultRole", "defaultSecondaryRoles", and "defaultWarehouse" fields.

To specify the "defaultRole", "defaultSecondaryRoles", and "defaultWarehouse" properties, Snowflake requires using one of the extension schemas. Note that the only possible value for defaultSecondaryRole is "ALL".

Note

Although Snowflake supports it, exercise caution in using the PUT operation since it is more expensive than a PATCH operation. Use the PATCH operation instead.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
        ],
    "userName": "test_user_1",
    "password": "test",
    "name": {
        "givenName": "test",
        "familyName": "user"
        },
    "emails": [{
        "primary": true,
        "value": "test.user@snowflake.com",
        "type": "work"
        }
    ],
    "displayName": "test user",
    "active": true,
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "defaultRole" : "test_role",
        "defaultSecondaryRoles" : "ALL",
        "defaultWarehouse" : "test_warehouse"
    }
}

Managing Roles with SCIM¶

Snowflake supports using SCIM to import roles from Okta, Azure AD and custom-built applications. There is a direct, one-to-one mapping with these roles to Snowflake roles.

Roles, which are usually synonymous with groups, are a logical collection of access privileges. In the Snowflake model, access to securable objects is allowed through privileges assigned to roles, which are in turn assigned to other roles or users.

Access permissions and rights that are granted to the role are automatically inherited by every member (e.g., user) of the role. For more information, see Overview of Access Control.

As users proceed through their career path in their organization, their access requirements to Snowflake may change. For example, a user may change from an individual contributor to a manager with direct reports. Upon their role changing, their access in Snowflake may also need to allow for data sets only available to managers.

As the user’s role membership changes in their organization, the access to Snowflake can automatically change once their organization roles are mapped to the corresponding Snowflake role.

Role Attributes¶

The Snowflake SCIM API passes role attributes in JSON format, which are shown in the corresponding API examples.

Snowflake supports the following SCIM attributes for role lifecycle management. Attributes are writable unless otherwise noted.

SCIM Group Attribute	Snowflake Group Attribute	Type	Description
`id`	`id`	String	The immutable, unique identifier (i.e. GUID) of the role in Snowflake. . Snowflake does not expose this value. It can be found in the Snowflake table `rest_event_history`. . Check the IdP logs to ensure the values match.
`displayName`	`name`	String	The name the user interface displays for the role.
`members.value`	N/A	String	The userID value of the user who is a member of the role.
`schemas`	N/A	String	An array of strings to indicate the namespace URIs. . For example, `urn:ietf:params:scim:schemas:core:2.0:Group`.

Role APIs¶

You can obtain role information with filters and also create a role, update the role membership, and delete a role. Snowflake supports the following APIs to facilitate role management.

Purpose	Method & API	Notes
Get a group by display name	GET scim/v2/Groups?filter=displayName=”scim_test_group”	Returns details of group with the given `displayName` and with a 200 status code if successful.
Get a group by its `groupId`.	GET scim/v2/Groups/{group_id}	Returns details of the group with the given groupId and a 200 status code if successful.
Get a sample group	GET scim/v2/Groups?startIndex=0&count=1	Returns a sample group to allow the SCIM client to read the schema and with a 200 status code if successful.
Create a new group	POST scim/v2/Groups	Creates a new group with a 201 status code if successful.
Update a group	PATCH scim/v2/Groups/{id}	Updates the group display name attribute or group membership. . PATCH requires an operations (i.e., `op`) key with an array stating whether to add or replace. . Returns a status code of 200 if successful or 204 (i.e., no content) if not successful.
Delete a group	DELETE scim/v2/Groups/{id})

For more information on SCIM API requests, see Making a SCIM API Request.

POST scim/v2/Groups¶

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName":"scim_test_group2"
}

PATCH scim/v2/Groups/{id})¶

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "replace",
        "value": {
            "displayName": "updated_name"
            }
        },
        {
            "op" : "remove",
            "path": "members[value eq \"user_id_1\"]"
        },
        {
          "op": "add",
          "value": [{
            "value": "user_id_2"
            }]
        }
    ]
}

Auditing with SCIM¶

It is possible to query Snowflake to determine which SCIM API requests were made over a given time interval.

For example, this information can help to determine whether the organization’s active user population which should be provisioned into Snowflake matches the users provisioned into Snowflake.

The SQL below is a representative example to query the rest_event_history table to determine which SCIM REST API requests were made in the last five minutes, up to 200 requests.

use role accountadmin;
use database demo_db;
use schema information_schema;
select * from table(rest_event_history('scim'));
select *
    from table(rest_event_history(
        'scim',
        dateadd('minutes',-5,current_timestamp()),
        current_timestamp(),
        200))
    order by event_timestamp;

For more information on how to modify this query, see the DATEADD and CURRENT_TIMESTAMP functions.

Supported SCIM Integrations¶

Snowflake can integrate with the following identity providers to provision, manage, and synchronize users and groups to Snowflake.

Okta
Microsoft Azure Active Directory
Custom

Note

Custom SCIM integrations allow identity providers that do not have a dedicated integration to provision, manage, and synchronize users and groups in Snowflake.

Currently, the Custom SCIM integration should be used for identity providers that are neither Okta nor Microsoft Azure AD.

Customers using Okta as their identity provider should follow the instructions in the Okta SCIM Integration with Snowflake.

Customers using Microsoft Azure Active Directory as their identity provider should follow the instructions in the Azure SCIM Integration with Snowflake.

Customers who are not using Okta or Microsoft Azure Active Directory as their identity provider should create their own SCIM client and then follow the instructions in the Custom SCIM Integration with Snowflake.

Next Topics: