Uso de tokens de acesso programático para autenticação¶

Requisitos da política de redes¶

Por padrão, o usuário deve estar sujeito a uma política de redes com uma ou mais regras de rede para gerar ou usar tokens de acesso programático:

• Para usuários de serviço (onde TYPE=SERVICE para o usuário), você só pode gerar ou usar um token se o usuário estiver sujeito a uma política de redes.

  Esse pré-requisito limita o uso do token a solicitações de um conjunto específico de endereços ou identificadores de rede.

• Para usuários humanos (onde TYPE=PERSON para o usuário), você pode gerar um token mesmo que o usuário não esteja sujeito a uma política de redes, mas o usuário deve estar sujeito a uma política de redes para se autenticar com esse token.

  Se um usuário humano que não estiver sujeito a uma política de redes precisar usar um token de acesso programático para autenticação, você poderá ignorar temporariamente o requisito de ter uma política de redes, mas não recomendamos isso. Consulte Geração de um token de acesso programático.

  Nota

  Os usuários não podem ignorar a própria política de redes.

A política de redes pode ser ativada para todos os usuários da conta ou para um usuário específico.

Para alterar esse requisito, crie ou modifique uma política de autenticação que especifique uma política de token de acesso programático.

Execute o comando CREATE AUTHENTICATION POLICY ou ALTER AUTHENTICATION POLICY. Na cláusula PAT_POLICY, defina NETWORK_POLICY_EVALUATION como um dos seguintes valores:

ENFORCED_REQUIRED (comportamento padrão)

O usuário deve estar sujeito a uma política de redes para gerar e usar tokens de acesso programático.

Se o usuário estiver sujeito a uma política de redes, a política de redes será aplicada durante a autenticação.

ENFORCED_NOT_REQUIRED

O usuário não precisa estar sujeito a uma política de redes para gerar e usar tokens de acesso programático.

Se o usuário estiver sujeito a uma política de redes, a política de redes será aplicada durante a autenticação.

NOT_ENFORCED

O usuário não precisa estar sujeito a uma política de redes para gerar e usar tokens de acesso programático.

Se o usuário estiver sujeito a uma política de redes, a política de redes não será aplicada durante a autenticação.

Por exemplo, para criar uma política de autenticação que remova o requisito de política de redes, mas que aplique qualquer política de redes à qual o usuário esteja sujeito:

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    NETWORK_POLICY_EVALUATION = ENFORCED_NOT_REQUIRED
  );

Em seguida, aplica a política de autenticação a uma conta ou usuário.

Como outro exemplo, alterar uma política de autenticação existente para remover o requisito da política de redes e impedir a aplicação de qualquer política de redes à qual o usuário esteja sujeito:

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    NETWORK_POLICY_EVALUATION = NOT_ENFORCED
  );

Requisitos da política de autenticação¶

Se houver uma política de autenticação que limite os métodos de autenticação de um usuário, o usuário não poderá gerar e usar tokens de acesso programático, a menos que a lista AUTHENTICATION_METHODS dessa política inclua 'PROGRAMMATIC_ACCESS_TOKEN'.

Por exemplo, suponha que uma política de autenticação limite os usuários ao uso dos métodos OAuth e de senha para autenticação:

CREATE AUTHENTICATION POLICY my_auth_policy
  ...
  AUTHENTICATION_METHODS = ('OAUTH', 'PASSWORD')
  ...

Os usuários não podem gerar e usar tokens de acesso programático, a menos que você adicione 'PROGRAMMATIC_ACCESS_TOKEN' à lista AUTHENTICATION_METHODS. Você pode usar o comando ALTER AUTHENTICATION POLICY para atualizar essa lista.

Por exemplo:

ALTER AUTHENTICATION POLICY my_auth_policy
  SET AUTHENTICATION_METHODS = ('OAUTH', 'PASSWORD', 'PROGRAMMATIC_ACCESS_TOKEN');

Configuração do tempo máximo de expiração¶

Por padrão, você pode especificar um tempo de expiração de até 365 dias para um token. Se quiser reduzir esse tempo para um período menor, crie ou modifique uma política de autenticação que especifique uma política de token de acesso programático com um tempo máximo de expiração.

Execute o comando CREATE AUTHENTICATION POLICY ou ALTER AUTHENTICATION POLICY. Na cláusula PAT_POLICY, defina MAX_EXPIRY_IN_DAYS como um valor que varia de 1 a 365.

Por exemplo, para criar uma política de autenticação que defina o máximo para 100 dias:

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    MAX_EXPIRY_IN_DAYS=100
  );

Em seguida, aplica a política de autenticação a uma conta ou usuário.

Como outro exemplo, para alterar uma política de autenticação existente e definir o máximo para 90 dias:

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    MAX_EXPIRY_IN_DAYS=90
  );

Configuração do tempo de expiração padrão¶

Por padrão, um token de acesso programático expira após 15 dias. Se quiser alterar isso, crie ou modifique uma política de autenticação que especifique uma política de token de acesso programático com uma expiração padrão.

Execute o comando CREATE AUTHENTICATION POLICY ou ALTER AUTHENTICATION POLICY. Na cláusula PAT_POLICY, defina DEFAULT_EXPIRY_IN_DAYS como um valor que varia de 1 até o tempo máximo de expiração.

Por exemplo, para criar uma política de autenticação que defina o padrão como 5 dias:

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    DEFAULT_EXPIRY_IN_DAYS=5
  );

Em seguida, aplica a política de autenticação a uma conta ou usuário.

Como outro exemplo, para alterar uma política de autenticação existente para definir o padrão para 30 dias:

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    DEFAULT_EXPIRY_IN_DAYS=30
  );

Uso de um token de acesso programático como senha¶

Para autenticar com um token de acesso programático como senha, você pode especificar o token para o valor da senha nas configurações do driver ou na chamada para se conectar ao Snowflake.

Por exemplo, se estiver usando o Snowflake Connector para Python, você pode especificar o token de acesso programático como o argumento password ao chamar o método snowflake.connector.connect.

conn = snowflake.connector.connect(
    user=USER,
    password=<programmatic_access_token>,
    account=ACCOUNT,
    warehouse=WAREHOUSE,
    database=DATABASE,
    schema=SCHEMA
)

Da mesma forma, você pode usar tokens de acesso programático no lugar de uma senha em aplicativos de terceiros (como o Tableau ou PowerBI). Cole o token de acesso programático no campo da senha.

Uso de um token de acesso programático para autenticação em um ponto de extremidade¶

Para autenticar com um token de acesso programático, defina os seguintes cabeçalhos HTTP na solicitação:

• Authorization: Bearer token_secret

• X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN (opcional)

Por exemplo, se estiver usando um cURL para enviar uma solicitação a um ponto de extremidade da Snowflake REST API:

curl --location 'https://myorganization-myaccount.snowflakecomputing.com/api/v2/databases' \
  --header "Authorization: Bearer <token_secret>"

Como outro exemplo, se você estiver usando cURL para enviar uma solicitação ao ponto de extremidade da Snowflake SQL API:

curl -si -X POST https://myorganization-myaccount.snowflakecomputing.com/api/v2/statements \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer <token_secret>" \
  --data '{"statement": "select 1"}'

Se a solicitação falhar com um erro PAT_INVALID, o erro pode ter ocorrido por um dos seguintes motivos:

• O usuário associado ao token de acesso programático não foi encontrado.

• A validação falhou.

• A função associada ao token de acesso programático não foi encontrada.

• O usuário não está associado ao token de acesso programático especificado.

Listagem de tokens de acesso programático¶

Você pode listar o token de acesso programático de um usuário no Snowsight ou executar comandos SQL.

SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER example_user;

Como renomear um token de acesso programático¶

Você pode alterar o nome de um token de acesso programático no Snowsight ou executar comandos SQL.

Rotação de um token de acesso programático¶

Você pode girar um token de acesso programático no Snowsight ou executar comandos SQL.

A rotação de um token retorna um novo segredo de token que tem o mesmo nome e um tempo de expiração estendido. A rotação de um token também expira o segredo do token existente. Use o novo token para se autenticar no Snowflake.

ALTER USER IF EXISTS example_user ROTATE PROGRAMMATIC ACCESS TOKEN example_token;

ALTER USER IF EXISTS example_user
  ROTATE PROGRAMMATIC ACCESS TOKEN example_token
  EXPIRE_ROTATED_TOKEN_AFTER_HOURS = 0;

+---------------+-----------------+-------------------------------------+
| token_name    | token_secret    | rotated_token_name                  |
|---------------+-----------------+-------------------------------------|
| EXAMPLE_TOKEN | ... (token) ... | EXAMPLE_TOKEN_ROTATED_1744239049066 |
+---------------+-----------------+-------------------------------------+

Revogação de um token de acesso programático¶

Você pode revogar um token de acesso programático no Snowsight ou executar comandos SQL.

ALTER USER IF EXISTS example_user REMOVE PROGRAMMATIC ACCESS TOKEN example_token;