Set up OAuth for Snowflake

Use this topic to enable users to create OAuth-backed Snowflake Data Sources, and authenticate and query Snowflake with a JWT token. After this is set up, users can select OAuth when they create a Snowflake Data Source.

When an OAuth-configured Snowflake is queried in a Domino execution, the dominodatalab-data library uses the Domino JWT token to authenticate against the underlying Snowflake database. If this is set up properly, no extra user action is needed.

To set up Snowflake OAuth, you must:

Set up an External OAuth Security Integration in your Snowflake account to configure Snowflake. This dictates what values your Snowflake account will expect to be propagated inside the token for successful authentication.
Set up Keycloak to ensure correct propagation of the necessary values in the Domino JWT access token.

Note	OAuth is not supported for service accounts. OAuth-authenticated connections can be used for any execution type except Domino endpoints.

Note

Because authentication depends on the Domino JWT token propagating the correct set-up values in the context of an execution, you cannot verify successful authentication when you create a Data Source. Therefore, the green checkmark that shows when you create a Data Source does not guarantee that authentication will succeed. To confirm successful value propagation in a Domino JWT token, use the dominodatalab-data library to query data from an OAuth Data Source in a Domino execution, such as a Workspace.

1. Configure Snowflake

To set up an External OAuth Security Integration in Snowflake, see the Snowflake documentation. Get familiar with the Snowflake terminology and the values that Snowflake needs in the token; correct spelling of the values is critical.

The following is a sample command to create a base security integration that allows all account roles to successfully authenticate. You can use this as a starting point to build an authentication configuration that fits your security needs.

create security integration <external_oauth_name>
    type = external_oauth
    enabled = true
    external_oauth_type = custom
    external_oauth_issuer = 'https://<domino-domain>/auth/realms/DominoRealm'
    external_oauth_rsa_public_key = <keycloak-realm-settings-public-key>
    external_oauth_audience_list=('account')
    external_oauth_scope_mapping_attribute = 'scp'
    external_oauth_token_user_mapping_claim='preferred_username_snowflake'
    external_oauth_snowflake_user_mapping_attribute='login_name';

alter security integration <external_oauth_name> set EXTERNAL_OAUTH_ANY_ROLE_MODE = ENABLE;

Find the value for these keys:

external_oauth_issuer in Keycloak’s Realm Settings > OpenID Endpoint Configuration > Issuer
external_oauth_rsa_public_key in Keycloak’s Realm Settings > Keys > Public Key from RS256

The configured security integration (desc security integration <external_oauth_name>) should look similar to the following:

Snowflake Security Integration

2. Set up Keycloak integration

The following steps describe how to instruct Keycloak to pass the values that Snowflake’s custom security integration expects in the Domino JWT access token. To do this, create mappers in the domino-play client and specify the option to add to access token in each mapper. This creates a key-value entry in the Domino JWT token with key being what is specified under Token Claim Name.

The value depends on what type of mapper is created. For example, a hardcoded-claim mapper requests a value, which ultimately propagates equally to all users. By contrast, a user-attribute mapper requests a User Attribute name, then looks into each Keycloak user attribute for that attribute name and propagates its value. This lets you customize how the Domino JWT token is augmented by each user.

The following is a base solution that matches the base Snowflake custom security integration described previously. This solution is a starting point to build upon for a customized authentication configuration that fits your security needs.

Set up the Keycloak integration:

Go to the keycloak admin console at https://<domino-domain>/auth/.
Click Clients.
Click the domino-play client ID.
Click Mappers.

Add the following mappers. The mappers are simple examples. You can write your mappers differently, as long as they conform to the Snowflake Security Integration’s requirements.

Issuer

Issuer
Token Claim Name	`external_oauth_issuer`
Claim JSON Type	`String`
Add to access token	`ON`
Claim value	The name of your OpenID Endpoint Configuration issuer. You can find the value in Realm Settings > OpenID Endpoint Configuration > Issuer.

Token Claim Name

external_oauth_issuer

Claim JSON Type

String

Add to access token

ON

Claim value

The name of your OpenID Endpoint Configuration issuer. You can find the value in Realm Settings > OpenID Endpoint Configuration > Issuer.

Issuer

Audience

Audience
Token Claim Name	`external_oauth_audience_list`
Claim JSON Type	`String`
Add to access token	`ON`
Multivalues	`ON`
Claim value	This should be a list of audience supported by the security integration.

Token Claim Name

external_oauth_audience_list

Claim JSON Type

String

Add to access token

ON

Multivalues

ON

Claim value

This should be a list of audience supported by the security integration.

Audience Mapper

User Mapping

User Mapping
Token Claim Name	`external_oauth_user_mapping_claim`
Claim JSON Type	`String`
Add to access token	`ON`
Claim value	This should represent the mapping between keycloak user and Snowflake user.

Token Claim Name

external_oauth_user_mapping_claim

Claim JSON Type

String

Add to access token

ON

Claim value

This should represent the mapping between keycloak user and Snowflake user.

External User Mapper

External User Mapping Attribute

External User Mapping Attribute
Token Claim Name	`preferred_username_snowflake`
Claim JSON Type	`String`
Add to access token	`ON`
Claim value	This is a mapper that goes with your custom security integration. Its value is the Snowflake username of the authenticating user. Note how in the Snowflake custom security integration, we specified `external_oauth_token_user_mapping_claim='preferred_username_snowflake'`, instructing Snowflake to use the value of the key `preferred_username_snowflake`.

Token Claim Name

preferred_username_snowflake

Claim JSON Type

String

Add to access token

ON

Claim value

This is a mapper that goes with your custom security integration. Its value is the Snowflake username of the authenticating user. Note how in the Snowflake custom security integration, we specified external_oauth_token_user_mapping_claim='preferred_username_snowflake', instructing Snowflake to use the value of the key preferred_username_snowflake.

Preferred Username Mapper

RSA Public Key Value

RSA Public Key Value
Token Claim Name	`external_oauth_rsa_public_key_value`
Claim JSON Type	`String`
Add to access token	`ON`
Claim value	This should be the name of your OpenID Endpoint Configuration issuer. You can find the value in Realm Settings > Keys > Public Key from RS256

Token Claim Name

external_oauth_rsa_public_key_value

Claim JSON Type

String

Add to access token

ON

Claim value

This should be the name of your OpenID Endpoint Configuration issuer. You can find the value in Realm Settings > Keys > Public Key from RS256

PK Mapper

SCP

SCP
Token Claim Name	`scp`
Claim JSON Type	`String`
Add to access token	`ON`
Claim value	This is the attribute that defines the scope of authorization of the issued token.

Token Claim Name

scp

Claim JSON Type

String

Add to access token

ON

Claim value

This is the attribute that defines the scope of authorization of the issued token.

SCP Mapper

External User Mapping Attribute

External User Mapping Attribute
Token Claim Name	`external_oauth_snowflake_user_mapping_attribute`
Claim JSON Type	`String`
Add to access token	`ON`
Claim value	This is the attribute that is used to map the access token to a Snowflake user record.

Token Claim Name

external_oauth_snowflake_user_mapping_attribute

Claim JSON Type

String

Add to access token

ON

Claim value

This is the attribute that is used to map the access token to a Snowflake user record.

User Mapping Mapper

Keycloak propagates the values obtained by the mappers into the JWT token that is used to authenticate against the External OAuth Security Integration you created in Snowflake.

If you added a mapper that required a user attribute, add the proper user attribute at Users > View All Users > <user ID> > Attributes.

You can also automate this to create further roles and mappers, as in this example user attribute:
Add OAuth to the available authentication types for Snowflake:
1. Go to Platform settings > Configuration records.
2. Click Add Record.
3. Enter the com.cerebro.domino.datasource.SnowflakeConfig.enabledAuthTypes key with the value OAuth or Basic, OAuth. The order of the values matters, and the first value will be set as default authentication method for all users.
Click Create.

3. Test the configuration

To test that OAuth is working with your Snowflake Data Source, follow these steps:

Register a Snowflake Data Source.
Select OAuth as the authentication type.
Open an execution.
Query data from the registered Data Source.

Tip

To get the token itself, make a GET request to the Domino API Proxy by running curl $DOMINO_API_PROXY/access-token in an execution like in a terminal of a Workspace or a script of a Job. You can use https://jwt.io/ to copy/paste the token and see what is and is not being propagated correctly into the Domino JWT token from Keycloak.