Partilhar via

Processar a autenticação

Tipos de autenticação

Uma extensão pode suportar um ou mais tipos de Autenticação. Cada tipo de autenticação é um tipo diferente de credencial. A interface de autenticação apresentada aos utilizadores finais no Power Query é determinada pelo tipo(s) de credencial(ões) que uma extensão suporta.

A lista de tipos de autenticação suportados é definida como parte da definição de Tipo de Fonte de Dados de uma extensão. Cada valor de Autenticação é um registo com campos específicos. A tabela seguinte lista os campos esperados para cada tipo. Todos os campos são obrigatórios, salvo indicação em contrário.

Tipo de Autenticação Campo Description
Anónimo O tipo de autenticação Anónimo (também chamado Implicit) não tem campos.
OAuth StartLogin Função que fornece a URL e a informação de estado para iniciar um fluxo OAuth.

Vá à secção Implementar um Fluxo OAuth .
FinishLogin Função que extrai o access_token e outras propriedades relacionadas com o fluxo OAuth.
Atualizar (opcional) Função que recupera um novo token de acesso a partir de um token de atualização.
Sair (opcional) Função que invalida o token de acesso atual do utilizador.
Etiqueta (opcional) Um valor de texto que permite sobrepor o rótulo padrão deste AuthenticationKind.
Aad URI de Autorização text value ou função unária que devolve o endpoint de autorização Microsoft Entra ID (exemplo: "https://login.microsoftonline.com/common/oauth2/authorize").

Vá à secção de autenticação do ID Microsoft Entra .
Resource text valor ou função unária que devolve o valor do recurso Microsoft Entra ID para o seu serviço.
Scope (opcional)text valor ou função unária que devolve a lista de(s) âmbito(s) a solicitar como parte do fluxo de autenticação. Múltiplos valores de âmbito devem ser separados por um espaço. O valor do âmbito deve ser o nome do escopo, sem um URI de ID de aplicação (exemplo: Data.Read). Quando não fornecido, o user_impersonation âmbito é solicitado.
Nome de UtilizadorPalavra-passe Nome de UtilizadorEtiqueta (opcional) Um valor de texto para substituir o rótulo padrão da caixa de texto Nome de Utilizador na interface de credenciais.
PasswordLabel (opcional) Um valor de texto para substituir o rótulo padrão da caixa de texto Password na interface de credenciais.
Etiqueta (opcional) Um valor de texto que permite sobrepor o rótulo padrão deste AuthenticationKind.
Windows Nome de UtilizadorEtiqueta (opcional) Um valor de texto para substituir o rótulo padrão da caixa de texto Nome de Utilizador na interface de credenciais.
EtiquetaSenha (opcional) Um valor de texto para substituir o rótulo padrão da caixa de texto Password na interface de credenciais.
Etiqueta (opcional) Um valor de texto que permite sobrepor o rótulo padrão deste AuthenticationKind.
Key EtiquetaChave (opcional) Um valor de texto para substituir o rótulo padrão da caixa de texto API Key na interface de credenciais.
Etiqueta (opcional) Um valor de texto que permite sobrepor o rótulo padrão deste AuthenticationKind.

O exemplo seguinte mostra o registo de autenticação de um conector que suporta credenciais OAuth, Key, Windows, Basic (Nome de utilizador e palavra-passe) e Anonymous.

Example:

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

Aceder às credenciais atuais

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

As funções da fonte de dados M que foram ativadas para extensibilidade herdam automaticamente o âmbito de credencial da sua extensão. Na maioria dos casos, não é necessário aceder explicitamente às credenciais atuais, no entanto, existem exceções, tais como:

  • Passar a credencial num cabeçalho personalizado ou num parâmetro de cadeia de consulta, como quando está a usar o tipo de autenticação API Key.
  • Definir propriedades da cadeia de ligação para extensões ODBC ou ADO.NET.
  • Verificar propriedades personalizadas num token OAuth.
  • Usar as credenciais como parte de um fluxo OAuth v1.

A Extension.CurrentCredential função devolve um objeto de registo. Os campos que contém são específicos do tipo de autenticação. A tabela seguinte contém detalhes.

Campo Description Usado por
TipoDeAutenticação Contém o nome do tipo de autenticação atribuído a esta credencial (UsernamePassword, OAuth, e assim sucessivamente). Todos
Nome de utilizador Valor do nome de utilizador Nome de utilizadorPalavra-passe, Windows
Palavra-passe Valor da palavra-passe. Normalmente é usado com UsernamePassword, mas também está definido como Key. Chave, Nome de UtilizadorPalavra-passe, Windows
access_token Valor do token de acesso OAuth. OAuth
Propriedades Um registo contendo outras propriedades personalizadas para uma determinada credencial. Normalmente usado com o OAuth para armazenar outras propriedades (como o refresh_token) devolvidas com o access_token durante o fluxo de autenticação. OAuth
Key O valor da chave da API. Note que o valor-chave também está disponível no campo Palavra-passe. Por defeito, o motor mashup insere esta chave num cabeçalho de Autorização como se este valor fosse uma palavra-passe básica de autenticação (sem nome de utilizador). Se este tipo de comportamento não for o que pretende, deve especificar a opção ManualCredentials = true no registo de opções. Key
EncryptConnection Um valor lógico que determinava se deveria ser necessária uma ligação encriptada à fonte de dados. Este valor está disponível para todos os Tipos de Autenticação, mas só é definido se EncryptConnection for especificado na definição da Fonte de Dados . Todos

O exemplo de código seguinte acede à credencial atual para uma chave API e usa-a 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

Implementação de um fluxo OAuth

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

Observação

As extensões Power Query são avaliadas em aplicações a correr em máquinas clientes. Os Conectores de Dados não devem usar segredos confidenciais nos seus fluxos OAuth, pois os utilizadores podem inspecionar o tráfego de extensão ou de rede para descobrir o segredo. Consulte Proof Key for Code Exchange do OAuth Public Clients RFC (também conhecido como PKCE) para mais detalhes sobre como fornecer fluxos que não dependem de segredos partilhados. Uma implementação de exemplo deste fluxo pode ser encontrada no nosso site GitHub.

Existem 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. Também pode misturar e combinar tipos de assinatura na sua implementação. As chamadas de função são correspondências baseadas no número de parâmetros (e nos seus tipos). Os nomes dos parâmetros não são tidos em conta.

Consulte o exemplo do GitHub para mais detalhes.

Assinaturas OAuth originais

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

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

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

Logout = (accessToken) => ...;

Assinaturas OAuth avançadas

Notas sobre as assinaturas avançadas:

  • Todas as assinaturas aceitam um clientApplication valor de registo, que é reservado para uso futuro.
  • Todas as assinaturas aceitam um dataSourcePath (também referido como resourceUrl na maioria dos exemplos).
  • A Refresh função aceita um oldCredential parâmetro, que é o anterior record devolvido pela sua FinishLogin função (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. Utiliza o mesmo cliente Microsoft Entra ID que é usado pelos conectores Power Query integrados e que suportam a autenticação de conta organizacional. Mais informações podem ser encontradas no guia de início rápido Configuring Microsoft Entra para um conector personalizado.

Observação

Se implementar o seu próprio fluxo OAuth para o Microsoft Entra ID, os utilizadores que ativaram o Acesso Condicional para o seu tenant podem encontrar problemas ao atualizar usando o serviço Power BI. Isto não afetará a atualização baseada em gateway, mas afetaria um conector certificado que suporta a atualização do serviço Power BI. Os utilizadores podem enfrentar um problema decorrente do facto de o conector utilizar uma aplicação de cliente pública ao configurar credenciais baseadas na web através do serviço Power BI. O token de acesso gerado por este fluxo será, em última análise, utilizado num computador diferente (ou seja, o serviço Power BI num centro de dados Azure, não na rede da empresa) daquele usado para autenticar originalmente (ou seja, o computador do utilizador que configura as credenciais da fonte de dados na rede da empresa). O tipo incorporado Aad contorna este problema usando um cliente Microsoft Entra ID diferente ao configurar credenciais no serviço Power BI. Esta opção não estará disponível para conectores que usem o OAuth tipo de autenticação.

A maioria dos conectores precisa de fornecer valores para os campos AuthorizationUri e Resource. Ambos os campos podem ser text valores, ou uma única função argumental que devolve 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 de fornecer um Resource valor. Por defeito, o valor é igual ao caminho raiz do parâmetro Uri do conector. Se o recurso Microsoft Entra ID da fonte de dados for diferente do valor do domínio (por exemplo, usar um GUID), então é necessário fornecer um Resource valor.

Exemplos de tipos de autenticação AAD

No caso seguinte, a fonte de dados oferece apoio ao Microsoft Entra ID na nuvem global utilizando o inquilino comum (sem suporte a B2B do Azure). Solicitar o âmbito .default retorna um token com todos os âmbitos previamente autorizados para o ID da aplicação do cliente 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 seguinte, a fonte de dados suporta a descoberta de inquilinos com base no OpenID Connect (OIDC) ou protocolo semelhante. Esta capacidade permite ao conector determinar o endpoint correto do Microsoft Entra ID a usar com base num ou mais parâmetros no caminho da fonte de dados. Esta abordagem dinâmica de descoberta permite que o conector suporte 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 informações sobre outros tipos de autenticação não abordados neste artigo, como o single logon baseado em Kerberos, visite o artigo sobre funcionalidades adicionais de conectores para saber mais.

  • Last updated on