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¶
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. |
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
orscope
. Include this value in theexternal_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 theUSE_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 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 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 tooauth
and thetoken
parameter to theexternal_oauth_access_token
.When passing the
token
value as a URL query parameter, it is necessary to URL-encode thetoken
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_name>",
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.