Configuração do Okta para OAuth externo¶

Este tópico descreve como configurar o Snowflake como um recurso OAuth e o Okta como um servidor de autorização do External OAuth para facilitar o acesso seguro e programático aos dados do Snowflake.

Procedimento de configuração¶

As cinco etapas seguintes consideram que seu ambiente não tem nada configurado relacionado aos servidores de autorização Okta OAuth, clientes OAuth, escopos e metadados necessários.

As informações das etapas 1-3 serão utilizadas para criar uma integração de segurança no Snowflake.

Se você já tem um servidor de autorização Okta e um cliente configurado, não é necessário completar todas as etapas abaixo. Em vez disso, ignore as quatro etapas seguintes e verifique se você pode obter as informações desejadas, criar escopos, atribuir escopos a uma ou mais políticas e acessar os metadados.

Se você não tiver um cliente e servidor de autorização Okta OAuth configurados, complete todas as cinco etapas seguintes.

Importante

As etapas neste tópico são um exemplo representativo sobre como configurar o Okta para External OAuth.

Você pode configurar o Okta para qualquer estado desejado e usar qualquer fluxo OAuth desejado desde que você possa obter as informações necessárias para a integração de segurança (neste tópico).

Observe que os passos seguintes servem como um guia para obter as informações necessárias para criar a integração de segurança no Snowflake.

Não deixe de consultar suas políticas internas de segurança com relação à configuração de um servidor de autorização para assegurar que sua organização cumpra todos os regulamentos necessários e requisitos de conformidade.

As etapas 1-3 são derivadas da documentação Okta sobre servidores de autorização. Para mais informações sobre como a Okta define seus termos, sua interface de usuário e opções relacionadas aos servidores de autorização, consulte os seguintes guias Okta:

Criar um cliente OAuth compatível para usar com o Snowflake¶

Navegue até o Okta Admin Console.
Clique em Applications.
Clique em Add Application.
Clique em Create New App.
- Para Platform, selecione Native App.
Clique em Create.
Digite um nome para o aplicativo.
Na caixa Login redirect URIs, adicione a URL da conta Snowflake completa (ou seja, https://<account_identifier>.snowflakecomputing.com). Para obter uma lista de formatos de URL possíveis, consulte Conexão com uma URL.
Clique em Save.
A partir de New Applications na interface General, clique em Edit.
Verifique Refresh Token e Resource Owner Password.
Clique em Save.
Clique no botão Edit ao lado de Client Credentials.
Selecione a opção Use Client Authentication.
Clique em Save.
No contêiner Client Credentials, salve ClientID e Secret. Estes dois valores serão conhecidos como <OAUTH_CLIENT_ID> e <OAUTH_CLIENT_SECRET>, respectivamente, nas etapas seguintes.

Criar um servidor de autorização OAuth¶

Navegue até o Okta Admin Console.
No menu Security, clique em API.
Clique em Authorization Servers.
Clique em Add Authorization Server.
Digite um nome.
Digite a URL da conta Snowflake como o valor Audience. Para obter uma lista de formatos de URL possíveis, consulte Conexão com uma URL.
Clique em Save.

Complete as seguintes etapas para o servidor de autorização recém-adicionado.

Copie o valor Issuer. Seu formato deve ser parecido com https://dev-390798.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7. Este valor será conhecido como o <OKTA_ISSUER> nas etapas seguintes.
Clique em Scopes.
Clique em Add Scope.
Para adicionar uma função do Snowflake como um escopo, digite o escopo tendo o nome da função do Snowflake com o prefixo session:role: (por exemplo: para a função de analista do Snowflake, digite session:role:analyst).
Clique em Create.
Clique em Access Policies.
Clique em Add Policy.
Digite um nome e uma descrição para a política. Atribua-a ao cliente criado anteriormente e clique em Create.
Na nova política de acesso, clique em Add Rule.
Digite um nome de regra.
Selecione Grant Types autorizados. Você deve selecionar Resource Owner Password e Client Credentials junto com quaisquer outros que correspondam às políticas de sua organização.
Para os escopos, você pode selecionar qualquer um dos escopos ou selecionar os escopos desejados criados anteriormente que os clientes designados para esta política poderão solicitar (incluindo offline_access para tokens de atualização, se necessário). Configure qualquer configuração adicional conforme necessário.
Clique em Create Rule.

Coletar informações Okta¶

Vá para o Okta Admin Console.
No menu Security, clique em API.
Clique em Authorization Servers.
Clique no servidor de autorização para o recurso Snowflake.
Na guia Settings, copie o valor Issuer. Este valor será conhecido como o <OKTA_ISSUER> nas etapas seguintes. Seu formato deve ser parecido com https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7.

No documento Metadata:

Copie o valor Metadata URI, abra uma guia do navegador e cole a URL na barra de endereço.
Você deve ver o texto JSON no navegador. Você pode trabalhar com este texto em um editor de texto ou no próprio navegador.
Localize o parâmetro "jwks_uri" e copie seu valor. Seu formato deve ser parecido com https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7/v1/keys. Este ponto de extremidade será conhecido como <OKTA_JWS_KEY_ENDPOINT> nas etapas seguintes.
Localize o parâmetro "token_endpoint" e copie seu valor. Seu formato deve ser parecido com https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7/v1/token. Este ponto de extremidade será conhecido como <OKTA_OAUTH_TOKEN_ENDPOINT> nas etapas seguintes.

Criar uma integração de segurança para o Okta¶

Esta etapa cria uma integração de segurança no Snowflake. A integração de segurança garante que o Snowflake possa se comunicar com o Okta com segurança, valida os tokens do Okta e fornece o acesso apropriado aos dados do Snowflake aos usuários com base na função do usuário associada ao token OAuth.

Para obter mais informações, consulte CREATESECURITYINTEGRATION.

Importante

Somente administradores de conta (ou seja, usuários com a função ACCOUNTADMIN) ou uma função com o privilégio global CREATE INTEGRATION podem executar este comando SQL.

Os valores dos parâmetros de integração de segurança diferenciam maiúsculas e minúsculas, e os valores que você coloca na integração de segurança devem corresponder a esses valores em seu ambiente. Se maiúsculas e minúsculas não corresponderem, é possível que o token de acesso não seja validado, resultando em uma falha da tentativa de autenticação.

Criar uma integração de segurança com públicos

O parâmetro external_oauth_audience_list da integração de segurança deve corresponder ao Audience que você especificou durante a configuração do Okta.

create security integration external_oauth_okta_2
    type = external_oauth
    enabled = true
    external_oauth_type = okta
    external_oauth_issuer = '<OKTA_ISSUER>'
    external_oauth_jws_keys_url = '<OKTA_JWS_KEY_ENDPOINT>'
    external_oauth_audience_list = ('<snowflake_account_url')
    external_oauth_token_user_mapping_claim = 'sub'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';

Copy

Modificação de sua integração de segurança External OAuth¶

Você pode atualizar sua integração de segurança External OAuth executando uma instrução ALTER para a integração de segurança.

Para obter mais informações, consulte ALTER SECURITY INTEGRATION (OAuth externo).

Uso da função ANY com External OAuth¶

Na etapa de configuração para criar uma integração de segurança no Snowflake, o token de acesso OAuth inclui a definição do escopo. Portanto, no tempo de execução, usar a integração de segurança External OAuth não permite nem ao cliente OAuth nem ao usuário usar uma função indefinida no token de acesso OAuth.

Após validar o token de acesso e criar uma sessão, a função ANY pode permitir que o cliente OAuth e o usuário decidam sua função. Se necessário, o cliente ou o usuário pode mudar para uma função que seja diferente da função definida no token de acesso OAuth.

Para configurar a função ANY, defina o escopo como SESSION:ROLE-ANY e configure a integração de segurança com o parâmetro external_oauth_any_role_mode. Este parâmetro pode ter três valores de cadeia de caracteres possíveis:

DISABLE não permite que o cliente OAuth ou usuário troque de função (ou seja, use role <função>;). Padrão.
ENABLE permite que o cliente OAuth ou usuário troque de função.
ENABLE_FOR_PRIVILEGE permite que o cliente OAuth ou usuário troque de função somente para um cliente ou usuário com o privilégio USE_ANY_ROLE. Este privilégio pode ser concedido e revogado para uma ou mais funções disponíveis para o usuário. Por exemplo:
```
grant USE_ANY_ROLE on integration external_oauth_1 to role1;
```
Copy
```
revoke USE_ANY_ROLE on integration external_oauth_1 from role1;
```
Copy

Defina a integração de segurança da seguinte forma:

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

Copy

Uso de funções secundárias com External OAuth¶

O escopo desejado para a função primária é passado no token externo: ou a função padrão para o usuário (session:role-any) ou uma função específica que foi concedida ao usuário (session:role:<nome_da_função>).

Por padrão, o Snowflake não ativa as funções secundárias padrão para um usuário (ou seja, DEFAULT_SECONDARY_ROLES) na sessão.

Para ativar as funções secundárias padrão para um usuário em uma sessão e permitir a execução do comando USE SECONDARY ROLES enquanto utiliza External OAuth, complete as seguintes etapas:

Configure a integração de segurança para a conexão. Defina o valor do parâmetro EXTERNAL_OAUTH_ANY_ROLE_MODE como ENABLE ou ENABLE_FOR_PRIVILEGE quando criar a integração de segurança (usando CREATE SECURITY INTEGRATION) ou mais tarde (usando ALTER SECURITY INTEGRATION).
Configure o servidor de autorização para passar o valor estático de session:role-any no atributo de escopo do token. Para obter mais informações sobre o parâmetro de escopo, consulte Visão geral de External OAuth.

Uso do redirecionamento do cliente com External OAuth¶

O Snowflake oferece suporte para o uso do redirecionamento do cliente com External OAuth, incluindo o uso do redirecionamento do cliente e OAuth com clientes Snowflake com suporte.

Para obter mais informações, consulte Redirecionamento de conexões do cliente.

Uso de políticas de rede com External OAuth¶

Atualmente, políticas de rede não podem ser adicionadas à sua integração de segurança External OAuth. Entretanto, você ainda pode implementar políticas de rede que se aplicam amplamente a toda a conta Snowflake.

Se seu caso de uso exigir uma política de redes que seja específica para a integração de segurança OAuth, use Snowflake OAuth. Esta abordagem permite que a política de redes OAuth do Snowflake seja distinta de outras políticas de rede que possam se aplicar à conta Snowflake.

Para obter mais informações, consulte Políticas de redes.

Uso da replicação com External OAuth¶

O Snowflake oferece suporte à replicação e failover/failback da integração de segurança OAuth externo a partir da conta de origem para a conta de destino.

Para obter mais detalhes, consulte Replicação de integrações de segurança e políticas de redes em múltiplas contas.

Procedimento de teste¶

No contexto de testes do OAuth ao usar o Okta como um servidor de autorização, você deve:

Verificar se o usuário do teste existe no Okta e se tem uma senha.
Verifique se o usuário do teste existe no Snowflake com seu valor de atributo login_name definido para o <OKTA_USER_USERNAME>
Registrar um cliente OAuth.
Permitir ao cliente OAuth fazer uma solicitação POST ao ponto de extremidade de token do Okta, como se segue:
- Tipo de concessão definida para proprietário de recursos
- Cabeçalho HTTP de autorização básica contendo clientID e segredo
- Dados FORM contendo o nome de usuário e senha
- Incluir escopos

O comando de exemplo solicita o analista e isso considera que session:role:analyst foi definida em Okta > OAuth App Resource.

Aqui está um exemplo para obter um token de acesso usando cURL.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --user <OAUTH_CLIENT_ID>:<OAUTH_CLIENT_SECRET> \
  --data-urlencode "username=<OKTA_USER_USERNAME>" \
  --data-urlencode "password=<OKTA_USER_PASSWORD>" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=session:role:analyst" \
  <OKTA_OAUTH_TOKEN_ENDPOINT>

Copy

Conexão ao Snowflake com External OAuth¶

Após configurar sua integração de segurança e obter seu token de acesso, você pode se conectar ao Snowflake usando uma das seguintes opções:

Observe o seguinte:

É necessário definir o parâmetro authenticator como oauth e o parâmetro token como external_oauth_access_token.
Ao passar o valor token como um parâmetro de consulta de URL, é necessário codificar o valor token para a URL.
Ao passar o valor token para um objeto Properties (por exemplo, driver JDBC), nenhuma modificação é necessária.

Por exemplo, se estiver usando o Conector Python, defina a cadeia de conexão como mostrado abaixo.

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"
)

Copy

Agora você pode usar o External OAuth para se conectar ao Snowflake de forma segura.