Guia de início rápido: configurando o Microsoft Entra para um conector personalizado

Artigo
03/19/2024

Este guia descreve os passos para configurar uma aplicação Microsoft Entra para utilização com um conector personalizado do Power Query. Recomendamos que os desenvolvedores de conectores revisem os conceitos da plataforma de identidade da Microsoft antes de continuar.

Como o termo do aplicativo é usado em vários contextos na plataforma Microsoft Entra, este guia usa os seguintes termos para distinguir entre IDs de aplicativo de conector e fonte de dados:

Aplicativo cliente: as IDs de cliente do Microsoft Entra usadas pelo conector do Power Query.
Aplicativo de recurso: O registro do aplicativo Microsoft Entra para o ponto de extremidade ao qual o conector se conecta (ou seja, seu serviço ou fonte de dados).

Habilitar o suporte do Microsoft Entra para um conector personalizado envolve:

Definir um ou mais escopos no aplicativo de recurso usado pelo conector.
Pré-autorizar os IDs de cliente do Power Query a utilizar esses âmbitos.
Definindo os valores e Scopes corretos Resource na definição do conector.

Este guia pressupõe que um novo aplicativo de recurso esteja registrado no Microsoft Entra. Os desenvolvedores com um aplicativo de recurso existente podem pular para a seção Configurar um escopo .

Nota

Para obter mais detalhes sobre como usar o Microsoft Entra em seu serviço ou aplicativo, vá para um dos guias de início rápido.

Registrar o aplicativo de recursos

Sua fonte de dados ou ponto de extremidade de API usa esse aplicativo de recurso para estabelecer confiança entre seu serviço e a plataforma de identidade da Microsoft.

Siga estas etapas para registrar um novo aplicativo de recurso:

Entre no centro de administração do Microsoft Entra como pelo menos um administrador de aplicativos na nuvem.
Navegue até Registros de aplicativos de identidade>>e selecione Novo registro.
Insira um Nome de exibição para seu aplicativo.
Em Tipos de conta suportados, selecione Contas neste diretório organizacional somente se o ponto de extremidade só estiver acessível de dentro da organização. Selecione Contas em qualquer diretório organizacional para serviços multilocatários acessíveis publicamente.
Selecione Registar.

Não é necessário especificar um valor de URI de redirecionamento.

A página Visão geral do aplicativo é exibida quando o registro é concluído. Anote os valores de ID de diretório (locatário) e ID de aplicativo (cliente), pois eles serão usados no código-fonte do serviço. Siga um dos guias nos exemplos de código da plataforma de identidade da Microsoft que se assemelha ao seu ambiente de serviço e arquitetura para determinar como configurar e usar seu novo aplicativo.

Definir um URI de ID de aplicativo

Antes de configurar um escopo para seu ponto de extremidade, você deve definir um URI de ID de Aplicativo para seu aplicativo de recurso. Este ID será utilizado pelo Resource campo do Aad registo no seu conector. O valor é definido como a URL raiz do seu serviço. Você também pode usar o padrão gerado pelo Microsoft Entra - - api://{clientId} onde {clientId} é a ID do cliente do seu aplicativo de recurso.

Vá para a página Visão geral do aplicativo de recursos.
Na tela central, em Essentials, selecione Adicionar um URI de ID de aplicativo.
Insira um URI ou aceite o padrão com base no ID do aplicativo.
Selecione Guardar e continuar.

Os exemplos neste guia pressupõem que você esteja usando o formato URI de ID do Aplicativo padrão (por exemplo - api://44994a60-7f50-4eca-86b2-5d44f873f93f).

Configurar um escopo

Os escopos são usados para definir permissões ou recursos para acessar APIs ou dados em seu serviço. A lista de escopos suportados é específica do serviço. Você deseja determinar um conjunto mínimo de escopos exigidos pelo seu conector. Tem de pré-autorizar pelo menos um âmbito para os IDs de cliente do Power Query.

Se seu aplicativo de recursos já tiver escopos definidos, você poderá pular para a próxima etapa.

Se o serviço não usar permissões baseadas em escopo, você ainda poderá definir um único escopo usado pelo conector. Você pode (opcionalmente) fazer uso desse escopo em seu código de serviço no futuro.

Neste exemplo, você define um único escopo chamado Data.Read.

Vá para a página Visão geral do aplicativo de recursos.
Em Gerenciar, selecione Expor uma API > Adicionar um escopo.
Em Nome do escopo, insira Data.Read.
Para Quem pode consentir, selecione a opção Administradores e usuários .
Preencha as caixas de nome para exibição e descrição restantes.
Verifique se Estado está definido como Habilitado.
Selecione Adicionar escopo.

Pré-autorizar as aplicações cliente do Power Query

Os conectores do Power Query usam duas IDs de cliente diferentes do Microsoft Entra. A pré-autorização de escopos para essas IDs de cliente simplifica a experiência de conexão.

ID de Cliente	Nome da Aplicação	Usado por
a672d62c-fc7b-4e81-a576-e60dc46e951d	Power Query para Excel	Ambientes de desktop
b52893c8-bc2e-47fc-918b-77022b299bbc	Atualização de Dados do Power BI	Ambientes de serviço

Para pré-autorizar os IDs de cliente do Power Query:

Vá para a página Visão geral do aplicativo de recursos.
Em Gerenciar, selecione Expor uma API.
Selecione Adicionar um aplicativo cliente.
Introduza um dos IDs de Cliente do Power Query.
Selecione os escopos autorizados apropriados.
Selecione Adicionar aplicativo.
Repita os passos 3 a 6 para cada ID de cliente do Power Query.

Habilite o tipo de autenticação Aad no conector

O suporte ao Microsoft Entra ID está habilitado para o conector adicionando o Aad tipo de autenticação ao registro da fonte de dados do conector.

MyConnector = [
    Authentication = [
        Aad = [
            AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
            Resource = "{YourApplicationIdUri}"
            Scope = ".default"
        ]
    ]
];

Substitua o {YourApplicationIdUri} valor pelo valor URI da ID do aplicativo para seu aplicativo de recurso, por exemplo, api://44994a60-7f50-4eca-86b2-5d44f873f93f.

Neste exemplo:

AuthorizationUri: A URL do Microsoft Entra usada para iniciar o fluxo de autenticação. A maioria dos conectores pode codificar esse valor para https://login.microsoftonline.com/common/oauth2/authorize, mas ele também pode ser determinado dinamicamente se seu serviço oferecer suporte a Contas B2B/Convidado do Azure. Para obter mais informações, vá para exemplos.
Recurso: O URI da ID do aplicativo do seu conector.
Escopo: use o escopo .default para receber automaticamente todos os escopos pré-autorizados. O uso .default permite que você altere os escopos de conector necessários em seu registro de aplicativo de recurso, sem a necessidade de atualizar seu conector.

Para obter mais detalhes e opções para configurar o suporte do Microsoft Entra no seu conector, vá para a página de exemplos de autenticação do Microsoft Entra ID.

Reconstrua seu conector e agora você deve ser capaz de autenticar com seu serviço usando o Microsoft Entra ID.

Resolução de Problemas

Esta seção descreve erros comuns que você pode receber se seu aplicativo Microsoft Entra estiver configurado incorretamente.

A aplicação Power Query não foi pré-autorizada

access_denied: AADSTS650057: Recurso inválido. O cliente solicitou acesso a um recurso que não está listado nas permissões solicitadas no registro do aplicativo do cliente. ID do aplicativo cliente: a672d62c-fc7b-4e81-a576-e60dc46e951d (Microsoft Power Query para Excel). Valor do recurso da solicitação: 44994a60-7f50-4eca-86b2-5d44f873f93f. ID do aplicativo de recurso: 44994a60-7f50-4eca-86b2-5d44f873f93

Poderá ver este erro se a sua aplicação de recursos não tiver pré-autorizado as aplicações cliente do Power Query. Siga os passos para pré-autorizar os IDs de cliente do Power Query.

O registro Aad do conector está faltando um valor de escopo

access_denied: AADSTS650053: A aplicação 'Microsoft Power Query para Excel' pediu o âmbito 'user_impersonation' que não existe no recurso '44994a60-7f50-4eca-86b2-5d44f873f93f'. Entre em contato com o fornecedor do aplicativo.

O Power Query solicita o user_impersonation escopo se o registro do Aad conector não definir um Scope campo ou se o Scope valor for null. Você pode resolver esse problema definindo um Scope valor no conector. O uso do .default escopo é recomendado, mas você também pode especificar escopos no nível do conector (por exemplo - Data.Read).

O escopo ou o aplicativo cliente requer aprovação do administrador

Precisa de aprovação do administrador. <> O locatário precisa de permissão para acessar recursos em sua organização que somente um administrador pode conceder. Por favor, peça a um administrador para conceder permissão a este aplicativo antes de poder usá-lo.

Um usuário pode receber esse erro durante seu fluxo de autenticação se seu Aplicativo de Recursos exigir permissões restritas ao administrador ou se o locatário do usuário impedir que usuários não administradores consintam com novas solicitações de permissão do aplicativo. Pode evitar este problema garantindo que o conector não requer âmbitos restritos pelo administrador e pré-autorizando os IDs de cliente do Power Query para a sua Aplicação de Recursos.

Partilhar via