Compartilhar via

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

  • Artigo

Este guia descreve as etapas para configurar um aplicativo Microsoft Entra para uso 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 aplicativo é usado em vários contextos na plataforma Microsoft Entra, este guia usa os seguintes termos para distinguir entre IDs de aplicativo do conector e da 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 do conector (ou seja, seu serviço ou fonte de dados).

A habilitação do 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 para usar esses escopos.
  • Configurar os valores Resource e Scopes corretos 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.

Observação

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 recurso

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

Siga estas etapas para registrar um novo aplicativo de recurso:

  1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
  2. Navegue até Identidade>Aplicativos>Registros de aplicativos e selecione Novo registro.
  3. Insira um Nome de exibição para o seu aplicativo.
  4. Para Tipos de conta com suporte, selecione Somente contas neste diretório organizacional se o ponto de extremidade só estiver acessível de dentro da organização. Selecione Contas em qualquer diretório organizacional para os serviços multilocatários acessíveis publicamente.
  5. Selecione Registrar.

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

A página Visão geral do aplicativo será exibida quando o registro for concluído. Anote os valores do ID de diretório (locatário) e do ID do 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 assemelham ao seu ambiente de serviço e arquitetura para determinar como configurar e usar seu novo aplicativo.

Configurar um URI do ID de Aplicativo

Antes de configurar um escopo para seu ponto de extremidade, defina o URI do ID de Aplicativo para seu aplicativo de recurso. Esse ID será usado pelo Resource campo do registro Aad em 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} - no qual {clientId} é o ID do cliente do aplicativo de recurso.

  1. Acesse a página Visão geral do aplicativo de recurso.
  2. Na tela central, em Essentials, selecione Adicionar um URI do ID de aplicativo.
  3. Insira um URI ou aceite o padrão com base no ID de aplicativo.
  4. Selecione Salvar e continuar.

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

Configurar um Escopo

Escopos são usados para definir permissões ou recursos para acessar APIs ou dados em seu serviço. A lista de escopos compatíveis é específica do serviço. Determine um conjunto mínimo de escopos exigidos pelo conector. Você precisa pré-autorizar pelo menos um escopo para os IDs de cliente do Power Query.

Se o aplicativo de recurso já tiver escopos definidos, vpasse 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) usar esse escopo em seu código de serviço no futuro.

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

  1. Acesse a página Visão geral do aplicativo de recurso.
  2. Em Gerenciar, selecione Expor uma API>Adicionar um escopo.
  3. Para Nome do escopo, insira Data.Read.
  4. Para Quem pode consentir, selecione as opções Administradores e usuários.
  5. Preencha as caixas nome de exibição e descrição restantes.
  6. Verifique se Estado está definido como Habilitado.
  7. Selecione Adicionar escopo.

Pré-autorizar os aplicativos cliente do Power Query

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

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

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

  1. Acesse a página Visão geral do aplicativo de recurso.
  2. Em Gerenciar, selecione Expor uma API.
  3. Selecione Adicionar um aplicativo cliente.
  4. Insira um dos IDs de Cliente do Power Query.
  5. Selecione os Escopos autorizados apropriados.
  6. Escolha Adicionar aplicativo.
  7. Repita as etapas de 3 a 6 para cada ID de cliente do Power Query.

Habilitar o tipo de autenticação Aad no conector

O suporte ao ID do Microsoft Entra está habilitado para o conector adicionando o tipo de autenticação Aad 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 valor {YourApplicationIdUri} pelo valor do URI de 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 for compatível com as Contas B2B/Convidado do Azure. Para obter mais informações, confira amostras.
  • Recurso: o URI do ID do aplicativo do conector.
  • Escopo: use o escopo .default para receber automaticamente todos os escopos pré-autorizados. O uso do .default permite que você altere os escopos do conector necessários no registro do aplicativo de recurso, sem a necessidade de atualizar o conector.

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

Recrie o conector e agora você poderá se autenticar com seu serviço usando o Microsoft Entra ID.

Solução de problemas

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

O aplicativo Power Query não foi pré-autorizado

access_denied: AADSTS650057: recurso inválido. O cliente solicitou acesso a um recurso que não está listado nas permissões solicitadas no registro de 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

Esse erro poderá ocorrer se o aplicativo de recurso não tiver pré-autorizado os aplicativos de cliente do Power Query. Siga as etapas para pré-autorizar os IDs do cliente no Power Query.

O registro Aad do conector não tem um valor de escopo

access_denied: AADSTS650053: o aplicativo 'Microsoft Power Query para Excel' solicitou o escopo 'user_impersonation' que não existe no recurso '44994a60-7f50-4eca-86b2-5d44f873f93f'. Contate o fornecedor do aplicativo.

O Power Query solicita o escopo user_impersonation se o registro do conector Aad não definir um campo Scope ou se o valor Scope for null. Você pode resolver esse problema definindo um valor Scope no conector. O uso do escopo .default é 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

A aprovação do administrador é necessária. O <locatário> precisa de permissão para acessar recursos em sua organização que somente um administrador pode conceder. Peça a um administrador para conceder permissão ao aplicativo antes de poder usá-lo.

Um usuário pode receber esse erro durante seu fluxo de autenticação se o Aplicativo de Recursos exigir permissões restritas ao administrador ou se o locatário do usuário impedir que usuários não administradores autorizem novas solicitações de permissão de aplicativo. Você pode evitar esse problema garantindo que seu conector não exija escopos restritos ao administrador e pré-autorizando as IDs de cliente do Power Query para o Aplicativo de Recurso.