Configure Custom Clients for External OAuth¶

This topic describes how to configure Snowflake as an OAuth Resource and a Custom client as an External OAuth authorization server to facilitate secure, programmatic access to Snowflake data.

In this Topic:

Overview
External OAuth Token Payload Requirements
Configuration Procedure
Testing Procedure
Connecting to Snowflake with External OAuth

Overview¶

Snowflake supports a custom integration for identity providers (IdPs) that are not otherwise supported to verify users and generate OAuth access tokens to facilitate secure, programmatic access to Snowflake data.

External OAuth Token Payload Requirements¶

For External OAuth custom clients, the following table lists the required payload information the External OAuth access token must contain for Snowflake to process the access token. For more information about the Claims column, see JWT Claims.

Claims	Description
scp	Scopes. A list of scopes in the access token.
scope	Scopes. A comma-separated string of scopes in the access token. Snowflake supports specifying any single character for the delimiter, such as a space (i.e. `' '`), by setting the `EXTERNAL_OAUTH_SCOPE_DELIMITER` property when creating or modifying the External OAuth security integration for custom clients. Contact Snowflake Support to enable this property in your Snowflake account.
aud	Audience. Identifies the recipients that the access token is intended for as a string URI.
exp	Expiration time. Identifies the expiration time on or after which the access token must not be accepted for processing.
iss	Issuer. Identifies the principal that issued the access token as a string URI.
iat	Issued at. Required. Identifies the time at which the JWT was issued.

Note

Snowflake supports the nbf (not before) claim, which identifies the time before which the access token must not be accepted for processing.

If your authorization server supports the nbf (not before) claim, you can optionally include the nbf claim in the access token.

To verify your token contains the required information, you can test the token on this JSON Web Tokens site.

As a representative example, the PAYLOAD: DATA interface displays the token payload as follows.

{
  "aud": "<audience_url>",
  "iat": 1576705500,
  "exp": 1576709100,
  "iss": "<issuer_url>",
  "scp": [
    "session:role:analyst"
  ]
}

Configuration Procedure¶

The following steps assume that your IdP and environment can be configured to obtain the necessary values to create the Snowflake Security Integration.

Important

The steps in this topic are a representative example on how to configure custom clients for External OAuth.

You can configure your environment to any desired state and use any desired OAuth flow provided that you can obtain the necessary information for the security integration (in this topic).

Note that the following steps serve as a guide to obtain the necessary information to create the security integration in Snowflake.

Be sure to consult your internal security policies with regard to configuring an authorization server to ensure your organization meets all necessary regulations and compliance requirements.

Step 1: Obtain Key Environment Values to Use External OAuth¶

Configure your IdP and authorization server. It is necessary to identify the following values to include in the Snowflake Security Integration in the next step.

Issuer URL: Include this URL with the external_oauth_issuer parameter.
RSA Public Key: Include this value with the external_oauth_rsa_public_key_value.
Audience URLs: If more than one Audience URL is necessary, separate each URL with a comma in the external_oauth_audience_list parameter.
Scope attribute: This value is configurable to use either scp or scope. Include this value in the external_oauth_scope_mapping_attribute. For more information, see External OAuth Token Payload Requirements.
User Attribute: This attribute refers to attribute to identify users in your IdP. Include this attribute value in the external_oauth_user_mapping_claim.
Snowflake User Attribute: The attribute in Snowflake to identify users. Include this value in the external_oauth_snowflake_user_mapping_attribute.

Step 2: Create an OAuth Authorization Server in Snowflake¶

This step creates a security integration in Snowflake. The security integration ensures that Snowflake can communicate securely with and validate tokens from your IdP, and provide the appropriate Snowflake data access to users based on the user role associated with the OAuth token. For more information, see CREATE SECURITY INTEGRATION.

Important

Only account administrators or a role with the global CREATE INTEGRATION privilege can execute this SQL command.

The security integration parameter values are case-sensitive and the values you put into the security integration must match those values in your environment. If the case does not match, it is possible that the access token will not be validated resulting in a failed authentication attempt.

Create an OAuth Authorization Server in Snowflake

create security integration external_oauth_custom
    type = external_oauth
    enabled = true
    external_oauth_type = custom
    external_oauth_issuer = '<authorization_server_url>'
    external_oauth_rsa_public_key = '<public_key_value>'
    external_oauth_audience_list=('<audience_url_1>', '<audience_url_2>')
    external_oauth_scope_mapping_attribute = 'scp'
    external_oauth_token_user_mapping_claim='upn'
    external_oauth_snowflake_user_mapping_attribute='login_name';

Modifying Your External OAuth Security Integration¶

You can update your External OAuth security integration by executing an ALTER statement on the security integration.

For more information, see ALTER SECURITY INTEGRATION.

Using ANY Role with External OAuth¶

In the configuration step to create a security integration in Snowflake, the OAuth access token includes the scope definition. Therefore, at runtime, using the External OAuth security integration allows neither the OAuth client nor the user to use an undefined role in the OAuth access token.

After validating the access token and creating a session, the ANY role can allow the OAuth client and user to decide its role. If necessary, the client or the user can switch to a role that is different that the role defined in the OAuth access token.

To configure ANY role, define the scope as SESSION:ROLE-ANY and configure the security integration with the external_oauth_any_role_mode parameter. This parameter can have three possible string values:

DISABLE does not allow the OAuth client or user to switch roles (i.e. use role <role>;). Default.
ENABLE allows the OAuth client or user to switch roles.
ENABLE_FOR_PRIVILEGE allows the OAuth client or user to switch roles only for a client or user with the USE_ANY_ROLE privilege. This privilege can be granted and revoked to one or more roles available to the user. For example:
```
grant USE_ANY_ROLE on integration external_oauth_1 to role1;
```
```
revoke USE_ANY_ROLE on integration external_oauth_1 from role1;
```

Define the security integration as follows:

create security integration external_oauth_1
    type = external_oauth
    enabled = true
    external_oauth_any_role_mode = 'ENABLE'
    ...

Using Secondary Roles with External OAuth¶

The desired scope for the primary role is passed in the external token: either the default role for the user (session:role-any) or a specific role that was granted to the user (session:role:<role_name>).

By default, Snowflake does not activate the default secondary roles for a user (i.e. the DEFAULT_SECONDARY_ROLES) user in the session.

To activate the default secondary roles for a user in a session and allow executing the USE SECONDARY ROLES command while using External OAuth, complete the following steps:

Configure the security integration for the connection. Set the EXTERNAL_OAUTH_ANY_ROLE_MODE parameter value to either ENABLE or ENABLE_FOR_PRIVILEGE when you create the security integration (using CREATE SECURITY INTEGRATION) or later (using ALTER SECURITY INTEGRATION).
Configure the authorization server to pass the static value of session:role-any in the scope attribute of the token. For more information about the scope parameter, see External OAuth Overview.

Using Client Redirect with External OAuth¶

Snowflake supports using Client Redirect with External OAuth, including using Client Redirect and OAuth with supported Snowflake Clients.

For more information, see Redirecting Client Connections.

Using Network Policies with External OAuth¶

Currently, network policies cannot be added to your External OAuth security integration.

If your use case requires OAuth and a Snowflake network policy, use Snowflake OAuth.

For more information, see OAuth and Network Policies.

Testing Procedure¶

In the context of testing OAuth while using Custom clients as an authorization server, you must:

Verify that the test user exists in your IdP and has a password.
Verify that the test user exists in Snowflake with their login_name attribute value set to the <external_oauth_token_user_mapping_claim>.
Register an OAuth Client
Allow the OAuth Client to make a POST request to the Custom Token endpoint as follows:
- Grant type set to Resource Owner
- HTTP Basic Authorization header containing the clientID and secret
- FORM data containing the user’s username & password
- Include scopes

The sample command requests the ANALYST custom role and that assumes the session:role:analyst has been defined in your OAuth authorization server.

Here is an example for getting an access token using cURL.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --user <OAUTH_CLIENT_ID>:<OAUTH_CLIENT_SECRET> \
  --data-urlencode "username=<IdP_USER_USERNAME>" \
  --data-urlencode "password=<IdP_USER_PASSWORD>" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=session:role:analyst" \
  <IdP_TOKEN_ENDPOINT>

Connecting to Snowflake with External OAuth¶

After configuring your security integration and obtaining your access token, you can connect to Snowflake using one of the following:

Note the following:

It is necessary to set the authenticator parameter to oauth and the token parameter to the external_oauth_access_token.
When passing the token value as a URL query parameter, it is necessary to URL-encode the token value.
When passing the token value to a Properties object (e.g. JDBC Driver), no modifications are necessary.

For example, if using the Python Connector, set the connection string as shown below.

ctx = snowflake.connector.connect(
   user="<username>",
   host="<hostname>",
   account="<account_identifier>",
   authenticator="oauth",
   token="<external_oauth_access_token>",
   warehouse="test_warehouse",
   database="test_db",
   schema="test_schema"
)

You can now use External OAuth to connect to Snowflake securely.