Managing Users & Groups with SCIM

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}

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})

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.