Configuração do PingFederate para OAuth externo

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

Neste tópico:

Procedimento de configuração

As duas etapas seguintes consideram que seu ambiente não tem nada configurado relacionado aos servidores de autorização PingFederateOAuth, clientes OAuth, escopos e metadados necessários. Estas etapas também são um exemplo representativo de como configurar o PingFederate.

As informações da primeira etapa serão utilizadas para criar uma integração de segurança do Snowflake.

Se você já tem um servidor de autorização PingFederate e um cliente configurado, não é necessário completar todas as etapas abaixo. Em vez disso, ignore a primeira etapa 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 PingFederateOAuth configurados, complete ambas as etapas.

Importante

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

Você pode configurar o PingFederate para qualquer estado desejado e usar qualquer fluxo OAuth desejado desde que 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.

A etapa 1 deriva da documentação PingIdentity sobre OAuth 2.0. Para mais informações sobre como a PingIdentity define seus termos, sua interface de usuário e opções relacionadas aos servidores de autorização, consulte o seguinte guia PingIdentity:

Configuração de PingFederate

  1. Navegue até a página de downloads do servidor PingFederate e baixe ou atualize sua instância PingFederate com base em seu sistema operacional.

  2. Use o guia de instalação do PingFederate para seu sistema operacional. Após a instalação, acesse PingFederate.

  3. Crie os escopos OAuth navegando para a interface Exclusive Scopes no painel OAuth Server.

  4. Para adicionar uma função do Snowflake como escopo, adicione-a ao Scope Value. A função do Snowflake deve ter o prefixo session:role: (por exemplo, para a função de analista do Snowflake, digite session:role:analyst).

  5. Digite uma descrição para o escopo na caixa Scope Description e clique em Add.

  6. Navegue até a guia OAuth Server e crie um novo cliente. Verifique os seguintes valores.

    Campo

    Valor

    NAME

    Um nome amigável para o servidor de autorização PingFederate OAuth

    DESCRIPTION

    Uma descrição amigável para o servidor de autorização PingFederate OAuth

    CLIENT AUTHENTICATION

    CLIENT SECRET

    EXCLUSIVE SCOPES

    Selecione os escopos (ou seja, funções do Snowflake)

    ALLOWED GRANT TYPES

    Escolha Refresh Token e Resource Owner Password Credentials

    DEFAULT ACCESS TOKEN MANAGER

    JSON Web Tokens

  7. Navegue até a guia Security e exporte o certificado. Extraia a chave pública do certificado para uso nas etapas seguintes.

  8. Navegue até a guia Instance Configuration na guia OAuth Server e Access Token Management | Create Access Token Management Instance e depois:

    • Atualize ISSUER CLAIM VALUE para o identificador único que faz referência a este servidor de autorização OAuth.

    • Atualize AUDIENCE CLAIM VALUE para a URL da sua conta Snowflake (por exemplo, https://<account_identifier>.snowflakecomputing.com). Para obter uma lista de formatos de URL possíveis, consulte Conexão com uma URL.

  9. Faça o download do complemento PingFederate OAuth Playground a partir da seção Developer Tools. Este cliente executa solicitações de API.

  10. Instale o OAuth Playground.

Criar uma integração de segurança no Snowflake

Esta etapa cria uma integração de segurança no Snowflake para garantir que o Snowflake possa se comunicar com o PingIdentity com segurança, validar os tokens do PingIdentity e fornecer o acesso apropriado aos dados do Snowflake aos usuários com base na função do usuário associada ao token OAuth.

Execute a seguinte instrução na interface da Web do Snowflake ou no SnowSQL.

Note que o valor para external_oauth_issuer deve ser o identificador exclusivo definido na Etapa 1.8. Por exemplo, se o valor do identificador único for 27f10cde-a964-4499-a88c-0c598883e5ad, substitua <id_exclusiva> por '27f10cde-a964-4499-a88c-0c598883e5ad'. O identificador único deve estar entre aspas simples (ou seja, verticais).

Escolha a integração de segurança que melhor atenda ao seu caso de uso e às suas necessidades de configuração. 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 para PingFederate

create or replace security integration external_oauth_pf_1
    type = external_oauth
    enabled = true
    external_oauth_type = ping_federate
    external_oauth_rsa_public_key = '<BASE64_PUBLIC_KEY>'
    external_oauth_issuer = '<unique_id>'
    external_oauth_token_user_mapping_claim = 'username'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';
Copy

Esta integração de segurança utiliza o parâmetro external_oauth_rsa_public_key. O Snowflake usa o valor da chave pública para verificar a assinatura em um token de acesso JWT.

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 Claim Value que você especificou durante a configuração do PingFederate.

create security integration external_oauth_pf_2
    type = external_oauth
    enabled=true
    external_oauth_type = ping_federate
    external_oauth_issuer = '<ISSUER>'
    external_oauth_rsa_public_key = '<BASE64_PUBLIC_KEY>'
    external_oauth_audience_list = ('<snowflake_account_url>')
    external_oauth_token_user_mapping_claim = 'username'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';
Copy

Esta integração de segurança utiliza o parâmetro external_oauth_rsa_public_key. O Snowflake usa o valor da chave pública para verificar a assinatura em um token de acesso JWT.

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 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 PingFederate como um servidor de autorização, você deve:

  1. Verificar se o usuário do teste existe no PingIdentity e se tem uma senha.

  2. Verifique se o usuário do teste existe no Snowflake com seu valor de atributo login_name definido para o <PING_USER_USERNAME>

  3. Conceder a função de analista a este usuário.

  4. Registrar um cliente OAuth.

  5. Permitir ao cliente OAuth fazer uma solicitação POST ao ponto de extremidade de token do PingFederate, 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.

    • Inclua quaisquer escopos necessários.

O comando de exemplo solicita o analista e isso considera que session:role:analyst foi definida em PingFederate > OAuth Server > Exclusive Scopes.

Use o seguinte comando para obter um token de acesso do Ping.

curl -k 'https://10.211.55.4:9031/as/token.oauth2' \
    --data 'client_id=<CLIENT_ID>&grant_type=password&username=<USERNAME>&password=<PASSWORD>&client_secret=<CLIENT_SECRET>&scope=session:role:analyst'
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.