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 (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:

  Copy codeExpand code block

  grant USE_ANY_ROLE on integration external_oauth_1 to role1;

  Show lessSee more

  Scroll to top
  Copy codeExpand code block

  revoke USE_ANY_ROLE on integration external_oauth_1 from role1;

  Show lessSee more

  Scroll to top

Define the security integration as follows:

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

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:

1. 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).
2. 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.

Currently, network policies cannot be added to your External OAuth security integration. However, you can still implement network policies that apply broadly to the entire Snowflake account.

If your use case requires a network policy that is specific to the OAuth security integration, use Snowflake OAuth. This approach allows the Snowflake OAuth network policy to be distinct from other network policies that may apply to the Snowflake account.

For more information, see Restricting network traffic for Snowflake OAuth.

Snowflake supports replication and failover/failback of the External OAuth security integration from a source account to a target account.

For details, see Replication of security integrations & network policies across multiple accounts.

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

• SnowSQL
• Python Connector
• Go Driver (https://godoc.org/github.com/snowflakedb/gosnowflake#hdr-Connection_Parameters)
• JDBC Driver
• ODBC Driver
• Spark Connector
• .NET Driver (https://github.com/snowflakedb/snowflake-connector-net/blob/master/README.md#create-a-connection)
• Node.js Driver

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.