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 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
orpassword
.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 |
---|---|---|---|
|
|
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 |
|
|
string |
The username the user uses to login. |
|
|
string |
The first name of the user. |
|
|
string |
The last name of the user. |
|
|
string |
Only supports one email address. |
|
|
string |
The name the user interface displays for the user. |
|
N/A |
string |
The unique identifier set by the provisioning client (e.g., Azure, Okta). |
|
|
string |
The password for the user. This value is not returned in the JSON response. |
|
|
boolean |
Disables the user when set to false. |
|
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. |
|
|
string |
The time the user is added to Snowflake. |
|
|
string |
The time the user is last modified in Snowflake. |
|
N/A |
string |
Users should have a value of user. |
|
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 |
Get details for a specific user |
GET scim/v2/Users/{{user_id}} |
Returns details of a user account with the given |
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 |
Update user |
PUT scim/v2/Users/{id} |
Checks if a user with the given |
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
andloginName
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
andloginName
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
andloginName
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
andloginName
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 |
---|---|---|---|
|
|
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 |
|
|
String |
The name the user interface displays for the role. |
|
N/A |
String |
The userID value of the user who is a member of the role. |
|
N/A |
String |
An array of strings to indicate the namespace URIs. . For example, |
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 |
Get a group by its |
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., |
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: