Autenticação (pré-visualização)

Artigo
12/28/2023

Este artigo fornece uma descrição geral da configuração do Microsoft Entra para chamar a API do Power Platform (pré-visualização). Para aceder aos recursos disponíveis através da API do Power Platform, tem de obter um token de portador do Microsoft Entra e enviá-lo como um cabeçalho juntamente com cada pedido. Dependendo do tipo de identidade que está a suportar (utilizador vs. principal de serviço), existem fluxos diferentes para obter este token de portador, conforme descrito neste artigo.

Os passos seguintes são necessários para obter um token de portador com as permissões corretas:

Criar um registo de aplicação no seu inquilino do Microsoft Entra
Configurar permissões de API
Configurar Cliente Público (opcional)
Configurar Certificados e Segredos (opcional)
Pedir um token de acesso

Passo 1. Criar um registo de aplicação

Navegue para a página registo de aplicação do Microsoft Entra e crie um novo registo. Dê um nome à aplicação e certifique-se de que a opção Inquilino único está selecionada. Pode ignorar a configuração do URI de redirecionamento.

Passo 2. Configurar permissões de API

No novo registo de aplicação, navegue para o separador Gerir – Permissões de API. Na secção Configurar permissões, selecione Adicionar uma Permissão. Na janela de diálogo que se abre, selecione o separador APIs que a minha organização utiliza e, em seguida, procure por API do Power Platform. Pode ver várias entradas com um nome semelhante a este, por isso certifique-se de que utiliza a que tem o GUID 8578e004-a5c6-46e7-913e-12f58912df43.

Se não vir a API do Power Platform a aparecer na lista quando pesquisa pelo GUID, é possível que ainda tenha acesso à mesma, mas a visibilidade não esteja atualizada. Para forçar uma atualização, execute o script do PowerShell abaixo:

#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, tem de selecionar as permissões necessárias. Estes são agrupados por Espaços de nomes. Dentro de um espaço de nomes, verá tipos de recurso e ações, por exemplo AppManagement.ApplicationPackages.Read, o que irá dar permissões de leitura para pacotes de aplicações. Para mais informações, consulte o nosso artigo Referência de permissão.

Nota

A API do Power Platform só utiliza permissões delegadas neste momento. Para aplicações que são executados com um contexto de utilizador, pede permissões delegadas utilizando o parâmetro âmbito. Estas permissões delegam os privilégios do utilizador com sessão iniciada na sua aplicação, permitindo-lhe agir como o utilizador quando chama os pontos finais da API do Power Platform.

Para as identidades do principal do serviço, não são utilizadas permissões de aplicação. Em vez disso, atualmente, os principais de serviço são tratados como Administradores do Power Platform e têm de ser registados seguindo PowerShell – Criar principal do serviço.

Depois de as permissões necessárias serem adicionadas à aplicação, selecione Conceder consentimento do administrador para concluir a configuração. Isto é necessário para instâncias em que pretende permitir que os utilizadores acedam de imediato à sua aplicação, em vez de requerer uma experiência de consentimento interativo. Se você puder oferecer suporte ao consentimento interativo, recomendamos seguir a plataforma de identidade e Microsoft o fluxo de OAuth código de autorização 2.0.

Passo 3. Configurar Cliente Público (opcional)

Se a aplicação requerer recursos de leitura e de escrita em nome de um utilizador, terá de ativar a definição Cliente Público. Esta é a única forma de o ID do Microsoft Entra aceitar as propriedades username e password no corpo do seu pedido de token. Note também que, se pretende utilizar esta funcionalidade, esta funcionalidade não funciona para contas que tenham a autenticação multifator ativada.

Para ativar, visite o separador Gerir – Autenticação. Na secção Definições Avançadas, defina o comutador Cliente Público como Sim.

Passo 4. Configurar Certificados e Segredos (opcional)

Se a aplicação requerer recursos de leitura e de escrita como ela própria, também conhecido como Principal de Serviço, existem duas formas de autenticação. Para utilizar certificados, navegue para o separador Gerir – Certificados e Segredos. Na secção Certificados, carregue um certificado x509 que poderá utilizar para autenticar. A outra forma é utilizar a secção Segredos para gerar um segredo do cliente. Guarde o segredo num local seguro para utilizar com as suas necessidades de automatização. As opções de certificado ou segredo permitir-lhe-ão fazer a autenticação junto do Microsoft Entra e receber um token para este cliente, o qual transmitirá para as APIs REST ou para os cmdlets PowerShell.

Passo 5. Pedir um token de acesso

Existem duas formas de obter um token de portador de acesso. Uma é para nome de utilizador e palavra-passe e a outra é para Principais de Serviço.

Fluxo de nome de utilizador e palavra-passe

Certifique-se de que lê acima a secção Cliente Público. Em seguida, envie um pedido POST via HTTP para o ID do Microsoft Entra com um payload de nome de utilizador e palavra-passe.

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 marcadores de posição que pode obter a partir da sua aplicação cliente no ID do Microsoft Entra. Receberá uma resposta que pode ser utilizada 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..."
}

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

Fluxo do principal de serviço

Certifique-se de que lê acima a secção Certificados e Segredos. Em seguida, envie um pedido POST via HTTP para o ID do Microsoft Entra com um payload de segredo do cliente. Isto é frequentemente referido como autenticação do principal do serviço.

Importante

Isto só pode ser utilizado depois de ter registado este ID da aplicação cliente com o Microsoft Power Platform seguindo a documentação relacionada do PowerShell ou 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..."
}

Utilize o valor access_token em chamadas subsequentes para a API do Power Platform com o cabeçalho HTTP Autorização. Como é mencionado acima, o fluxo de Principal de Serviço não utiliza permissões de aplicação e é, em vez disso, por agora, tratada como um Administrador do Power Platform para todas as chamadas que efetuar.

Consulte também

Criando um aplicativo principal de serviço via API (pré-visualização)
PowerShell - Criar entidade de serviço

Partilhar via