SSO do Power BI no Snowflake

Este tópico descreve como usar o Microsoft Power BI para instanciar uma sessão do Snowflake e acessar o Snowflake usando o login único (SSO).

Neste tópico:

Visão geral

O Snowflake permite aos usuários do Microsoft Power BI conectarem-se ao Snowflake usando as credenciais do provedor de identidade e uma implementação OAuth 2.0 para fornecer uma experiência SSO de acesso aos dados do Snowflake.

Esse recurso elimina a necessidade de implementações do Power BI Gateway no local, pois o serviço Power BI usa um driver Snowflake incorporado para se conectar ao Snowflake.

Fluxo de trabalho geral

O diagrama a seguir resume o fluxo de autorização para instanciar uma sessão do Snowflake a partir do Power BI:

Visão geral do fluxo de trabalho pbi sso
  1. O usuário faz login no serviço Power BI usando o Microsoft Azure Active Directory (Azure AD).

  2. Opcionalmente, o Azure AD pode verificar o usuário por meio de um IdP via SAML. Atualmente, a Microsoft oferece suporte apenas ao Azure AD como IdP para Power BI SSO.

  3. Quando o usuário se conecta ao Snowflake, o serviço Power BI pede ao Azure AD que lhe dê um token para o Snowflake.

  4. O serviço Power BI usa o driver Snowflake incorporado para enviar o token do Azure AD ao Snowflake como parte da cadeia de conexão.

  5. O Snowflake valida o token, extrai o nome de usuário do token, mapeia-o para o usuário Snowflake e cria uma sessão Snowflake para o serviço Power BI usando a função padrão do usuário.

Pré-requisitos

Para sua conta Snowflake, verifique o seguinte antes de usar o recurso SSO do Power BI:

  • No Snowflake, se você estiver usando Controle do tráfego de rede com políticas de rede, você deve permitir o intervalo de IP do Microsoft Azure que inclui a região do Azure onde sua conta no Snowflake está hospedada e quaisquer regiões Azure adicionais, conforme necessário.

    Importante

    Para criar uma política de rede específica para o Power BI para a região Azure onde sua conta Snowflake no Azure está localizada, pesquise o download do JSON da Microsoft para sua região.

    Por exemplo, se sua conta Snowflake no Azure está localizada na região Canada Central, pesquisa o download do JSON para PowerBI.CanadaCentral. Selecione os intervalos de endereços IP na lista addressPrefixes. Use estes intervalos de endereços IP para criar ou atualizar uma política de rede no Snowflake.

    Se a lista addressPrefixes estiver vazia, entre em contato com a Microsoft para solicitar uma atualização.

    Se você estiver usando vários serviços Microsoft Azure (por exemplo, Power BI, SCIM), contate seu administrador Azure para verificar os intervalos de endereços IP corretos para garantir que a política de rede do Snowflake contenha os intervalos de endereços IP corretos para permitir que os usuários acessem o Snowflake.

  • O atributo login_name, name ou o atributo email para o usuário no Snowflake deve ser mapeado para o atributo Azure AD upn. Se o atributo login_name não estiver definido, então o processo usa como padrão o atributo name.

Considerações

Com o Power BI Gateway:

Conectividade privada ao serviço Snowflake é suportada. Se for necessário utilizar algum destes dois serviços para se conectar ao Snowflake, utilize o gateway no local para se conectar.

Sem o Power BI Gateway:

Conectividade privada ao serviço Snowflake não é suportada. Para o Power BI Service e o Power BI Desktop, crie uma política de rede para permitir os intervalos de endereços IP públicos do Azure Active Directory. Observe que as políticas de rede têm um limite de 100.000 caracteres para os endereços IP permitidos.

Tokens e chaves:

O Snowflake tenta verificar o Azure Active Directory através do valor de URL na propriedade external_oauth_jws_keys_url (mostrada abaixo) ou através dos endereços IP permitidos na política de rede, se a política de rede existir. A Microsoft atualiza seus tokens e chaves a cada 24 horas. Para obter mais informações sobre as atualizações da Microsoft, consulte Visão geral de tokens no Azure Active Directory B2C.

Definição de funções permitidas:

Por padrão, as funções do sistema ACCOUNTADMIN, ORGADMIN e SECURITYADMIN não podem usar o Microsoft Power BI para instanciar uma sessão do Snowflake. Se for necessário utilizar estas funções altamente privilegiadas, atualize o parâmetro de integração de segurança EXTERNAL_OAUTH_ALLOWED_ROLES para especificar estas funções. Tenha cuidado antes de especificar as funções do sistema ACCOUNTADMIN, ORGADMIN e SECURITYADMIN no parâmetro de integração de segurança EXTERNAL_OAUTH_ALLOWED_ROLES.

Para obter mais informações, consulte CREATE SECURITY INTEGRATION e ALTER SECURITY INTEGRATION.

Introdução

Esta seção explica como criar uma integração de segurança Power BI no Snowflake e como acessar o Snowflake através do Power BI.

Criação de uma integração de segurança do Power BI

Nota

Esta etapa não é necessária se você estiver usando o serviço Power BI gateway para Power BI para se conectar ao Snowflake ou estiver usando seu nome de usuário e senha do Snowflake para autenticação.

Para usar o Power BI para acessar os dados do Snowflake pelo SSO, é necessário criar uma integração de segurança para o Power BI usando CREATESECURITY INTEGRATION, como mostrado abaixo.

A integração de segurança deve ter o valor correto para o parâmetro external_oauth_issuer. Parte deste valor é mapeada para seu locatário Azure AD. Você pode encontrar este valor na seção About de seu locatário do Power BI.

Se sua organização tem uma implantação avançada do serviço Power BI, então verifique com seu administrador Azure AD para obter o valor correto do locatário do Azure AD para usar na construção da URL do emissor.

Por exemplo, se a ID de seu locatário do Azure AD for a828b821-f44f-4698-85b2-3c6749302698, então construa o valor AZURE_AD_ISSUER semelhante a https://sts.windows.net/a828b821-f44f-4698-85b2-3c6749302698/. É importante incluir a barra (ou seja, /) no final do valor.

Depois de construir o valor para AZURE_AD_ISSUER, execute o comando CREATESECURITYINTEGRATION.

Se sua conta Snowflake ou serviço do Microsoft Power BI estiver em uma região da nuvem do Microsoft Azure Government, defina o valor da propriedade external_oauth_audience_list como https://analysis.usgovcloudapi.net/powerbi/connector/Snowflake.

Integração de segurança para Microsoft Power BI

create security integration powerbi
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = 'https://login.windows.net/common/discovery/keys'
    external_oauth_audience_list = ('https://analysis.windows.net/powerbi/connector/Snowflake', 'https://analysis.windows.net/powerbi/connector/snowflake')
    external_oauth_token_user_mapping_claim = 'upn'
    external_oauth_snowflake_user_mapping_attribute = 'login_name'
Copy

Integração de segurança do Microsoft Azure Government para Microsoft Power BI

create security integration powerbi_mag
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = 'https://login.windows.net/common/discovery/keys'
    external_oauth_audience_list = ('https://analysis.usgovcloudapi.net/powerbi/connector/Snowflake', 'https://analysis.usgovcloudapi.net/powerbi/connector/snowflake')
    external_oauth_token_user_mapping_claim = 'upn'
    external_oauth_snowflake_user_mapping_attribute = 'login_name'
Copy

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.

Os valores de lista especificados para a propriedade EXTERNAL_OAUTH_AUDIENCE_LIST são URLs com nome Snowflake maiúsculo e minúsculo. Inclua URLs nesta lista para garantir que seu cliente possa se conectar ao Snowflake com base nos valores que a Microsoft pode esperar para formar uma conexão.

Verifique se todos os valores de parâmetro são exatamente iguais. Por exemplo, se o valor de URL <AZURE_AD_ISSUER> 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 DROPINTEGRATION) e então criar o objeto novamente com o valor correto de URL (usando CREATE SECURITY INTEGRATION).

Em seu ambiente, se o UPN valor do atributo do usuário corresponde ao campo de e-mail do usuário em vez do login_name no Snowflake, então substitua login_name por email_address. Por exemplo:

create security integration powerbi
    type = external_oauth
    ...
    external_oauth_snowflake_user_mapping_attribute = 'email_address';
Copy

Uso do SSO do Power BI com usuários convidados B2B

Para permitir que usuários convidados do Azure AD business to business (isto é, B2B) acessem o Snowflake usando o SSO do Microsoft Power BI, defina o valor da propriedade EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM como 'unique_name'. Por exemplo:

create security integration powerbi
  type = external_oauth
  enabled = true
  external_oauth_type = azure
  external_oauth_issuer = '<AZURE_AD_ISSUER>'
  external_oauth_jws_keys_url = 'https://login.windows.net/common/discovery/keys'
  external_oauth_audience_list = ('https://analysis.windows.net/powerbi/connector/Snowflake', 'https://analysis.windows.net/powerbi/connector/snowflake')
  external_oauth_token_user_mapping_claim = 'unique_name'
  external_oauth_snowflake_user_mapping_attribute = 'login_name';
Copy

Para obter mais informações, consulte Explicação do usuário B2B.

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 de funções secundárias com o SSO do Power BI no Snowflake

O escopo desejado para a função principal é passado no token externo. Essa função é uma função específica que foi concedida ao usuário (session:role:<role_name>).

Por padrão, as funções secundárias padrão para um usuário (ou seja, a propriedade de usuário DEFAULT_SECONDARY_ROLES) não são ativadas 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 OAuth externo, complete esta etapa:

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

Uso do Redirecionamento do cliente com SSO do Power BI no Snowflake

O Snowflake suporta o uso do Redirecionamento do cliente com SSO do Power BI no Snowflake.

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

Uso da replicação com Power BI SSO

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.

Conexão ao Snowflake a partir do Power BI

Para mais detalhes sobre como se conectar ao Snowflake a partir do Power BI, consulte a documentação do Power BI.

Uso de políticas de rede com External OAuth

Atualmente, políticas de rede não podem ser adicionadas a uma integração de segurança External OAuth, o que significa que você não pode definir uma política de rede que se aplique apenas à integração do Power BI. Entretanto, você ainda pode implementar políticas de rede que se aplicam amplamente a toda a conta Snowflake. Para obter mais informações sobre o intervalo IP da Microsoft que deve ser incluído na política de rede, consulte a seção Pré-requisitos (neste tópico).

Solução de problemas

  • Retomada do warehouse. Se um determinado usuário tentar utilizar um warehouse suspenso, o Microsoft Power BI exibe uma mensagem de erro que não está descrita em Mensagens de erro. Verifique e, se necessário, configure o warehouse para retomar automaticamente para resolver a mensagem de erro. Para obter mais informações, consulte Início ou retomada de um warehouse.

  • Ao tentar conectar o Power BI ao Snowflake, podem ocorrer erros. Dependendo da mensagem de erro, pode ser necessário solucionar problemas junto à Microsoft, Snowflake ou ambas.

    • Mensagens de erro descrevem mensagens comuns que o Snowflake pode retornar que são exibidas no Power BI.

    • O histórico de login descreve como usar o Snowflake para verificar se ou quando um usuário acessou o Snowflake pela última vez.

Mensagens de erro

A tabela a seguir descreve mensagens de erro que o Snowflake retorna enquanto um usuário se autentica no Power BI:

Comportamento

Mensagem de erro

Ação de solução de problemas

Valor inválido de token de acesso ou público.

Failed to update data source credentials: ODBC:ERROR [28000] Invalid OAuth access token. [<número>].

Verifique se o parâmetro external_oauth_issuer contém o valor correto. . No Azure AD, verifique se o token de acesso é atual.

Usuário AAD não encontrado na conta Snowflake.

Failed to update data source credentials: ODBC:ERROR [28000] Incorrect username or password was specified.

Verifique se o usuário existe no Snowflake (ou se o valor do atributo name ou login_name coincide com o valor de UPN do usuário no Azure AD). Se você estiver adicionando um usuário, verifique se o valor UPN ainda não existe no Azure AD.

Usuário do Snowflake presente, mas desabilitado.

Failed to update data source credentials: ODBC:ERROR [28000] User access disabled. Contate seu administrador de sistema local.

No Snowflake, execute desc user <nome de usuário> para verificar se o atributo disabled está definido para true. Se você quiser que este usuário seja permitido, execute alter user <nome de usuário> set disabled = true;. Tente acessar novamente o Snowflake a partir do Power BI.

O Snowflake recebe um token AAD expirado do Power BI.

Failed to update data source credentials: ODBC:ERROR [28000] OAuth access token expired. [<número>].

Entre em contato com o suporte Snowflake.

Integração de segurança não criada ou desabilitada na conta Snowflake.

Failed to update data source credentials: ODBC:ERROR [28000] OAuth Authz Server Integration is not enabled.

Execute desc <nome_integração_segurança> para verificar ou recriar a integração de segurança.

A função padrão não está definida para o usuário.

Failed to update data source credentials: ODBC: ERROR [28000] No default role has been assigned to the user, contact a local system administrator to assign a default role and retry.

Defina a função padrão para o usuário.

A função padrão para o usuário não foi concedida ao usuário.

Test failed because of 250001 (08001): Failed to connect to DB: <host>. A função padrão configurada para o usuário “<ROLE>” não foi concedida a este usuário. Contate seu administrador de sistema local, ou tente fazer o login usando um cliente CLI com uma cadeia de conexão selecionando outra função, por exemplo PUBLIC.

Verifique a função padrão para o usuário e conceda a função a ele.

Histórico de login

Se um usuário for capaz de acessar o Power BI mas não de instanciar uma sessão do Snowflake, você pode determinar quando o usuário acessou o Snowflake pela última vez executando os seguintes comandos, usando qualquer conector com suporte ou a interface da Web para o Snowflake. Observe que somente autenticações bem sucedidas são registradas.

use role accountadmin;
select *
from table(information_schema.login_history(dateadd('hours',-1,current_timestamp()),current_timestamp()))
order by event_timestamp;
Copy

Para cada resultado, avalie as colunas USER_NAME e FIRST_AUTHENTICATION_FACTOR.

  • O valor USER_NAME deve estar alinhado com os mapeamentos de atributos descritos na seção Pré-requisitos.

  • O FIRST_AUTHENTICATION_FACTOR deve ser definido como OAUTH_ACCESS_TOKEN.