Configuração de servidores de autorização personalizados para External OAuth

Este tópico descreve como criar uma integração de segurança externa OAuth no Snowflake para que os clientes possam acessar os dados do Snowflake autenticando-se com um servidor de autorização personalizado.

Se seu servidor de autorização for um provedor de identidade suportado (IdP) em vez de um provedor personalizado, consulte o tópico focado na configuração desse IdP específico.

Neste tópico:

Requisitos de carga útil de token do External OAuth

O token de acesso que os servidores de autenticação personalizados enviam ao Snowflake deve conter as seguintes informações de carga útil. Para obter mais informações sobre a coluna Claims, consulte Declarações JWT.

Declarações

Descrição

scp

Escopos. Uma lista de escopos no token de acesso.

escopo

Escopos.

Uma sequência de escopos separados por vírgula no token de acesso.

O Snowflake oferece suporte à especificação de qualquer caractere único para o delimitador, tal como um espaço (ou seja, ' '), definindo a propriedade EXTERNAL_OAUTH_SCOPE_DELIMITER ao criar ou modificar a integração de segurança do OAuth externo para servidores de autorização personalizados.

Contate o suporte Snowflake para ativar esta propriedade em sua conta Snowflake.

aud

Público. Identifica os destinatários aos quais o token de acesso é destinado como um URI de cadeia de caracteres.

exp

Tempo de expiração. Identifica o tempo de expiração em ou após o qual o token de acesso não deve ser aceito para processamento.

iss

Emissor. Identifica o principal que emitiu o token de acesso como um URI de cadeia de caracteres.

iat

Emitido em. Obrigatório. Identifica o momento em que o JWT foi emitido.

Nota

O Snowflake suporta a declaração nbf (não antes), que identifica o tempo antes do qual o token de acesso não deve ser aceito para processamento.

Se seu servidor de autorização personalizado oferecer suporte à declaração nbf (não antes), você pode incluir opcionalmente a declaração nbf no token de acesso.

Para verificar se seu token contém as informações necessárias, você pode testar o token neste site de Tokens JSON da Web.

Como um exemplo representativo, a interface PAYLOAD: DATA exibe a carga útil do token da seguinte forma.

{
  "aud": "<audience_url>",
  "iat": 1576705500,
  "exp": 1576709100,
  "iss": "<issuer_url>",
  "scp": [
    "session:role:analyst"
  ]
}
Copy

Procedimento de configuração

As etapas seguintes consideram que seu servidor de autorização personalizado e ambiente podem ser configurados para obter os valores necessários para criar a integração de segurança do Snowflake.

Importante

As etapas neste tópico são um exemplo representativo de como configurar servidores de autorização personalizados.

Você pode configurar seu ambiente para qualquer estado desejado e usar qualquer fluxo do OAuth externo desejado desde que possa obter as informações necessárias para a integração de segurança do OAuth externo.

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

Consulte suas políticas internas de segurança antes de configurar um servidor de autorização personalizado para garantir que sua organização atenda a todos os regulamentos e requisitos de conformidade.

Obter valores de ambiente chave para usar External OAuth

Ao configurar seu IdP e servidor de autorização, você deve coletar os seguintes valores para definir uma integração de segurança do OAuth externo:

URL do emissor:

Inclua esta URL com o parâmetro external_oauth_issuer.

Chave pública RSA:

Inclua este valor com o parâmetro external_oauth_rsa_public_key.

URLs de público:

Se for necessário mais de uma URL de público, separe cada URL com uma vírgula no parâmetro external_oauth_audience_list.

Atributo de escopo:

Você pode definir esse valor como scp ou scope. Por padrão, esse valor é scp.

Você pode definir o valor do parâmetro external_oauth_scope_mapping_attribute como esse valor.

Se você não usar o valor padrão, scp, defina o valor do parâmetro external_oauth_scope_mapping_attribute como scope.

Para obter mais informações, consulte Requisitos de carga útil de token do External OAuth.

Atributo de usuário:

Este atributo se refere ao atributo para identificar usuários em seu IdP. Inclua este valor de atributo no parâmetro external_oauth_user_mapping_claim.

Atributo de usuário do Snowflake:

O atributo no Snowflake para identificar os usuários. Inclua este valor no parâmetro external_oauth_snowflake_user_mapping_attribute.

Criação de uma integração de segurança de External OAuth no Snowflake

Esta etapa cria uma integração de segurança externa OAuth no Snowflake. A integração de segurança do OAuth externo garante que o Snowflake possa se comunicar com segurança e validar os tokens de acesso a partir de seu servidor de autorização personalizado, e fornece aos usuários acesso aos dados do Snowflake com base em sua função de usuário associada ao token de acesso. Para obter mais informações, consulte CREATE SECURITY INTEGRATION.

Importante

Somente administradores de conta 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 do OAuth externo diferenciam maiúsculas e minúsculas, e os valores que você coloca na integração de segurança do OAuth externo devem corresponder aos valores em seu ambiente. Caso um valor não seja correspondente, é possível que o token de acesso não seja validado, resultando em uma falha da tentativa de autenticação.

Criação de uma integração de segurança de External OAuth no Snowflake

create security integration external_oauth_custom
    type = external_oauth
    enabled = true
    external_oauth_type = custom
    external_oauth_issuer = '<authorization_server_url>'
    external_oauth_rsa_public_key = '<public_key_value>'
    external_oauth_audience_list = ('<audience_url_1>', '<audience_url_2>')
    external_oauth_token_user_mapping_claim = 'upn'
    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:

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

  2. 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 OAuth externo, incluindo o uso do redirecionamento do cliente e OAuth externo 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

Para testar a configuração de um servidor de autorização personalizado:

  1. Verificar se o usuário do teste existe em seu IdP e se tem uma senha.

  2. Verificar se o usuário do teste existe no Snowflake com seu valor de atributo login_name definido para a declaração <declaração_mapeamento_usuário_token_external_oauth>.

  3. Registro de um cliente OAuth 2.0

  4. Permitir ao cliente OAuth 2.0 fazer uma solicitação POST ao ponto de extremidade do token personalizado, como 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 a função ANALYST personalizada e isso considera que session:role:analyst foi definido em seu servidor de autorização personalizado.

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=<IdP_USER_USERNAME>" \
  --data-urlencode "password=<IdP_USER_PASSWORD>" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=session:role:analyst" \
  <IdP_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.