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 Check the IdP logs to ensure the values match. |
|
|
string |
The identifier to login into Snowflake. For details about these Snowflake attributes, see CREATE USER. |
|
|
string |
The first name of the user. |
|
|
string |
The last name of the user. |
|
|
string |
The user email address. The value supports a single 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. Note: If the SCIM security integration |
|
|
boolean |
Disables the user when set to |
|
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. Supported values include:
|
Custom Attributes¶
Snowflake supports setting custom attributes that are not defined by RFC 7643, such as
defaultRole
, defaultWarehouse
, and defaultSecondaryRoles
.
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 a user exists. |
|
Returns details of a user account with the given |
Get details for a specific user. |
|
Returns details of a user account with the given |
Get details for a specific user. |
|
Returns a sample user to allow the SCIM client to read the schema and with an HTTP status code of |
Create a user. |
|
Creates a user in Snowflake and returns an HTTP If the user already exists or another conflict arises, Snowflake returns an HTTP |
Update user with partial attributes. |
|
Deactivates the corresponding user if the To activate a currently deactivated user, set PATCH requires an Operations key (i.e. Returns an HTTP status code of |
Update a user. |
|
Checks if a user with the given Otherwise, it will replace the read-write or write-only attributes based on the request. Returns an HTTP status code of |
Delete a user. |
|
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, 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
defaultSecondaryRoles
is "ALL"
.
Note
Although Snowflake supports it, exercise caution in using the PUT operation because 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 might change. For example, a user might change from an individual contributor to a manager with direct reports. Upon their role changing, their access in Snowflake might 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 by calling the Information Schema table function REST_EVENT_HISTORY. Check the IdP logs to ensure the values match. |
|
|
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. |
|
Returns the details of group with the given |
Get a group by its |
|
Returns details of the group with the given |
Get a sample group. |
|
Returns a sample group to allow the SCIM client to read the schema and with an HTTP status code of |
Create a new group. |
|
Creates a new group with an HTTP status code of |
Update a group. |
|
Updates the group display name attribute or group membership. PATCH requires an operations (i.e. Returns an HTTP status code of |
Delete a group. |
|
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 that calls the Information Schema table function REST_EVENT_HISTORY 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',
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.
Using Replication with SCIM¶
Snowflake supports replication and failover/failback with the SCIM security integration from the source account to the target account.
For details, see Replication of Security Integrations & Network Policies Across Multiple Accounts.
Next Topics: