Authentication

Questo articolo offre una panoramica della configurazione di Microsoft Entra per chiamare l'API power platform. Per accedere alle risorse disponibili tramite l'API power platform, è necessario ottenere un token di connessione da Microsoft Entra e inviarlo come intestazione insieme a ogni richiesta. A seconda del tipo di identità supportato (utente e entità servizio) esistono diversi flussi per ottenere questo token di connessione, come descritto in questo articolo.

Per ottenere un token di connessione con le autorizzazioni corrette, completare i passaggi seguenti:

1. Creare una registrazione dell'applicazione nel tenant di Microsoft Entra
2. Configurare le autorizzazioni API
3. Configurare l'URI di piattaforma e reindirizzamento
4. (Facoltativo) Configurare certificati e segreti
5. Richiedere un token di accesso

Passaggio 1: Creare una registrazione dell'applicazione nel tenant di Microsoft Entra

1. Vai al portale di Azure .
2. Selezionare Microsoft Entra ID nella parte superiore della pagina. Selezionare quindi + Aggiungi>registrazione app.
3. Compilare la pagina Registra un'applicazione :
   1. Nome : assegnare all'applicazione un nome riconoscibile, ad esempio Power Platform Admin SDK.
   2. Tipi di account supportati: selezionare Solo tenant singolo: <nome> della società.
   3. URI di reindirizzamento : ignorare questa opzione per il momento. Configurarlo nel passaggio 3.
4. Selezionare Registra per creare l'applicazione. Al termine della registrazione, prendere nota dell'ID applicazione (client) e dell'ID directory (tenant) dalla pagina di panoramica. Entrambi i valori saranno necessari in un secondo momento.

È anche possibile creare la registrazione usando l'interfaccia della riga di comando di Azure:

az login

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

Il comando restituisce un oggetto JSON. Si noti il appId valore : questo valore è l'ID client.

Passaggio 2: Configurare autorizzazioni API

Nella registrazione della nuova app passare alla scheda Gestisci - Autorizzazioni API . Nella sezione Configura autorizzazioni selezionare Aggiungi un'autorizzazione. Nella finestra di dialogo selezionare la scheda API usate dall'organizzazione e quindi cercare l'API Power Platform. Potrebbero essere visualizzate diverse voci con un nome simile a questo, quindi assicurarsi di usare quello con il GUID 8578e004-a5c6-46e7-913e-12f58912df43.

Se l'API Power Platform non viene visualizzata nell'elenco durante la ricerca in base al GUID, potrebbe essere ancora possibile accedervi, ma la visibilità non viene aggiornata. Per forzare un aggiornamento, eseguire lo script seguente:

#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

Da qui selezionare le autorizzazioni necessarie. Queste autorizzazioni vengono raggruppate in base agli spazi dei nomi. All'interno di uno spazio dei nomi vengono visualizzati tipi di risorse e azioni, ad esempio AppManagement.ApplicationPackages.Read, che fornisce le autorizzazioni di lettura per i pacchetti dell'applicazione. Per altre informazioni, vedere l'articolo Informazioni di riferimento sulle autorizzazioni .

Dopo aver aggiunto le autorizzazioni necessarie all'applicazione, selezionare Concedi il consenso amministratore per completare l'installazione. Concedendo il consenso dell'amministratore, si autorizzano le autorizzazioni per tutti gli utenti nel tenant in modo che non vengano richieste con una finestra di dialogo di consenso interattivo la prima volta che usano l'app. Se si preferisce il consenso interattivo per utente, seguire Il flusso del codice di autorizzazione di Microsoft Identity Platform e OAuth 2.0.

È anche possibile concedere il consenso amministratore usando l'interfaccia della riga di comando di Azure:

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

Passaggio 3: Configurare l'URI di piattaforma e reindirizzamento

Gli SDK, gli script di PowerShell e le applicazioni desktop che eseguono l'autenticazione per conto di un utente richiedono un URI di reindirizzamento in modo che Microsoft Entra possa restituire i token all'applicazione dopo l'autenticazione.

1. Nella registrazione dell'app passare a Gestisci - Autenticazione.

2. Selezionare Aggiungi un URI di reindirizzamento, quindi scegliere Applicazioni per dispositivi mobili e desktop.

3. Selezionare l'URI di reindirizzamento predefinito seguente:

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

4. Selezionare Configura per salvare.

È anche possibile aggiungere l'URI di reindirizzamento usando l'interfaccia della riga di comando di 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

Impostazione client pubblica

Nella sezione Impostazioni avanzate nella stessa scheda Autenticazione è presente un interruttore Consenti flussi client pubblici . Impostare questa opzione su Sì solo se si prevede di usare il flusso ROPC (Resource Owner Password Credentials), che invia un nome utente e una password direttamente nel corpo della richiesta del token.

Questo flusso non funziona per gli account in cui è abilitata l'autenticazione a più fattori. Per i flussi di codice del browser o del dispositivo interattivi, non è necessario abilitare questa impostazione.

Passaggio 4: (Facoltativo) Configurare certificati e segreti

Se l'app richiede la lettura e la scrittura di risorse come se stessa, nota anche come entità servizio, esistono due modi per eseguire l'autenticazione. Per usare i certificati, passare a Gestisci - Certificati e segreti. Nella sezione Certificati caricare un certificato x509 che è possibile usare per l'autenticazione.

L'altro modo è usare la sezione Segreti per generare un segreto client. Salva il segreto in una posizione sicura per utilizzarlo secondo le esigenze di automazione. Le opzioni di certificato o segreto consentono di eseguire l'autenticazione con Microsoft Entra e ricevere un token per questo client, che viene passato alle API REST o ai cmdlet di PowerShell.

Passaggio 5: Richiedere un token di accesso

È possibile ottenere un token di connessione di accesso in due modi: uno per nome utente e password e l'altro per le entità servizio.

Flusso di nome utente e password

Assicurarsi di leggere la sezione client pubblica. Quindi, invia una richiesta POST tramite HTTP a Microsoft Entra ID con un payload nome utente e password.

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

L'esempio precedente contiene segnaposto che è possibile recuperare dall'applicazione client in Microsoft Entra ID. Si riceve una risposta che è possibile usare per effettuare chiamate successive all'API 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..."
}

Utilizza il valore access_token nelle chiamate successive all'API di Power Platform con l'intestazione HTTP Autorizzazione.

Flusso di entità servizio

Assicurarsi di leggere la sezione Configurare certificati e segreti . Quindi, invia una richiesta POST tramite HTTP a Microsoft Entra ID con un payload segreto client. Questo metodo di autenticazione viene spesso definito autenticazione dell'entità servizio.

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

L'esempio precedente contiene segnaposto che è possibile recuperare dall'applicazione client in Microsoft Entra ID. Si riceve una risposta che è possibile usare per effettuare chiamate successive all'API power platform.

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

Utilizza il valore access_token nelle chiamate successive all'API di Power Platform con l'intestazione HTTP Autorizzazione. Le autorizzazioni valide dell'entità servizio sono determinate dal ruolo controllo degli accessi in base al ruolo assegnato. Per informazioni su come assegnare un ruolo, vedere Esercitazione: Assegnare ruoli controllo degli accessi in base al ruolo alle entità servizio.

Avvio rapido con l'interfaccia della riga di comando di Azure

Lo script seguente crea una registrazione dell'app end-to-end. Eseguire ogni comando in ordine e sostituire i valori segnaposto con i propri.

# 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

Dopo aver eseguito questi comandi, è possibile usare la registrazione dell'app con gli SDK, PowerShell o le chiamate REST dirette. Per cercare gli ID di autorizzazione per il --api-permissions parametro, vedere informazioni di riferimento sull'autorizzazione.

Risoluzione dei problemi comuni

Errori di "consenso obbligatorio" o "richiede l'approvazione dell'amministratore"

Questo errore si verifica quando l'amministratore non ha concesso il consenso alle autorizzazioni API per la registrazione dell'app. Passare a Registrazioni app per le autorizzazioni dell'API> dell'app > e selezionare Concedi consenso amministratore.

In alternativa, esegui:

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

Errori "L'utente non è assegnato a un ruolo per l'applicazione"

Questo errore indica che l'applicazione aziendale associata alla registrazione dell'app ha l'assegnazione utente obbligatoria impostata su Sì. Quando questa impostazione è abilitata, solo gli utenti o i gruppi assegnati in modo esplicito all'applicazione possono accedere. Per correggere l'errore, eseguire una delle azioni seguenti:

• Passare alleapplicazioni>Microsoft Entra ID> Enterprise le proprietà dell'app > e impostare Assegnazione obbligatoria su No.
• Aggiungere gli utenti o i gruppi di sicurezza pertinenti in Utenti e gruppi.

Criteri di accesso condizionale che bloccano l'accesso

Se l'organizzazione applica criteri di accesso condizionale, potrebbero bloccare l'acquisizione dei token per la registrazione dell'app. Le cause comuni includono i requisiti di conformità dei dispositivi, le restrizioni di posizione o i criteri basati sui rischi. Collaborare con l'amministratore di Microsoft Entra per escludere la registrazione dell'app dai criteri o assicurarsi che i client soddisfino i requisiti dei criteri.

"API Power Platform" non trovata nella selezione API

Se la ricerca dell'API Power Platform per nome o GUID nella finestra di dialogo Autorizzazioni API non restituisce risultati, l'entità servizio non viene creata nel tenant. Seguire i passaggi di aggiornamento forzato nel passaggio 2 per crearlo.

Eseguire l'autenticazione con Gli SDK di Power Platform e PowerShell

Gli esempi seguenti illustrano come autenticare ed eseguire una chiamata API di esempio usando ogni SDK e PowerShell. Prima di eseguire questi esempi, completare i passaggi 1-3 precedenti in questo articolo per creare e configurare la registrazione dell'app.

Autenticazione interattiva (utente delegato)

L'autenticazione interattiva apre una finestra del browser per consentire all'utente di accedere. Questo flusso è ideale per gli script per sviluppatori, gli strumenti di amministrazione e qualsiasi scenario in cui è presente un utente.

# 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())

Client riservato (entità servizio)

L'autenticazione client riservata usa un segreto client o un certificato e non richiede l'interazione dell'utente. Questo flusso di autenticazione è ideale per servizi, pipeline e automazione in background.

$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())

Contenuti correlati

Esercitazione: Assegnare ruoli controllo degli accessi in base al ruolo alle entità servizio
Controllo degli accessi in base al ruolo per l'interfaccia di amministrazione di Power Platform
Informazioni di riferimento sulle autorizzazioni