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 IU de autenticação apresentada aos utilizadores finais no Power Query é orientada pelo tipo de credencial(is) suportada(s) por uma extensão.

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 registro com campos específicos. A tabela a seguir lista os campos esperados para cada tipo. Todos os campos são obrigatórios, salvo indicação em contrário.

O exemplo a seguir mostra o registro de autenticação para um conector que suporta credenciais OAuth, chave, Windows, Basic (nome de usuário e senha) e anônimo.

Exemplo:

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

Acessando as credenciais atuais

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 credenciais da sua extensão. Na maioria dos casos, você não precisa acessar explicitamente as credenciais atuais, no entanto, há exceções, como:

• Passar a credencial em um cabeçalho personalizado ou parâmetro de cadeia de caracteres de consulta (como quando você está usando o tipo de autenticação de chave de API).
• Definição de propriedades de cadeia de conexão para extensões ODBC ou ADO.NET.
• Verificação de 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 contém são específicos do tipo de autenticação. A tabela a seguir contém detalhes.

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

Exemplo:

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 lógica personalizada para seu serviço. Para fazer isso, uma extensão fornece funções para StartLogin (retornar o URI de autorização para iniciar o fluxo OAuth) e FinishLogin (trocar o código de autorização por um token de acesso). Opcionalmente, as extensões também 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).

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. Você também pode misturar e combinar 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 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 registro, que é reservado para uso futuro.
• Todas as assinaturas aceitam a dataSourcePath (também referido como resourceUrl na maioria das amostras).
• A Refresh função aceita um oldCredential parâmetro, que é o anterior record retornado 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 os conectores internos do Power Query que suportam a autenticação de conta organizacional. Mais informações podem ser encontradas no guia de início rápido Configurando o Microsoft Entra para um conector personalizado.

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

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

AuthorizationUri = (dataSourcePath) => FunctionThatDeterminesAadEndpointFromDataSourcePath(dataSourcePath)

Resource = "77256ee0-fe79-11ea-adc1-0242ac120002"   // Microsoft Entra ID resource value for your service - Guid or URL

Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

Os conectores que usam um identificador baseado em Uri não precisam fornecer um Resource valor. Por padrão, 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, ele usa um GUID), um Resource valor precisará ser fornecido.

Exemplos de tipo de autenticação Aad

No caso a seguir, a fonte de dados dá suporte à nuvem global Microsoft Entra ID usando o locatário comum (sem suporte B2B do Azure). A solicitação do escopo .default retorna um token com todos os escopos previamente autorizados para a ID do aplicativo cliente do Power Query.

Authentication = [
    Aad = [
        AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
        Resource = "77256ee0-fe79-11ea-adc1-0242ac120002", // Entra Application ID URI or app guid
        Scope = ".default"
    ]
]

No caso a seguir, a fonte de dados oferece suporte à descoberta de locatário com base no OpenID Connect (OIDC) ou protocolo semelhante. Essa capacidade permite que o conector determine o ponto de extremidade correto do Microsoft Entra ID 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 ofereça 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 logon único baseado em Kerberos, visite o artigo sobre funcionalidade de conector adicional para saber mais.