Configuração do Microsoft Azure AD para OAuth externo

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

Neste tópico:

Procedimento de configuração

As quatro etapas seguintes consideram que seu ambiente não tem nada configurado relacionado aos servidores de autorização Azure AD 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 e cliente Azure AD configurados, não é necessário completar todas as etapas abaixo. Em vez disso, ignore as três 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 servidor de autorização e cliente Azure AD OAuth configurados, complete todas as quatro etapas seguintes.

Importante

Estas etapas neste tópico são um exemplo representativo sobre como configurar o Azure AD para External OAuth.

Você pode configurar o Azure AD para qualquer estado desejado e usar qualquer fluxo OAuth desejado desde que você possa obter as informações necessárias para a integração da 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.

As etapas 1-3 são derivadas da documentação Azure AD sobre OAuth 2.0 e Autenticação. Para mais informações sobre como a Microsoft define seus termos, sua interface de usuário e opções relacionadas a OAuth 2.0 e Autenticação consulte os seguintes guias do Azure AD:

Determinar o fluxo OAuth no Azure AD

O Azure AD suporta dois fluxos OAuth diferentes, nos quais um cliente OAuth pode obter um token de acesso.

  1. O servidor de autorização pode conceder ao cliente OAuth um token de acesso em nome do usuário.

  2. O servidor de autorização pode conceder ao cliente OAuth um token de acesso para o próprio cliente OAuth.

No primeiro fluxo, a identidade no token de acesso faz referência ao usuário. No segundo fluxo, a identidade no token de acesso faz referência ao cliente OAuth.

O Microsoft Azure AD não permite o mesmo formato de função para cada um desses dois fluxos OAuth. O formato da função a ser usada depende do fluxo OAuth em uso. Depois de determinar qual fluxo OAuth utilizar:

Configurar o recurso OAuth no Azure AD

  1. Navegue até o Microsoft Azure Portal e autentique.

  2. Navegue até o Azure Active Directory.

  3. Clique em App Registrations.

  4. Clique em New Registration.

  5. Digite Snowflake OAuth Resource, ou valor similar, como o Name.

  6. Verifique se Supported account types está definido como Single Tenant.

  7. Clique em Register.

  8. Clique em Expose an API.

  9. Clique no link Set ao lado de Application ID URI para definir o Application ID URI.

    Importante

    O Application ID URI deve ser único dentro do diretório de sua organização, tal como https://your.company.com/4d2a8c2b-a5f4-4b86-93ca-294185f45f2e. Este valor será referido como <SNOWFLAKE_APPLICATION_ID_URI> nas etapas de configuração subsequentes.

    Para ajuda para obter o ID URI de seu aplicativo, contate o administrador interno do Microsoft Azure AD.

    Se o ID URI do aplicativo não for usado, então é necessário criar uma integração de segurança com os públicos que usam a conta Snowflake URL (ou seja, <identificador_de_conta>.snowflakecomputing.com). Para obter mais informações, consulte:

  10. Para adicionar uma função do Snowflake como um escopo OAuth para fluxos OAuth onde o cliente programático age em nome de um usuário, clique em Add a scope para adicionar um escopo representando a função do Snowflake.

    • Insira o escopo usando o nome da função do Snowflake com o prefixo session:scope:. Por exemplo, para a função de analista do Snowflake, digite session:scope:analyst.

    • Selecione quem pode consentir.

    • Digite um display name para o escopo (por exemplo: Administrador de conta).

    • Digite uma description para o escopo (por exemplo: Pode administrar a conta Snowflake).

    • Clique em Add Scope.

  11. Para adicionar uma função do Snowflake como uma função para fluxos OAuth onde o cliente programático solicita um token de acesso para si mesmo:

    • Clique em Manifest.

    • Localize o elemento appRoles.

    • Insira uma App Role com as seguintes configurações.

      Configuração

      Descrição

      allowedMemberTypes

      Aplicativo.

      descrição

      Uma descrição da função.

      displayName

      Um nome amigável para os usuários verem.

      id

      Uma ID única. Você pode usar a função [System.Guid]::NewGuid() de PowerShell para gerar uma ID única, se necessário.

      isEnabled

      Defina como true.

      lang

      O idioma. Defina como null.

      origin

      Defina como Application.

      valor

      Defina o nome da função do Snowflake com o prefixo session:role:. . Para a função de analista, insira session:role:analyst.

      O App Role se manifesta da seguinte forma.

      "appRoles":[
          {
              "allowedMemberTypes": [ "Application" ],
              "description": "Account Administrator.",
              "displayName": "Account Admin",
              "id": "3ea51f40-2ad7-4e79-aa18-12c45156dc6a",
              "isEnabled": true,
              "lang": null,
              "origin": "Application",
              "value": "session:role:analyst"
          }
      ]
      
      Copy
  12. Clique em Save.

Criar um cliente OAuth no Azure AD

  1. Navegue até o Microsoft Azure Portal e autentique.

  2. Navegue até o Azure Active Directory.

  3. Clique em App Registrations.

  4. Clique em New Registration.

  5. Digite um nome para o cliente, como Snowflake OAuth Client.

  6. Verifique se os tipos de conta com suporte estão definidos como locatário único.

  7. Clique em Register.

  8. Na seção Overview, copie o ClientID do campo Application (client) ID. Isto será conhecido como o <OAUTH_CLIENT_ID> nas seguintes etapas.

  9. Clique em Certificates & secrets e depois em New client secret.

  10. Adicione uma descrição do segredo.

  11. Selecione never expire. Para fins de teste, selecione segredos que nunca expiram.

  12. Clique em Add. Copie o segredo. Isto será conhecido como o <OAUTH_CLIENT_SECRET> nas seguintes etapas.

  13. Para clientes programáticos que solicitarão um token de acesso em nome de um usuário, configure as permissões delegadas para aplicativos da seguinte forma.

    • Clique em API Permissions.

    • Clique em Add Permission.

    • Clique em My APIs.

    • Clique no Snowflake OAuth Resource que você criou em Configurar o recurso OAuth no Azure AD.

    • Clique na caixa Delegated Permissions.

    • Verifique a permissão relacionada aos escopos definidos no aplicativo que você deseja conceder a este cliente.

    • Clique em Add Permissions.

    • Clique no botão Grant Admin Consent para conceder as permissões ao cliente. Observe que, para fins de teste, as permissões são configuradas desta forma. Entretanto, em um ambiente de produção, a concessão de permissões desta forma não é aconselhável.

    • Clique em Yes.

  14. Para clientes programáticos que irão solicitar um token de acesso para si mesmos, configure API permissions for Applications da seguinte forma.

    • Clique em API Permissions.

    • Clique em Add Permission.

    • Clique em My APIs.

    • Clique no Snowflake OAuth Resource que você criou em Configurar o recurso OAuth no Azure AD.

    • Clique em Application Permissions.

    • Verifique a Permission relacionada às funções definidas manualmente no Manifest do aplicativo que você deseja conceder a este cliente.

    • Clique em Add Permissions.

    • Clique no botão Grant Admin Consent para conceder as permissões ao cliente. Note que, para fins de teste, as permissões são configuradas desta forma. Entretanto, em um ambiente de produção, a concessão de permissões desta forma não é aconselhável.

    • Clique em Yes.

Coletar informações do Azure AD para o Snowflake

  1. Navegue até o Microsoft Azure Portal e autentique.

  2. Navegue até o Azure Active Directory.

  3. Clique em App Registrations.

  4. Clique no Snowflake OAuth Resource que você criou em Configurar o recurso OAuth no Azure AD.

  5. Clique em Endpoints na interface Overview.

  6. No lado direito, copie o OAuth 2.0 token endpoint (v2) e anote as URLs para OpenID Connect metadata e Federation Connect metadata.

    • O OAuth 2.0 token endpoint (v2) será conhecido como o <AZURE_AD_OAUTH_TOKEN_ENDPOINT> nas seguintes etapas de configuração. O ponto de extremidade deve ser semelhante a https://login.microsoftonline.com/90288a9b-97df-4c6d-b025-95713f21cef9/oauth2/v2.0/token.

    • Para OpenID Connect metadata, abra em uma nova janela do navegador.

      • Localize o parâmetro "jwks_uri" e copie seu valor.

      • Este valor de parâmetro será conhecido como o <AZURE_AD_JWS_KEY_ENDPOINT> nas etapas de configuração a seguir. O ponto de extremidade deve ser semelhante a https://login.microsoftonline.com/90288a9b-97df-4c6d-b025-95713f21cef9/discovery/v2.0/keys.

    • Para o Federation metadata document, abra a URL em uma nova janela do navegador.

      • Localize o parâmetro "entityID" no XML Root Element e copie seu valor.

      • Este valor de parâmetro será conhecido como o <AZURE_AD_ISSUER> nas etapas de configuração a seguir. O valor entityID deve ser semelhante a https://sts.windows.net/90288a9b-97df-4c6d-b025-95713f21cef9/.

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

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

Escolha a integração de segurança que melhor atenda ao seu caso de uso e às suas necessidades de configuração. Se sua integração for baseada apenas na configuração anterior, utilize a primeira integração de segurança. Para obter mais informações, consulte CREATESECURITYINTEGRATION.

Importante

Se você estiver tentando criar uma integração de segurança para Microsoft Power BI, siga as instruções de configuração em SSO do Power BI no Snowflake.

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.

Verifique se todos os valores são exatamente iguais. Por exemplo, se o valor do Emissor não terminar com uma barra invertida e a integração da segurança for criada com um caractere de barra invertida no final da URL, uma mensagem de erro ocorrerá. Seria então necessário descartar o objeto de integração de segurança usando DROP INTEGRATION e então criar o objeto novamente com o valor correto do Emissor usando CREATE SECURITY INTEGRATION.

Criar uma integração de segurança para o Azure AD

create security integration external_oauth_azure_1
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = '<AZURE_AD_JWS_KEY_ENDPOINT>'
    external_oauth_token_user_mapping_claim = 'upn'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';
Copy

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 Application ID URI que você especificou durante a configuração do Azure AD.

create security integration external_oauth_azure_2
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = '<AZURE_AD_JWS_KEY_ENDPOINT>'
    external_oauth_audience_list = ('<SNOWFLAKE_APPLICATION_ID_URI>')
    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 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 Azure AD como um servidor de autorização, você deve:

  1. Verifique se o usuário do teste existe no Azure AD 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 <AZURE_AD_USER_USERNAME>

  3. Conceda a função SYSADMIN a este usuário.

  4. Registrar um cliente OAuth.

  5. Permita que o cliente OAuth faça uma solicitação POST ao ponto de extremidade de token do Azure AD como a seguir:

    • 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

Aqui está um exemplo para obter um token de acesso usando cURL. Observe que o escopo deve ser totalmente qualificado, incluindo o Azure App URI (por exemplo, scope=https://example.com/wergheroifvj25/session:role-any).

curl -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --data-urlencode "client_id=<OAUTH_CLIENT_ID>" \
  --data-urlencode "client_secret=<OAUTH_CLIENT_SECRET>" \
  --data-urlencode "username=<AZURE_AD_USER>" \
  --data-urlencode "password=<AZURE_AD_USER_PASSWORD>" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=<AZURE_APP_URI+AZURE_APP_SCOPE>" \
  '<AZURE_AD_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.