Authentication

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

Para obter um token portador com as permissões corretas, complete os seguintes passos:

1. Crie um registo de aplicação no seu tenant Microsoft Entra
2. Configurar permissões de API
3. Configurar plataforma e redirecionar URI
4. (Opcional) Configurar certificados e segredos
5. Solicitar um token de acesso

Passo 1. Criar um registo de aplicação no seu inquilino do Microsoft Entra

1. Vai para o portal Azure.
2. Selecione o ID Microsoft Entra no topo da página. Depois seleciona + Adicionar>registo de app.
3. Preencha a página de Registo de candidatura:
   1. Nome — Dê à aplicação um nome reconhecível, como Power Platform Admin SDK.
   2. Tipos de contas suportadas — Selecione Apenas inquilino único - <nome> da sua empresa.
   3. Redirecionar URI — Ignora isto por agora. Configura-se no Passo 3.
4. Selecione Registrar para criar o aplicativo. Após a conclusão do registo, note o ID da Aplicação (cliente) e o ID do Diretório (inquilino) na página de visão geral — precisa de ambos os valores mais tarde.

Também pode criar o registo usando o Azure CLI:

az login

az ad app create --display-name "Power Platform Admin SDK" --sign-in-audience AzureADMyOrg

O comando devolve um objeto JSON. Note o appId valor — esse valor é o seu ID de cliente.

Passo 2. Configurar permissões de API

No registo da sua nova aplicação, vá ao separador Gerenciar - Permissões da API . Na secção Configurar permissões , selecione Adicionar uma Permissão. Na caixa de diálogo, selecione o separador das APIs que a minha organização utiliza , e depois procure por Power Platform API. Pode ver várias entradas com um nome semelhante a este, por isso certifique-se de usar a que tem o GUID 8578e004-a5c6-46e7-913e-12f58912df43.

Se não vires a API do Power Platform exibida na lista ao pesquisares por GUID, podes ainda ter acesso a ela, mas a visibilidade não é atualizada. Para forçar uma atualização, execute o seguinte script:

#Install the Microsoft Graph PowerShell SDK module
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force

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

az login

az ad sp create --id 8578e004-a5c6-46e7-913e-12f58912df43

A partir daqui, selecione as permissões de que precisa. Estas permissões estão agrupadas por Namespaces. Dentro de um namespace, vê-se tipos de recursos e ações, como AppManagement.ApplicationPackages.Read, que dá permissões de leitura para pacotes de aplicação. Para mais informações, consulte o artigo de referência sobre Permissões .

Depois de adicionar as permissões necessárias à aplicação, selecione Conceder consentimento de administrador para concluir a configuração. Ao conceder o consentimento do administrador, autoriza as permissões para todos os utilizadores do tenant para que não sejam convidados com um diálogo interativo de consentimento na primeira utilização da sua aplicação. Se preferir consentimento interativo por utilizador, siga a Microsoft Identity Platform e o fluxo de código de autorização OAuth 2.0.

Também pode conceder consentimento de administrador usando o Azure CLI:

# Replace <app-id> with your application (client) ID
az ad app permission admin-consent --id <app-id>

Passo 3. Configurar plataforma e redirecionar URI

SDKs, scripts PowerShell e aplicações de ambiente de trabalho que se autenticam em nome de um utilizador requerem um URI de redirecionamento para que a Microsoft Entra possa devolver tokens à sua aplicação após a autenticação.

1. No registo da sua aplicação, vá a Gerenciar - Autenticação.

2. Selecione Adicionar um URI de Redirecionamento, depois escolha aplicações móveis e desktop.

3. Selecione o seguinte URI de redirecionamento incorporado:

   https://login.microsoftonline.com/common/oauth2/nativeclient

4. Selecione Configurar para guardar.

Também pode adicionar o URI de redirecionamento usando o Azure CLI:

# Replace <app-id> with your application (client) ID
az ad app update --id <app-id> --public-client-redirect-uris https://login.microsoftonline.com/common/oauth2/nativeclient

Configuração de cliente público

Na secção de Definições Avançadas , no mesmo separador de Autenticação , há uma opção para permitir fluxos públicos de clientes . Defina esta opção para Sim apenas se planear usar o fluxo Resource Owner Password Credentials (ROPC), que envia um nome de utilizador e uma palavra-passe diretamente no corpo do token request.

Este fluxo não funciona para contas que têm autenticação multifator ativada. Para fluxos interativos de código de navegador ou dispositivo, não precisa de ativar esta configuração.

Passo 4. (Opcional) Configurar certificados e segredos

Se a sua aplicação requer recursos de leitura e escrita por si só, também conhecidos como princípio de serviço, existem duas formas de autenticar. Para usar certificados, vá a Gerenciar - Certificados e segredos. Na secção de Certificados , carregue um certificado x509 que possa usar 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 permitem-lhe autenticar-se com o Microsoft Entra e receber um token para este cliente, que passa para as APIs REST ou para os comandos do PowerShell.

Passo 5. Pedir um token de acesso

Pode obter um token portador de acesso de duas formas: uma é para nome de utilizador e palavra-passe, e a outra é para os principais de serviço.

Fluxo de nome de utilizador e palavra-passe

Certifique-se de ler a secção de clientes públicos. 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 anterior contém marcadores de posição que pode recuperar da sua aplicação cliente no Microsoft Entra ID. Recebe uma resposta que pode usar para fazer chamadas subsequentes à 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 ler a secção Configurar certificados e segredos . Em seguida, envie um pedido POST via HTTP para o ID do Microsoft Entra com um payload de segredo do cliente. Este método de autenticação é frequentemente referido como autenticação principal de serviço.

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

O exemplo anterior contém marcadores de posição que pode recuperar da sua aplicação cliente no Microsoft Entra ID. Recebe uma resposta que pode usar para fazer chamadas subsequentes à API do Power Platform.

{
  "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. As permissões efetivas do principal de serviço são determinadas pelo papel RBAC que lhe é atribuído. Para aprender a atribuir um papel, veja o Tutorial: Atribuir papéis RBAC aos principais de serviço.

Início rápido com Azure CLI

O script seguinte cria um registo de aplicação de ponta a ponta. Executa cada comando por ordem e substitui valores provisórios pelos teus.

# Sign in to Azure CLI
az login

# Create the app registration (single tenant)
az ad app create --display-name "Power Platform Admin SDK" --sign-in-audience AzureADMyOrg

# Save the app ID from the output, then create a service principal for it
az ad sp create --id <app-id>

# Add a delegated permission (example: AppManagement.ApplicationPackages.Read)
# The --api value is the Power Platform API app ID.
# The --api-permissions value is the permission ID and type (Scope = delegated).
# Repeat this command for each permission you need. See the Permission reference for IDs.
az ad app permission add --id <app-id> \
  --api 8578e004-a5c6-46e7-913e-12f58912df43 \
  --api-permissions <permission-id>=Scope

# Grant admin consent so users aren't prompted individually
az ad app permission admin-consent --id <app-id>

# Add the native client redirect URI for interactive auth
az ad app update --id <app-id> \
  --public-client-redirect-uris https://login.microsoftonline.com/common/oauth2/nativeclient

Depois de executar estes comandos, pode usar o registo da sua aplicação com os SDKs, PowerShell ou chamadas REST diretas. Para consultar os IDs de permissão para o --api-permissions parâmetro, consulte a referência de Permissões.

Solução de problemas comuns

Erros de "consentimento necessário" ou "requer aprovação do administrador"

Este erro ocorre quando o administrador não consentiu com as permissões da API para o registo da sua aplicação. Vá a Registos>> de Apps Permissões da API da sua aplicação e selecione Conceder consentimento de administrador.

Em alternativa, execute:

az ad app permission admin-consent --id <app-id>

Erros "O utilizador não é atribuído a um papel para a aplicação"

Este erro significa que a aplicação empresarial associada ao registo da sua aplicação tem a atribuição de utilizador requerida definida como Sim. Quando esta configuração está ativada, apenas os utilizadores ou grupos explicitamente atribuídos à aplicação podem iniciar sessão. Para corrigir este erro, tome uma das seguintes ações:

• Vá àsaplicações>empresariais> Microsoft Entra ID, propriedades da sua aplicação> e defina Atribuição necessária para Nº.
• Adicione os utilizadores relevantes ou grupos de segurança em Utilizadores e grupos.

Políticas de acesso condicional que bloqueiam o acesso

Se a sua organização aplicar políticas de acesso condicional, podem bloquear a aquisição de tokens para o registo da sua aplicação. As causas comuns incluem requisitos de conformidade com dispositivos, restrições de localização ou políticas baseadas no risco. Trabalhe com o administrador do Microsoft Entra para excluir o registo da sua aplicação da política ou garantir que os clientes cumprem os requisitos da política.

"Power Platform API" não encontrada no seletor de API

Se pesquisar por Power Platform API por nome ou GUID no diálogo de permissões da API não der resultados, o principal de serviço não é criado no seu tenant. Siga os passos de atualização forçada no Passo 2 para o criar.

Autenticar com SDKs do Power Platform e PowerShell

Os exemplos seguintes mostram como autenticar e fazer uma chamada de API de exemplo usando cada SDK e PowerShell. Antes de executar estes exemplos, complete os Passos 1-3 anteriores neste artigo para criar e configurar o registo da sua aplicação.

Autenticação interativa (utilizador delegado)

A autenticação interativa abre uma janela do navegador para o utilizador iniciar sessão. Este fluxo funciona melhor para scripts de programação, ferramentas de administração e qualquer cenário em que um utilizador esteja presente.

# Sign in interactively (opens a browser)
Connect-AzAccount

# Get an access token for the Power Platform API
$token = Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com"

# Call the List Environments endpoint as an example
$headers = @{ Authorization = "Bearer $($token.Token)" }
$environments = Invoke-RestMethod -Uri "https://api.powerplatform.com/environmentmanagement/environments?api-version=2024-10-01" -Headers $headers
$environments.value | Format-Table name, properties.displayName

using Microsoft.PowerPlatform.Management;

// Create an interactive client — opens a browser for sign-in
var factory = new ServiceClientFactory();
var client = factory.Create("YOUR_CLIENT_ID");

// List environments as an example
var environments = await client.Environmentmanagement.Environments.GetAsync();
foreach (var env in environments.Value)
{
    Console.WriteLine($"{env.Name} - {env.Properties.DisplayName}");
}

import asyncio
from azure.identity import InteractiveBrowserCredential
from kiota_authentication_azure import AzureIdentityAuthenticationProvider
from kiota_http import HttpxRequestAdapter
from mspp_management import ServiceClientBase

async def main():
    # Create interactive browser credential
    credential = InteractiveBrowserCredential(client_id="YOUR_CLIENT_ID")

    # Wire up the Kiota request adapter
    auth_provider = AzureIdentityAuthenticationProvider(
        credentials=credential,
        scopes=["https://api.powerplatform.com/.default"]
    )
    adapter = HttpxRequestAdapter(authentication_provider=auth_provider)

    # Create the SDK client
    client = ServiceClientBase(adapter)

    # List environments as an example
    environments = await client.environmentmanagement.environments.get()
    for env in environments.value:
        print(f"{env.name} - {env.properties.display_name}")

asyncio.run(main())

Cliente confidencial (principal de serviço)

A autenticação de cliente confidencial utiliza um segredo ou certificado de cliente e não requer interação do utilizador. Este fluxo de autenticação é ideal para serviços em segundo plano, pipelines e automação.

$tenantId = "YOUR_TENANT_ID"
$clientId = "YOUR_CLIENT_ID"
$clientSecret = "YOUR_CLIENT_SECRET"

# Request a token using client credentials
$body = @{
    client_id     = $clientId
    scope         = "https://api.powerplatform.com/.default"
    client_secret = $clientSecret
    grant_type    = "client_credentials"
}
$tokenResponse = Invoke-RestMethod -Method Post `
    -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" `
    -ContentType "application/x-www-form-urlencoded" `
    -Body $body

# Call the List Environments endpoint as an example
$headers = @{ Authorization = "Bearer $($tokenResponse.access_token)" }
$environments = Invoke-RestMethod -Uri "https://api.powerplatform.com/environmentmanagement/environments?api-version=2024-10-01" -Headers $headers
$environments.value | Format-Table name, properties.displayName

using Microsoft.PowerPlatform.Management;

// Create a confidential client with a client secret
var factory = new ServiceClientFactory();
var client = factory.CreateConfidential(
    "YOUR_TENANT_ID",
    "YOUR_CLIENT_ID",
    "YOUR_CLIENT_SECRET"
);

// List environments as an example
var environments = await client.Environmentmanagement.Environments.GetAsync();
foreach (var env in environments.Value)
{
    Console.WriteLine($"{env.Name} - {env.Properties.DisplayName}");
}

import asyncio
from azure.identity import ClientSecretCredential
from kiota_authentication_azure import AzureIdentityAuthenticationProvider
from kiota_http import HttpxRequestAdapter
from mspp_management import ServiceClientBase

async def main():
    # Create client secret credential
    credential = ClientSecretCredential(
        tenant_id="YOUR_TENANT_ID",
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET"
    )

    # Wire up the Kiota request adapter
    auth_provider = AzureIdentityAuthenticationProvider(
        credentials=credential,
        scopes=["https://api.powerplatform.com/.default"]
    )
    adapter = HttpxRequestAdapter(authentication_provider=auth_provider)

    # Create the SDK client
    client = ServiceClientBase(adapter)

    # List environments as an example
    environments = await client.environmentmanagement.environments.get()
    for env in environments.value:
        print(f"{env.name} - {env.properties.display_name}")

asyncio.run(main())

Conteúdo relacionado

Tutorial: Atribuir funções RBAC aos principais de serviço
Controlo de acesso baseado em funções para o centro de administração do Power Platform
Referência de permissão