Managing Users & Groups with SCIM

.

Related Topics

• Overview of Access Control

This topic describes:

1. SCIM integrations with Snowflake.

2. SCIM use cases with Snowflake.

3. Using the Snowflake SCIM APIs to make requests to an identity provider.

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:

1. User Lifecycle Management

2. 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.

1. Creating and activating a user.

2. Updating user attributes, such as email or password.

3. 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. . urn:ietf:params:scim:schemas:core:2.0:User . urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

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.

• Currently, setting the "defaultWarehouse" and "defaultRole" fields is only possible with Okta; Azure AD does not support this configuration.

  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": {
        "defaultWarehouse" : "test_warehouse",
        "defaultRole" : "test_role"
    }
}

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.

1. Okta

2. Microsoft Azure Active Directory

3. 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:

• Okta SCIM Integration with Snowflake
• Azure SCIM Integration with Snowflake
• Custom SCIM Integration with Snowflake
• Making a SCIM API Request