Autenticação (versão preliminar)

Artigo
01/02/2024

Este artigo fornece uma visão geral da configuração do Microsoft Entra para chamar a API do Power Platform (versão preliminar). Para acessar os recursos disponíveis por meio da API do Power Platform, você deverá obter um token de portador do Microsoft Entra e enviá-lo como um cabeçalho junto com cada solicitação. Dependendo do tipo de identidade ao qual você está dando suporte (usuário versus entidade de serviço), há fluxos diferentes para obter esse token de portador, conforme descrito neste artigo.

As etapas a seguir são necessárias para obter um token de portador com as permissões corretas:

Criar um registro de aplicativo em seu locatário do Microsoft Entra
Configurar permissões de API
Configurar Cliente Público (opcional)
Configurar Certificados e Segredos (opcional)
Solicitar um token de acesso

Etapa 1. Criar um registro de aplicativo

Navegue até a página Registro de aplicativo do Microsoft Entra e crie um novo registro. Dê um nome ao aplicativo e certifique-se de que a opção Locatário único esteja selecionada. Você pode ignorar a configuração do URI de redirecionamento.

Etapa 2. Configurar permissões de API

No registro do seu novo aplicativo, navegue até a guia Gerenciar - Permissões de API. Na seção Configurar permissões, selecione Adicionar uma Permissão. Na janela de diálogo que é aberta, selecione a guia APIs usadas por minha organização e, em seguida, pesquise API do Power Platform. Você pode ver várias entradas com um nome semelhante a este, portanto, certifique-se de usar aquela com o GUID 8578e004-a5c6-46e7-913e-12f58912df43.

Se não vir a API do Power Platform na lista ao pesquisar o GUID, é possível que você ainda tenha acesso a ela, mas a visibilidade não foi atualizada. Para impor uma atualização, execute o seguinte script do PowerShell:

#Install the Microsoft Entra the module
Install-Module AzureAD

Connect-AzureAD
New-AzureADServicePrincipal -AppId 8578e004-a5c6-46e7-913e-12f58912df43 -DisplayName "Power Platform API"

A partir daqui, você deverá selecionar as permissões necessárias. Elas são agrupadas por Namespaces. Em um namespace, você verá tipos de recursos e ações, por exemplo, AppManagement.ApplicationPackages.Read, que dará permissões de leitura para pacotes de aplicativos. Para obter mais informações, confira nosso artigo Referência de permissão.

Observação

A API do Power Platform faz uso de permissões delegadas apenas neste momento. Para aplicativos executados com um contexto de usuário, você solicita permissões delegadas usando o parâmetro scope. Essas permissões delegam os privilégios do usuário conectado ao seu aplicativo, permitindo que ele atue como o usuário ao chamar pontos de extremidade da API do Power Platform.

Para identidades de entidade de serviço, as permissões de aplicativo não são usadas. Em vez disso, as entidades de serviço são tratadas como Administradores do Power Platform e devem ser registradas seguindo PowerShell - Criar entidade de serviço.

Depois que as permissões necessárias forem adicionadas ao aplicativo, selecione Conceder consentimento de administração para concluir a configuração. Isso será necessário para casos em que você deseja permitir que os usuários acessem seu aplicativo imediatamente, em vez de exigir uma experiência de consentimento interativa. Se você puder dar suporte ao consentimento interativo, recomendamos seguir o fluxo de código de autorização da plataforma de identidade da Microsoft e do OAuth 2.0.

Etapa 3. Configurar Cliente Público (opcional)

Se seu aplicativo exigir recursos de leitura e gravação em nome de um usuário, você precisará habilitar a configuração de Cliente Público. Esta é a única maneira para o Microsoft Entra ID aceitar propriedades de nome de usuário e senha no corpo de sua solicitação de token. Observe também que, se você pretende usar esse recurso, ele não funcionará para contas com autenticação multifator habilitada.

Para habilitar, visite a guia Gerenciar – Autenticação. Na seção Configurações Avançadas, defina a alternância Cliente Público como Sim.

Etapa 4. Configurar Certificados e Segredos (opcional)

Se o seu aplicativo exigir recursos de leitura e gravação como ele mesmo, também conhecido como Entidade de Serviço, há duas maneiras de autenticar. Para usar certificados, navegue até a guia Gerenciar – Certificados e segredos. Na seção Certificados, carregue um certificado x509 que você poderá usar para autenticar. A outra forma é usar a seção Segredos para gerar um segredo do cliente. Salve o segredo em um local seguro para usar com suas necessidades de automação. As opções de certificado ou de segredo permitirão que você se autentique no Microsoft Entra e receba um token para esse cliente, do qual você passará para as APIs REST ou cmdlets do PowerShell.

Etapa 5. Solicitar um token de acesso

Há duas maneiras de obter um token de portador de acesso. Uma é para nome de usuário e senha e o outra é para Entidades de Serviço.

Fluxo de nome de usuário e senha

Leia a seção Cliente Público acima. Em seguida, envie uma solicitação POST via HTTP para o Microsoft Entra ID com um conteúdo de nome de usuário e senha.

Content-Type: application/x-www-form-urlencoded
Host: login.microsoftonline.com
Accept: application/json
POST https://login.microsoftonline.com/YOUR_TENANT.COM/oauth2/v2.0/token
BODY:
client_id={CLIENT_ID_FROM_AZURE_CLIENT_APP}&scope=https://api.powerplatform.com/.default&username={USER_EMAIL_ADDRESS}&password={PASSWORD}&grant_type=password

O exemplo acima contém espaços reservados que você pode recuperar de seu aplicativo cliente no Microsoft Entra ID. Você receberá uma resposta que poderá ser usada para fazer chamadas subsequentes para a API do Power Platform.

{
  "token_type": "Bearer",
  "scope": "https://api.powerplatform.com/AppManagement.ApplicationPackages.Install https://api.powerplatform.com/AppManagement.ApplicationPackages.Read https://api.powerplatform.com/.default",
  "expires_in": 4747,
  "ext_expires_in": 4747,
  "access_token": "eyJ0eXAiOiJKV1QiLCJu..."
}

Use o valor access_token nas chamadas subsequentes para a API do Power Platform com o cabeçalho HTTP Autorização.

Fluxo de Entidade de serviço

Leia a seção Certificados e segredos acima. Em seguida, envie uma solicitação POST via HTTP para o Microsoft Entra id com um conteúdo de segredo de cliente. Isso geralmente é conhecido como autenticação da entidade de serviço.

Importante

Isso só poderá ser usado após você ter registrado essa ID de aplicativo cliente no Microsoft Power Platform seguindo a documentação relacionada do PowerShell ou do REST.

Content-Type: application/x-www-form-urlencoded
Host: login.microsoftonline.com
Accept: application/json
POST https://login.microsoftonline.com/YOUR_TENANT.COM/oauth2/v2.0/token
BODY:
client_id={CLIENT_ID_FROM_AZURE_CLIENT_APP}&scope=https://api.powerplatform.com/.default&client_secret={SECRET_FROM_AZURE_CLIENT_APP}&grant_type=client_credentials

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1..."
}

Use o valor access_token nas chamadas subsequentes para a API do Power Platform com o cabeçalho HTTP Autorização. Conforme observado acima, o fluxo da Entidade de Serviço não usa permissões de aplicativo e, por enquanto, é tratado como um Administrador do Power Platform para todas as chamadas que elas fazem.

Consulte também

Criando um aplicativo de entidade de serviço via API (versão preliminar)
PowerShell - Criar entidade de serviço

Compartilhar via