Processar a autenticação

Artigo
12/04/2024

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.

Tipo de autenticação	Campo	Descrição
Anónimo		O tipo de autenticação Anonymous (também chamado `Implicit`) não tem nenhum campo.
OAuth	StartLogin	Função que fornece as informações de URL e 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	(facultativo) Função que recupera um novo token de acesso de um token de atualização.
	Fim de Sessão	(facultativo) Função que invalida o token de acesso atual do usuário.
	Etiqueta	(facultativo) Um valor de texto que permite substituir o rótulo padrão para este AuthenticationKind.
Aad	AuthorizationUri	`text` value ou função unária que retorna o ponto de extremidade de autorização do Microsoft Entra ID (exemplo: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Vá para a seção de autenticação do Microsoft Entra ID.
	Recurso	`text` value ou função unária que retorna o valor do recurso Microsoft Entra ID para seu serviço.
	Âmbito	(facultativo) `text` value ou função unária que retorna a lista de escopos(es) 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 `user_impersonation` escopo é solicitado.
UsernamePassword	UsernameLabel	(facultativo) Um valor de texto para substituir o rótulo padrão da caixa de texto Nome de usuário na interface do usuário de credenciais.
	SenhaLabel	(facultativo) Um valor de texto para substituir o rótulo padrão da caixa de texto Senha na interface do usuário de credenciais.
	Etiqueta	(facultativo) Um valor de texto que permite substituir o rótulo padrão para este AuthenticationKind.
Windows	UsernameLabel	(facultativo) Um valor de texto para substituir o rótulo padrão da caixa de texto Nome de usuário na interface do usuário de credenciais.
	SenhaLabel	(facultativo) Um valor de texto para substituir o rótulo padrão da caixa de texto Senha na interface do usuário de credenciais.
	Etiqueta	(facultativo) Um valor de texto que permite substituir o rótulo padrão para este AuthenticationKind.
Chave	Rótulo de chave	(facultativo) Um valor de texto para substituir o rótulo padrão da caixa de texto Chave de API na interface do usuário de credenciais.
	Etiqueta	(facultativo) 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 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.

Campo	Descrição	Usado por
AuthenticationKind	Contém o nome do tipo de autenticação atribuído a essa credencial (UsernamePassword, OAuth e assim por diante).	Todos
Username	Valor do nome de usuário	UsernamePassword, Windows
Palavra-passe	Valor da senha. Normalmente usado com UsernamePassword, mas também é definido para Key.	Chave, 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 OAuth para armazenar outras propriedades (como o refresh_token) retornadas com o access_token durante o fluxo de autenticação.	OAuth
Chave	O valor da chave da 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 desejado, especifique a opção ManualCredentials = true no registro options.	Chave
EncryptConnection	Um valor lógico que determinou se deve ser necessária uma conexão criptografada com a fonte de dados. Esse valor está disponível para todos os tipos de autenticação, mas só é definido se EncryptConnection for especificado na definição de fonte de dados.	Todos

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

Nota

As extensões do Power Query são avaliadas em aplicações executadas em máquinas 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 aprender o segredo. Vá para Proof Key for Code Exchange by OAuth Public Clients RFC (também conhecido como PKCE) para obter mais detalhes sobre como fornecer fluxos que não dependem de segredos compartilhados. Um exemplo de implementação desse fluxo pode ser encontrado em nosso site do 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. 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.

Nota

Se você implementar seu próprio fluxo OAuth para o Microsoft Entra ID, 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 afetará a atualização baseada em gateway, mas afetará um conector certificado que ofereça suporte à atualização do serviço do Power BI. Os usuários podem ter 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) daquele 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 contorna esse problema usando um cliente de ID do Microsoft Entra diferente ao 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 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 = "44445555-eeee-6666-ffff-7777aaaa8888"   // 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 = "44445555-eeee-6666-ffff-7777aaaa8888", // 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.

Partilhar via