Compartilhar via

Lidar com a autenticação

Tipos de autenticação

Uma extensão pode dar suporte a um ou mais tipos de Autenticação. Cada tipo de autenticação é um tipo diferente de credencial. A interface de autenticação do usuário é exibida para usuários finais no Power Query, determinada pelo tipo de credenciais às quais uma extensão suporta.

A lista de tipos de autenticação com suporte é definida como parte da definição do Tipo de Fonte de Dados de uma extensão. Cada valor de Autenticação é um registro com campos específicos. A tabela a seguir lista os campos esperados para cada tipo. Todos os campos são necessários, a menos que marcados de outra forma.

Tipo de autenticação Campo Description
Anônimo O tipo de autenticação Anônimo (também chamado Implicit) não tem campos.
OAuth IniciarSessão Função que fornece as informações de URL e de estado para iniciar um fluxo OAuth.

Vá para a seção Implementando um Fluxo OAuth .
FinishLogin Função que extrai o access_token e outras propriedades relacionadas ao fluxo OAuth.
Atualizar (opcional) Função que recupera um novo token de acesso de um token de atualização.
Logout (opcional) Função que invalida o token de acesso atual do usuário.
Etiqueta (opcional) Um valor de texto que permite substituir o rótulo padrão para este AuthenticationKind.
Aad URI de Autorização text valor ou função unária que retorna o endpoint de autorização do Microsoft Entra ID (exemplo: "https://login.microsoftonline.com/common/oauth2/authorize").

Vá para a seção autenticação da ID do Microsoft Entra .
Resource text valor ou função unária que retorna o valor do recurso da ID do Microsoft Entra para seu serviço.
Scope (opcional)text valor ou função unária que retorna a lista de escopos a serem solicitados como parte do fluxo de autenticação. Vários valores de escopo devem ser separados por um espaço. O valor do escopo deve ser o nome do escopo, sem um URI de ID do aplicativo (exemplo: Data.Read). Quando não fornecido, o escopo user_impersonation é solicitado.
NomeDeUsuárioSenha Etiqueta de Nome de Usuário (opcional) Um valor de texto para substituir o rótulo padrão da caixa de texto Nome de usuário na interface do usuário das credenciais.
EtiquetaSenha (opcional) Um valor de texto para substituir o rótulo padrão da caixa de texto Senha na interface do usuário das credenciais.
Etiqueta (opcional) Um valor de texto que permite substituir o rótulo padrão para este AuthenticationKind.
Windows Rótulo do Nome de Usuário (opcional) Um valor de texto para substituir o rótulo padrão da caixa de texto Nome de usuário na interface do usuário das credenciais.
EtiquetaSenha (opcional) Um valor de texto para substituir o rótulo padrão da caixa de texto Senha na interface do usuário das credenciais.
Etiqueta (opcional) Um valor de texto que permite substituir o rótulo padrão para este AuthenticationKind.
Key KeyLabel (opcional) Um valor de texto para substituir o rótulo padrão da caixa de texto chave de API na interface do usuário das credenciais.
Etiqueta (opcional) Um valor de texto que permite substituir o rótulo padrão para este AuthenticationKind.

O exemplo a seguir mostra o registro de Autenticação para um conector que dá suporte a credenciais OAuth, Key, Windows, Basic (Nome de usuário e senha) e Anônimo.

Example:

Authentication = [
    OAuth = [
        StartLogin = StartLogin,
        FinishLogin = FinishLogin,
        Refresh = Refresh,
        Logout = Logout
    ],
    Key = [],
    UsernamePassword = [],
    Windows = [],
    Anonymous = []
]

Acessando as credenciais correntes

As credenciais atuais podem ser recuperadas usando a Extension.CurrentCredential função.

As funções de fonte de dados M que foram habilitadas para extensibilidade herdam automaticamente o escopo de credencial da extensão. Na maioria dos casos, você não precisa acessar explicitamente as credenciais atuais, no entanto, há exceções, como:

  • Passando a credencial em um cabeçalho personalizado ou parâmetro de query string (como quando se está usando o tipo de autenticação por chave de API).
  • Definindo propriedades de cadeia de conexão para extensões ODBC ou ADO.NET.
  • Verificando propriedades personalizadas em um token OAuth.
  • Usando as credenciais como parte de um fluxo OAuth v1.

A Extension.CurrentCredential função retorna um objeto de registro. Os campos que ele contém são específicos do tipo de autenticação. A tabela a seguir contém detalhes.

Campo Description Usado Por
AuthenticationKind Contém o nome do tipo de autenticação atribuído a essa credencial (UsernamePassword, OAuth e assim por diante). All
Nome de usuário Valor de nome de usuário NomeDeUsuarioSenha, Windows
Senha Valor da senha. Normalmente usado com UsernamePassword, mas também é definido como Chave. Key, UsernamePassword, Windows
access_token Valor do token de acesso OAuth. OAuth
Propriedades Um registro que contém outras propriedades personalizadas para uma determinada credencial. Normalmente usado com o OAuth para armazenar outras propriedades (como a refresh_token) retornadas com o access_token durante o fluxo de autenticação. OAuth
Key O valor da chave de API. Observe que o valor da chave também está disponível no campo Senha. Por padrão, o mecanismo de mashup insere essa chave em um cabeçalho de autorização como se esse valor fosse uma senha de autenticação básica (sem nome de usuário). Se esse tipo de comportamento não for o que você deseja, especifique a opção ManualCredentials = true no registro de opções. Key
EncryptConnection Um valor lógico que determina se é necessário uma conexão criptografada com a fonte de dados. Esse valor está disponível para todos os Tipos de Autenticação, mas só será definido se EncryptConnection for especificado na definição da Fonte de Dados . All

O exemplo de código a seguir acessa a credencial atual para uma chave de API e a usa para preencher um cabeçalho personalizado (x-APIKey).

Example:

MyConnector.Raw = (_url as text) as binary =>
let
    apiKey = Extension.CurrentCredential()[Key],
    headers = [

        #"x-APIKey" = apiKey,
        Accept = "application/vnd.api+json",
        #"Content-Type" = "application/json"
    ],
    request = Web.Contents(_url, [ Headers = headers, ManualCredentials = true ])
in
    request

Implementando um fluxo OAuth

O tipo de autenticação OAuth permite que uma extensão implemente a lógica personalizada para seu serviço. Para fazer isso, uma extensão fornece funções para StartLogin (retornando o URI de autorização para iniciar o fluxo OAuth) e FinishLogin (trocando o código de autorização por um token de acesso). Opcionalmente, as extensões podem implementar Refresh (trocando um token de atualização por um novo token de acesso) e Logout (expirando os tokens de atualização e acesso atuais) também.

Observação

As extensões do Power Query são avaliadas em aplicativos em execução em computadores cliente. Os Conectores de Dados não devem usar segredos confidenciais em seus fluxos OAuth, pois os usuários podem inspecionar a extensão ou o tráfego de rede para saber o segredo. Acesse a Chave de Prova do Code Exchange por RFC de Clientes Públicos OAuth (também conhecido como PKCE) para obter mais detalhes sobre como fornecer fluxos que não dependem de segredos compartilhados. Uma implementação de exemplo desse fluxo pode ser encontrada em nosso site do GitHub.

Há dois conjuntos de assinaturas de função OAuth: a assinatura original que contém um número mínimo de parâmetros e uma assinatura avançada que aceita mais parâmetros. A maioria dos fluxos OAuth pode ser implementada usando as assinaturas originais. Você também pode combinar e variar tipos de assinatura em sua implementação. As chamadas de função são correspondências com base no número de parâmetros (e seus tipos). Os nomes dos parâmetros não são levados em consideração.

Vá para o exemplo do GitHub para obter mais detalhes.

Assinaturas originais do OAuth

StartLogin = (dataSourcePath, state, display) => ...;

FinishLogin = (context, callbackUri, state) => ...;

Refresh = (dataSourcePath, refreshToken) =>  ...;

Logout = (accessToken) => ...;

Assinaturas avançadas do OAuth

Observações sobre as assinaturas avançadas:

  • Todas as assinaturas aceitam um clientApplication valor de registro, que é reservado para uso futuro.
  • Todas as assinaturas aceitam um dataSourcePath (também conhecido como resourceUrl na maioria dos exemplos).
  • A Refresh função aceita um oldCredential parâmetro, que é o anterior record retornado pela função FinishLogin (ou chamada anterior para Refresh).
StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

FinishLogin = (clientApplication, dataSourcePath, context, callbackUri, state) => ...;

Refresh = (clientApplication, dataSourcePath, oldCredential) =>  ...;

Logout = (clientApplication, dataSourcePath, accessToken) => ...;

Autenticação do Microsoft Entra ID

O Aad tipo de autenticação é uma versão especializada do OAuth para Microsoft Entra ID. Ele usa o mesmo cliente Microsoft Entra ID que os conectores embutidos do Power Query que dão suporte à autenticação de contas organizacionais. Mais informações podem ser encontradas no guia de início rápido configurando o Microsoft Entra para um conector personalizado .

Observação

Se você implementar seu próprio fluxo OAuth para a ID do Microsoft Entra, os usuários que habilitaram o Acesso Condicional para seu locatário poderão encontrar problemas ao atualizar usando o serviço do Power BI. Isso não terá impacto na atualização baseada em gateway, mas afetará um conector certificado que suporta a atualização a partir do serviço Power BI. Os usuários podem encontrar um problema decorrente do conector usando um aplicativo cliente público ao configurar credenciais baseadas na Web por meio do serviço do Power BI. O token de acesso gerado por esse fluxo será usado em um computador diferente (ou seja, o serviço do Power BI em um data center do Azure, não na rede da empresa) do que aquele usado para autenticar originalmente (ou seja, o computador do usuário que configura as credenciais da fonte de dados na rede da empresa). O tipo interno Aad resolve esse problema usando um cliente de ID do Microsoft Entra diferente para configurar credenciais no serviço do Power BI. Essa opção não estará disponível para conectores que usam o OAuth tipo de autenticação.

A maioria dos conectores precisa fornecer valores para os campos AuthorizationUri e Resource. Ambos os campos podem ser text valores ou uma única função de argumento que retorna um text value.

AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize"

AuthorizationUri = (dataSourcePath) => FunctionThatDeterminesAadEndpointFromDataSourcePath(dataSourcePath)

Resource = "44445555-eeee-6666-ffff-7777aaaa8888"   // Microsoft Entra ID resource value for your service - Guid or URL

Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

Conectores que usam um identificador baseado em Uri não precisam fornecer valor algum. Por padrão, o valor é igual ao caminho raiz do parâmetro Uri do conector. Se o recurso de ID do Microsoft Entra da fonte de dados for diferente do valor de domínio (por exemplo, ele usa um GUID), um Resource valor precisará ser fornecido.

Exemplos de tipo de autenticação do AAD

No caso a seguir, a fonte de dados dá suporte ao Microsoft Entra ID global na nuvem usando o tenant comum (sem suporte para Azure B2B). Solicitar o escopo .default retorna um token com todos os escopos autorizados anteriormente para a ID de aplicativo cliente do Power Query.

Authentication = [
    Aad = [
        AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
        Resource = "44445555-eeee-6666-ffff-7777aaaa8888", // Entra Application ID URI or app guid
        Scope = ".default"
    ]
]

No caso a seguir, a fonte de dados dá suporte à descoberta de locatário com base no OIDC (OpenID Connect) ou em um protocolo semelhante. Essa capacidade permite que o conector determine o ponto de extremidade correto da ID do Microsoft Entra a ser usado com base em um ou mais parâmetros no caminho da fonte de dados. Essa abordagem de descoberta dinâmica permite que o conector dê suporte ao Azure B2B.


// Implement this function to retrieve or calculate the service URL based on the data source path parameters
GetServiceRootFromDataSourcePath = (dataSourcePath) as text => ...;

GetAuthorizationUrlFromWwwAuthenticate = (url as text) as text =>
    let
        // Sending an unauthenticated request to the service returns
        // a 302 status with WWW-Authenticate header in the response. The value will
        // contain the correct authorization_uri.
        // 
        // Example:
        // Bearer authorization_uri="https://login.microsoftonline.com/{tenant_guid}/oauth2/authorize"
        responseCodes = {302, 401},
        endpointResponse = Web.Contents(url, [
            ManualCredentials = true,
            ManualStatusHandling = responseCodes
        ])
    in
        if (List.Contains(responseCodes, Value.Metadata(endpointResponse)[Response.Status]?)) then
            let
                headers = Record.FieldOrDefault(Value.Metadata(endpointResponse), "Headers", []),
                wwwAuthenticate = Record.FieldOrDefault(headers, "WWW-Authenticate", ""),
                split = Text.Split(Text.Trim(wwwAuthenticate), " "),
                authorizationUri = List.First(List.Select(split, each Text.Contains(_, "authorization_uri=")), null)
            in
                if (authorizationUri <> null) then
                    // Trim and replace the double quotes inserted before the url
                    Text.Replace(Text.Trim(Text.Trim(Text.AfterDelimiter(authorizationUri, "=")), ","), """", "")
                else
                    error Error.Record("DataSource.Error", "Unexpected WWW-Authenticate header format or value during authentication.", [
                        #"WWW-Authenticate" = wwwAuthenticate
                    ])
        else
            error Error.Unexpected("Unexpected response from server during authentication.");

<... snip ...>

Authentication = [
    Aad = [
        AuthorizationUri = (dataSourcePath) =>
            GetAuthorizationUrlFromWwwAuthenticate(
                GetServiceRootFromDataSourcePath(dataSourcePath)
            ),
        Resource = "https://myAadResourceValue.com", // Microsoft Entra ID resource value for your service - Guid or URL
        Scope = ".default"
    ]
]

Outros tipos de autenticação

Para obter informações sobre outros tipos de autenticação não abordados neste artigo, como o logon único baseado em Kerberos, visite o artigo sobre funcionalidade adicional do conector para saber mais.

  • Last updated on