Authentication

Este artigo fornece uma visão geral da configuração do Microsoft Entra para chamar a API do Power Platform. Para acessar os recursos disponíveis por meio da API do Power Platform, você deve 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 que você está suportando (usuário vs. entidade de serviço) há fluxos diferentes para obter esse token de portador, conforme descrito neste artigo.

Para obter um token de portador com as permissões corretas, conclua as seguintes etapas:

1. Criar um registro de aplicativo em seu locatário do Microsoft Entra
2. Configurar permissões de API
3. Configurar o URI de plataforma e redirecionamento
4. (Opcional) Configurar certificados e segredos
5. Solicitar um token de acesso

Etapa 1. Criar um registro de aplicativo em seu locatário do Microsoft Entra

1. Acesse o portal do Azure.
2. Selecione a ID do Microsoft Entra na parte superior da página. Em seguida, selecione + Adicionar>registro de aplicativo.
3. Preencha a página Registrar um aplicativo :
   1. Nome : dê ao aplicativo um nome reconhecível, como o SDK do Administrador do Power Platform.
   2. Tipos de conta com suporte – selecionar somente locatário único – <o nome> da sua empresa.
   3. URI de redirecionamento – Ignore isso por enquanto. Configure-o na Etapa 3.
4. Selecione Registrar para criar o aplicativo. Após a conclusão do registro, observe a ID do aplicativo (cliente) e a ID do diretório (locatário) da página de visão geral. Você precisará dos dois valores posteriormente.

Você também pode criar o registro usando a CLI do Azure:

az login

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

O comando retorna um objeto JSON. Observe o appId valor : esse valor é a ID do cliente.

Etapa 2. Configurar permissões de API

No novo registro do aplicativo, vá para a guia Gerenciar – Permissões de API . Na seção Configurar permissões, selecioneAdicionar uma Permissão. Na caixa de diálogo, selecione as APIs que minha organização usa e pesquise a API do Power Platform. Você pode ver várias entradas com um nome semelhante a este, portanto, use-a com o GUID 8578e004-a5c6-46e7-913e-12f58912df43.

Se você não vir a API do Power Platform exibida na lista ao pesquisar por GUID, talvez ainda tenha acesso a ela, mas a visibilidade não será 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 necessárias. Essas permissões são agrupadas por Namespaces. Em um namespace, você vê tipos de recursos e ações, como AppManagement.ApplicationPackages.Read, que fornece permissões de leitura para pacotes de aplicativos. Para obter mais informações, consulte o artigo de referência de permissão .

Depois de adicionar as permissões necessárias ao aplicativo, selecione Conceder consentimento do administrador para concluir a instalação. Ao conceder consentimento do administrador, você autoriza as permissões para todos os usuários no locatário para que eles não sejam solicitados com uma caixa de diálogo de consentimento interativa na primeira vez que usarem seu aplicativo. Se preferir o consentimento interativo por usuário, siga a plataforma de identidade da Microsoft e o fluxo de código de autorização do OAuth 2.0.

Você também pode conceder consentimento do administrador usando a CLI do Azure:

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

Etapa 3. Configurar o URI de plataforma e redirecionamento

SDKs, scripts do PowerShell e aplicativos da área de trabalho que se autenticam em nome de um usuário exigem um URI de redirecionamento para que o Microsoft Entra possa retornar tokens de volta ao seu aplicativo após a autenticação.

1. No registro do aplicativo, vá para Gerenciar – Autenticação.

2. Selecione Adicionar um URI de Redirecionamento e escolha Aplicativos móveis e de área de trabalho.

3. Selecione o seguinte URI de redirecionamento interno:

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

4. Selecione Configurar para salvar.

Você também pode adicionar o URI de redirecionamento usando a CLI do Azure:

# 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 do cliente público

Na seção Configurações avançadas na mesma guia Autenticação , há uma alternância Permitir fluxos de cliente públicos . Defina essa alternância como Sim somente se você planeja usar o fluxo ROPC (Credenciais de Senha do Proprietário do Recurso), que envia um nome de usuário e uma senha diretamente no corpo da solicitação de token.

Esse fluxo não funciona para contas que têm a autenticação multifator habilitada. Para fluxos interativos de código do navegador ou do dispositivo, você não precisa habilitar essa configuração.

Etapa 4. (Opcional) Configurar certificados e segredos

Se seu aplicativo exigir a leitura e gravação de recursos como ele mesmo, também conhecido como uma entidade de serviço, há duas maneiras de autenticar. Para usar certificados, acesse Gerenciar – Certificados e segredos. Na seção Certificados , carregue um certificado x509 que você pode 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 segredo permitem que você se autentique com o Microsoft Entra e receba um token para esse cliente, que você passa para as APIs REST ou cmdlets do PowerShell.

Etapa 5. Solicitar um token de acesso

Você pode obter um token de portador de acesso de duas maneiras: uma maneira é para nome de usuário e senha e a outra é para entidades de serviço.

Fluxo de nome de usuário e senha

Certifique-se de ler a seção de cliente público. 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 anterior contém espaços reservados que você pode recuperar do aplicativo cliente na ID do Microsoft Entra. Você recebe uma resposta que pode ser usada 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..."
}

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 Configurar certificados e segredos . Em seguida, envie uma solicitação POST via HTTP para o Microsoft Entra id com um conteúdo de segredo de cliente. Esse método de autenticação geralmente é chamado de autenticação de entidade 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 espaços reservados que você pode recuperar do aplicativo cliente na ID do Microsoft Entra. Você recebe uma resposta que pode ser usada para fazer chamadas subsequentes à API do Power Platform.

{
  "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. As permissões efetivas da entidade de serviço são determinadas pela função RBAC atribuída a ela. Para saber como atribuir uma função, consulte Tutorial: Atribuir funções RBAC a entidades de serviço.

Início rápido com a CLI do Azure

O script a seguir cria um registro de aplicativo de ponta a ponta. Execute cada comando em ordem e substitua os valores de espaço reservado por seus próprios.

# 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 esses comandos, você pode usar o registro do aplicativo com os SDKs, o PowerShell ou as chamadas REST diretas. Para pesquisar IDs de permissão para o --api-permissions parâmetro, consulte a referência de permissão.

Solução de problemas comuns

Erros de "Consentimento necessário" ou "precisa de aprovação do administrador"

Esse erro ocorre quando o administrador não consentiu com as permissões de API no registro do aplicativo. Acesse registros> de aplicativo nas permissões da API do aplicativo > e selecione Conceder consentimento do administrador.

Como alternativa, execute:

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

Erros "O usuário não está atribuído a uma função para o aplicativo"

Esse erro significa que o aplicativo empresarial associado ao registro do aplicativo tem a atribuição de usuário necessária definida como Sim. Quando essa configuração estiver habilitada, somente usuários ou grupos atribuídos explicitamente ao aplicativo poderão entrar. Para corrigir esse erro, execute uma das seguintes ações:

• Acesseos aplicativos>Microsoft Entra ID> Enterprise e defina As Propriedades do aplicativo > e defina a Atribuição necessária como No.
• Adicione os usuários ou grupos de segurança relevantes em Usuários e grupos.

Políticas de acesso condicional bloqueando o acesso

Se sua organização aplicar políticas de acesso condicional, ela poderá bloquear a aquisição de token para o registro do aplicativo. As causas comuns incluem requisitos de conformidade do dispositivo, restrições de localização ou políticas baseadas em risco. Trabalhe com o administrador do Microsoft Entra para excluir o registro do aplicativo da política ou garantir que os clientes atendam aos requisitos de política.

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

Se a pesquisa da API do Power Platform por nome ou GUID na caixa de diálogo de permissões de API não retornar resultados, a entidade de serviço não será criada em seu locatário. Siga as etapas de atualização forçada na Etapa 2 para criá-la.

Autenticar com SDKs do Power Platform e PowerShell

Os exemplos a seguir mostram como autenticar e fazer uma chamada de API de exemplo usando cada SDK e PowerShell. Antes de executar esses exemplos, conclua as Etapas 1 a 3 anteriormente neste artigo para criar e configurar o registro do aplicativo.

Autenticação interativa (usuário delegado)

A autenticação interativa abre uma janela do navegador para o usuário entrar. Esse fluxo funciona melhor para scripts de desenvolvedor, ferramentas de administração e qualquer cenário em que um usuário 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 (entidade de serviço)

A autenticação de cliente confidencial usa um segredo ou certificado do cliente e não requer interação do usuário. Esse fluxo de autenticação é melhor 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 a entidades de serviço
Controle de acesso baseado em função para o Centro de administração do Power Platform
Referência de permissão