Uso do Snowflake OAuth para aplicativos locais

This topic describes the preferred authentication method for local applications, including desktop applications and local scripts.

Snowflake OAuth is implemented by creating a security integration that defines an interface between Snowflake as the OAuth authorization server and the application that is authenticating on behalf of a user by using the OAuth authorization code flow. Snowflake OAuth is a strong authentication option because the application doesn’t have to store or manage secrets, and you don’t have to configure a third-party identity provider like External OAuth.

To simplify how a local application uses Snowflake OAuth to authenticate, your account has a built-in security integration called SNOWFLAKE$LOCAL_APPLICATION. Because the security integration already exists, if a local application uses a Snowflake client like the Python driver or Snowflake CLI, the application can authenticate to Snowflake by setting a property or parameter of the client. No further set up is required. The built-in integration also simplifies the setup for local applications that call the OAuth endpoints directly rather than use a Snowflake client.

Um administrador pode alterar os parâmetros da integração SNOWFLAKE$LOCAL_APPLICATION para ajustar o comportamento, como especificar por quanto tempo os tokens de acesso e de atualização do OAuth são válidos.

O Snowflake OAuth para aplicativos locais tem as seguintes vantagens adicionais:

  • Unlike user-created Snowflake OAuth integrations, in-role session switching is supported.

  • Isso é uma substituição direta para aplicativos que atualmente usam apenas senhas para autenticar usuários. O Snowflake está descontinuando senhas de fator único; portanto, o Snowflake OAuth para aplicativos locais oferece um caminho para usar uma forma mais segura de autenticação sem exigir muita configuração.

Nota

A integração de segurança SNOWFLAKE$LOCAL_APPLICATION está sendo implementada gradualmente em todas as contas. Para determinar se essa integração incorporada existe em sua conta, execute o seguinte comando:

SHOW SECURITY INTEGRATIONS LIKE 'SNOWFLAKE$LOCAL_APPLICATION';
Copy

Configuração da integração do Snowflake OAuth

A integração de segurança SNOWFLAKE$LOCAL_APPLICATION incorporada pertence ao sistema, mas pode ser configurada por administradores de segurança (ou seja, usuários com a função de sistema SECURITYADMIN).

Os administradores de segurança podem configurar os seguintes parâmetros da integração de segurança:

Parâmetro

Descrição

ENABLED

Controla se a integração está habilitada. Se a integração estiver desabilitada, os aplicativos locais deverão usar um método de autenticação diferente.

OAUTH_ISSUE_REFRESH_TOKENS

Controls whether the authorization server issues refresh tokens.

OAUTH_REFRESH_TOKEN_VALIDITY

Define a duração da validade dos tokens de atualização.

OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED

Controls whether the authorization server issues single-use refresh tokens.

OAUTH_ACCESS_TOKEN_VALIDITY

Define a duração da validade dos tokens de acesso.

For example, to modify the built-in security integration so that the authorization server starts issuing single-use refresh tokens, run the following commands:

USE ROLE SECURITYADMIN;

ALTER SECURITY INTEGRATION SNOWFLAKE$LOCAL_APPLICATION
  SET OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED = TRUE;
Copy

Para obter mais informações sobre como definir esses parâmetros, consulte ALTER SECURITY INTEGRATION.

Controle da frequência de login

When OAUTH_ISSUE_REFRESH_TOKENS = TRUE, applications can use refresh tokens to obtain new access tokens without prompting users to log in again. Users only need to re-authenticate when the refresh token expires after the duration that is specified by the OAUTH_REFRESH_TOKEN_VALIDITY parameter.

Configuração de um aplicativo local para usar o Snowflake OAuth

This section provides the details a developer needs to configure a local application to authenticate with Snowflake OAuth. The following types of local applications can authenticate by using the built-in integration:

Aplicativos que usam um cliente Snowflake

When a local application uses a Snowflake client like the Snowflake ODBC driver, it can authenticate with Snowflake OAuth by setting the authenticator connection option to oauth_authorization_code. Additional development work isn’t required.

Pré-requisito

With Snowflake OAuth for local applications, the Snowflake client must be able to open the user’s web browser. For this reason, both the Snowflake client and the local application that uses it must be installed on the user’s computer. Snowflake OAuth for local applications doesn’t work if the Snowflake client is used by code that runs on a server.

Clientes compatíveis

Seu aplicativo local pode usar os seguintes clientes Snowflake para autenticar com o Snowflake OAuth para aplicativos locais:

Cliente

Versão mínima exigida

Configuração obrigatória

.NET

v4.8.0

Defina authenticator=oauth_authorization_code na cadeia de conexão.

Go

v1.14.1

Defina authenticator=oauth_authorization_code na configuração de conexão.

JDBC

v3.24.1

Defina authenticator=oauth_authorization_code na cadeia de conexão para o driver.

Node.js

v2.1.0

Defina authenticator: 'oauth_authorization_code' nas opções de conexão.

ODBC

v3.9.0

  • Para Linux e macOS, defina authenticator=oauth_authorization_code no arquivo odbc.ini.

  • Para Windows, na ferramenta ODBC Data Source Administrator, edite o DSN para o Snowflake e defina o autenticador como oauth_authorization_code.

Python

v3.16.0

Passe AUTHENTICATOR=OAUTH_AUTHORIZATION_CODE para a função snowflake.connector.connect().

Snowflake CLI

v3.8.1

Adicione a opção authenticator = "OAUTH_AUTHORIZATION_CODE" à definição de conexão.

SnowSQL

v1.4.0

Adicione o parâmetro authenticator = "OAUTH_AUTHORIZATION_CODE" no arquivo de configuração.

Aplicativos que chamam pontos de extremidade do OAuth diretamente

Your local application can use Snowflake OAuth by making requests to the authorization endpoint and token endpoint of Snowflake as the authorization server. You don’t need to use a Snowflake client. The application sends a request to Snowflake’s authorization endpoint to authenticate the user and receive an authorization code, and then sends a request to the token endpoint to exchange that code for an access token.

Para obter mais informações sobre como fazer solicitações REST aos pontos de extremidade de autorização e token do Snowflake, consulte Chamada dos pontos de extremidade do OAuth.

Requisitos para solicitações

As solicitações REST do seu aplicativo aos pontos de extremidade de autorização e token devem estar em conformidade com os seguintes requisitos:

  • The redirect URL in the request to the authorization endpoint must be http://127.0.0.1[:port][/path]. That is, your local application must be listening on a loopback address for the authorization code that is returned by Snowflake as the authorization server.

  • As solicitações aos pontos de extremidade de autorização e token devem implementar a Proof Key for Code Exchange (PKCE). Para obter mais informações, consulte Proof Key for Code Exchange.

  • When calling the token endpoint to exchange an authorization code for an access token, the application must provide the proper client ID and client secret. This requirement varies slightly depending on how you choose to send these client credentials:

    • Se você enviar as credenciais do cliente no cabeçalho da solicitação, o ID do cliente deverá ser LOCAL_APPLICATION e o segredo do cliente deverá ser LOCAL_APPLICATION.

    • Se você enviar as credenciais do cliente no corpo POST, o ID do cliente deverá ser LOCAL_APPLICATION. A integração incorporada configura o aplicativo local como um cliente público; portanto, o segredo do cliente não é necessário se você fornecer o ID do cliente como client_id=LOCAL_APPLICATION no corpo de POST.

Notas de uso

Every account has a SNOWFLAKE$LOCAL_APPLICATION integration, so this integration isn’t replicated. The configuration of the built-in integration is unique to each account.

Linguagem: Português