About DominoArchitecture
Keycloak Authentication Service
Data Management
Troubleshooting
About Domino
Domino Data LabKnowledge BaseData Science BlogTraining

Configure Data Source Authentication

As an administrator, you can configure the authentication options that are available to users.

Add or remove authentication methods

By default, only basic authentication is supported for data source authentication. For some data source types, you can enable additional authentication methods.

Add an authentication method for a data source type

  1. Navigate to Admin > Advanced > Central Config.

  2. Click Add Record.

  3. Follow the schema below to add the supported key-value pair.

    The value is a comma-separated text value where each word is an authentication type; see the data source authentication configuration reference for the valid values for each data source type.

  4. Click Create.

An example configuration is shown below:

CC-Sample

Note
Note
Remove an authentication method

  1. Go to Admin > Advanced > Central Config.

  2. Click the Edit icon next to the relevant configuration key.

  3. Remove the authentication method from the list of values.

  4. Click Save.

Set up OAuth for Snowflake

Follow the guide below to enable users to create OAuth-backed Snowflake data sources, and authenticate and query Snowflake using an automatically-propagated JWT token. Once this is set up, users can select OAuth upon Snowflake datasource creation. When an OAuth-configured Snowflake is queried within a Domino execution, the Domino JWT token is used by the dominodatalab-data library to authenticate against the underlying Snowflake database; if set up properly, no extra user action is necessary. The effort to set up Snowflake OAuth is two-fold:

  1. Configure Snowflake by setting up an External OAuth Security Integration within your Snowflake account. This dictates what values your Snowflake account will expect to be propagated inside the token for successful authentication.

  2. Set up Keycloak to ensure correct propagation of the necessary values in the Domino JWT access token.

Note
Note

1. Configure Snowflake

To set up an External OAuth Security Integration within 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.

Below 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 one below:

Snowflake Security Integration

2. Set up Keycloak integration

The steps below specify how to instruct Keycloak to pass the values that Snowflake’s custom security integration expects in the Domino JWT access token. You do so by creating mappers in the domino-play client and specifying 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.

Below, is a base solution that matches the base Snowflake custom security integration above. This solution is a starting point to build upon for a customized authentication configuration that fits your security needs.

Set up the Keycloak integration:

  1. Access the keycloak admin console at https://<domino-domain>/auth/.

  2. Click Clients. It should look like this:

    Keycloak Client Dashboard

  3. Click the domino-play client ID.

  4. Click Mappers. It should look like this:

    Mappers

  5. Add the mappers described below. 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.

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

    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

    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

    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

    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

    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

    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

    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

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

    Alternatively, automate this to create further roles and mappers, as in this example user attribute:

    User Attribute

  7. Add OAuth to the available authentication types for Snowflake:

  8. Navigate to Admin > Advanced > Central Config.

  9. Click Add Record.

  10. Enter the com.cerebro.domino.datasource.SnowflakeConfig.enabledAuthTypes key with the value OAuth or Basic, OAuth. Note that the order of the values matters, and the first value will be set as default authentication method for all users.

    CC-Sample

  11. Click Create.

3. Test the configuration

To test that OAuth is working with your Snowflake data source, follow these steps:

  1. Register a Snowflake data source.

  2. Select OAuth as the authentication type.

  3. Open an execution.

  4. Query data from the registered data source.

Tip

Set up IAM authentication

As an admin, you can enable users to create data sources using IAM authentication for these AWS-based data source types:

Note
Set up IAM authentication

  1. Configure single sign-on (SSO).

  2. Configure AWS credential propagation.

  3. Add IAM to the available authentication options for one or more of the supported data source types.

  4. Navigate to Admin > Advanced > Central Config.

  5. Click Add Record.

  6. Enter one of the keys below with the value AWSIAMRole or Basic, AWSIAMRole.

    • com.cerebro.domino.datasource.MySQLConfig.enabledAuthTypes

    • com.cerebro.domino.datasource.PostgreSQLConfig.enabledAuthTypes

    • com.cerebro.domino.datasource.RedshiftConfig.enabledAuthTypes

    • com.cerebro.domino.datasource.S3Config.enabledAuthTypes

    See the configuration reference for complete details about the supported configurations.

  7. Click Create.

Domino Data LabKnowledge BaseData Science BlogTraining
Copyright © 2022 Domino Data Lab. All rights reserved.