Authentifizierung

Dieser Artikel enthält eine Übersicht über das Microsoft Entra-Setup zum Aufrufen der Power Platform-API. Um auf Ressourcen zuzugreifen, die über die Power Platform-API verfügbar sind, müssen Sie ein Bearertoken von Microsoft Entra abrufen und es zusammen mit jeder Anforderung als Header senden. Je nach dem Identitätstyp, den Sie unterstützen (Benutzer- und Dienstprinzipal), gibt es unterschiedliche Flüsse, um dieses Bearertoken abzurufen, wie in diesem Artikel beschrieben.

Führen Sie die folgenden Schritte aus, um ein Bearertoken mit den richtigen Berechtigungen abzurufen:

1. Erstellen einer Anwendungsregistrierung in Ihrem Microsoft Entra-Mandanten
2. Konfigurieren von API-Berechtigungen
3. Konfigurieren von Plattform- und Umleitungs-URI
4. (Optional) Konfigurieren von Zertifikaten und geheimen Schlüsseln
5. Anfordern eines Zugriffstokens

Schritt 1. Eine Anwendungsregistrierung in Ihrem Microsoft Entra-Mandanten erstellen

1. Öffnen Sie das Azure-Portal.
2. Wählen Sie oben auf der Seite die Microsoft Entra-ID aus. Wählen Sie dann +App-Registrierunghinzufügen> aus.
3. Füllen Sie die Seite "Anwendung registrieren" aus:
   1. Name – Geben Sie der Anwendung einen erkennbaren Namen, z. B. das Power Platform Admin SDK.
   2. Unterstützte Kontotypen – nur einzelner Mandant auswählen – <Firmenname>.
   3. Umleitungs-URI – Überspringen Sie dies vorerst. Sie konfigurieren sie in Schritt 3.
4. Wählen Sie Registrieren aus, um die Anwendung zu erstellen. Notieren Sie sich nach Abschluss der Registrierung die Anwendungs-ID (Client-ID) und die Verzeichnis-ID (Mandant) auf der Übersichtsseite . Sie benötigen später beide Werte.

Sie können die Registrierung auch mithilfe der Azure CLI erstellen:

az login

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

Der Befehl gibt ein JSON-Objekt zurück. Notieren Sie sich den appId Wert – dieser Wert ist Ihre Client-ID.

Schritt 2. API-Berechtigungen konfigurieren

Wechseln Sie in Ihrer neuen App-Registrierung zur Registerkarte "Verwalten – API-Berechtigungen" . Wählen Sie im Abschnitt "Berechtigungen konfigurieren " die Option "Berechtigung hinzufügen" aus. Wählen Sie im Dialogfeld die APIs aus, die meine Organisation verwendet , und suchen Sie dann nach der Power Platform-API. Möglicherweise werden mehrere Einträge mit einem ähnlichen Namen wie dieser angezeigt. Stellen Sie daher sicher, dass Sie die Einträge mit der GUID 8578e004-a5c6-46e7-913e-12f58912df43 verwenden.

Wenn die Power Platform-API bei der Suche nach GUID in der Liste nicht angezeigt wird, haben Sie möglicherweise weiterhin Zugriff darauf, aber die Sichtbarkeit wird nicht aktualisiert. Führen Sie das folgende Skript aus, um eine Aktualisierung zu erzwingen:

#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

Wählen Sie hier die erforderlichen Berechtigungen aus. Diese Berechtigungen werden nach Namespaces gruppiert. In einem Namespace werden Ressourcentypen und -aktionen wie AppManagement.ApplicationPackages.Read angezeigt, die Leseberechtigungen für Anwendungspakete erteilt. Weitere Informationen finden Sie im Berechtigungsreferenzartikel .

Nachdem Sie der Anwendung die erforderlichen Berechtigungen hinzugefügt haben, wählen Sie " Administratorzustimmung erteilen" aus , um das Setup abzuschließen. Durch die Erteilung der Administratorzustimmung autorisieren Sie die Berechtigungen für alle Benutzer im Mandanten, sodass sie bei der ersten Verwendung Ihrer App nicht mit einem interaktiven Zustimmungsdialogfeld aufgefordert werden. Wenn Sie die interaktive Zustimmung pro Benutzer bevorzugen, folgen Sie der Microsoft Identity Platform und dem OAuth 2.0-Autorisierungscodefluss.

Sie können der Administratorzustimmung auch mithilfe der Azure CLI erteilen:

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

Schritt 3. Konfigurieren von Plattform- und Umleitungs-URI

SDKs, PowerShell-Skripts und Desktopanwendungen, die sich im Namen eines Benutzers authentifizieren, erfordern einen Umleitungs-URI, sodass Microsoft Entra Token nach der Authentifizierung zurück an Ihre Anwendung zurückgeben kann.

1. Wechseln Sie in Ihrer App-Registrierung zu "Verwalten – Authentifizierung".

2. Wählen Sie "Umleitungs-URI hinzufügen" und dann "Mobile" und "Desktopanwendungen" aus.

3. Wählen Sie den folgenden integrierten Umleitungs-URI aus:

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

4. Wählen Sie "Konfigurieren" aus, um zu speichern.

Sie können den Umleitungs-URI auch mithilfe der Azure CLI hinzufügen:

# 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

Einstellung des öffentlichen Clients

Unter dem Abschnitt "Erweiterte Einstellungen " auf derselben Registerkarte " Authentifizierung " gibt es einen Umschalter für öffentliche Clientflüsse zulassen. Legen Sie diesen Umschalter nur auf "Ja " fest, wenn Sie beabsichtigen, den RoPC-Fluss (Resource Owner Password Credentials) zu verwenden, der einen Benutzernamen und ein Kennwort direkt im Textkörper der Tokenanforderung sendet.

Dieser Ablauf funktioniert nicht für Konten mit aktivierter mehrstufiger Authentifizierung. Für interaktive Browser- oder Gerätecodeflüsse müssen Sie diese Einstellung nicht aktivieren.

Schritt 4. (Optional) Konfigurieren von Zertifikaten und geheimen Schlüsseln

Wenn Ihre App Das Lesen und Schreiben von Ressourcen als selbst erfordert, auch als Dienstprinzipal bezeichnet, gibt es zwei Möglichkeiten zur Authentifizierung. Um Zertifikate zu verwenden, wechseln Sie zu "Verwalten – Zertifikate und geheime Schlüssel". Laden Sie im Abschnitt "Zertifikate " ein x509-Zertifikat hoch, das Sie zum Authentifizieren verwenden können.

Andernfalls können Sie den Abschnitt Geheimnisse verwenden, um einen geheimen Clientschlüssels zu generieren. Speichern Sie das Geheimnis an einem sicheren Ort, um es für Ihre Automatisierungsanforderungen zu verwenden. Mit den Zertifikat- oder geheimen Optionen können Sie sich bei Microsoft Entra authentifizieren und ein Token für diesen Client erhalten, das Sie entweder an die REST-APIs oder PowerShell-Cmdlets übergeben.

Schritt 5. Einen Zugriffstoken anfordern

Sie können ein Zugriffs bearertoken auf zwei Arten abrufen: eine Möglichkeit für Benutzername und Kennwort und die andere Möglichkeit ist für Dienstprinzipale.

„Benutzername und Kennwort“-Flow

Lesen Sie unbedingt den Abschnitt "Öffentlicher Client". Senden Sie dann eine POST-Anforderung über HTTP an Microsoft Entra ID mit einer Nutzlast aus Benutzername und Kennwort.

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

Das vorherige Beispiel enthält Platzhalter, die Sie aus Ihrer Clientanwendung in der Microsoft Entra-ID abrufen können. Sie erhalten eine Antwort, die Sie verwenden können, um nachfolgende Aufrufe an die Power Platform-API zu tätigen.

{
  "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..."
}

Verwenden Sie den Wert Zugriffstoken in nachfolgenden Aufrufen an die Power Platform-API mit der HTTP-Kopfzeile Genehmigung.

Dienstprinzipal-Flow

Lesen Sie unbedingt den Abschnitt "Zertifikate und geheime Schlüssel konfigurieren ". Senden Sie dann eine POST-Anforderung über HTTP an Microsoft Entra ID mit einer Nutzlast aus dem geheimen Clientschlüssel. Diese Authentifizierungsmethode wird häufig als Dienstprinzipalauthentifizierung bezeichnet.

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

Das vorherige Beispiel enthält Platzhalter, die Sie aus Ihrer Clientanwendung in der Microsoft Entra-ID abrufen können. Sie erhalten eine Antwort, die Sie verwenden können, um nachfolgende Aufrufe an die Power Platform-API zu tätigen.

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

Verwenden Sie den Wert Zugriffstoken in nachfolgenden Aufrufen an die Power Platform-API mit der HTTP-Kopfzeile Genehmigung. Die effektiven Berechtigungen des Dienstprinzipals werden durch die ihm zugewiesene RBAC-Rolle bestimmt. Informationen zum Zuweisen einer Rolle finden Sie im Lernprogramm: Zuweisen von RBAC-Rollen zu Dienstprinzipalen.

Schnellstart mit Azure CLI

Das folgende Skript erstellt eine End-to-End-App-Registrierung. Führen Sie jeden Befehl in der Reihenfolge aus, und ersetzen Sie Platzhalterwerte durch eigene Werte.

# 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

Nachdem Sie diese Befehle ausgeführt haben, können Sie ihre App-Registrierung mit den SDKs, PowerShell- oder direkten REST-Aufrufen verwenden. Informationen zum Nachschlagen von Berechtigungs-IDs für den --api-permissions Parameter finden Sie in der Berechtigungsreferenz.

Behandlung häufig auftretender Probleme

Fehler "Zustimmung erforderlich" oder "Administratorgenehmigung erforderlich"

Dieser Fehler tritt auf, wenn der Administrator den API-Berechtigungen für Ihre App-Registrierung nicht zugestimmt hat. Wechseln Sie zu App-Registrierungen> Ihrer App-API-Berechtigungen>, und wählen Sie "Administratorzustimmung erteilen" aus.

Führen Sie alternativ aus:

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

Fehler "Der Benutzer ist einer Rolle für die Anwendung nicht zugewiesen"

Dieser Fehler bedeutet, dass die Unternehmensanwendung, die Ihrer App-Registrierung zugeordnet ist, die Benutzerzuweisung auf"Ja" festgelegt ist. Wenn diese Einstellung aktiviert ist, können sich nur Benutzer oder Gruppen anmelden, die der Anwendung explizit zugewiesen sind. Führen Sie eine der folgenden Aktionen aus, um diesen Fehler zu beheben:

• Wechseln Sie zu Den Microsoft Entra ID Enterprise-Anwendungen>>, und> legen Sie "Zuordnung erforderlich" auf "Nein" fest.
• Fügen Sie die relevanten Benutzer oder Sicherheitsgruppen unter "Benutzer und Gruppen" hinzu.

Richtlinien für bedingten Zugriff, die den Zugriff blockieren

Wenn Ihre Organisation Richtlinien für bedingten Zugriff anwendet, blockieren sie möglicherweise den Tokenerwerb für Ihre App-Registrierung. Häufige Ursachen sind Gerätekompatibilitätsanforderungen, Standorteinschränkungen oder risikobasierte Richtlinien. Arbeiten Sie mit Ihrem Microsoft Entra-Administrator zusammen, um entweder Ihre App-Registrierung aus der Richtlinie auszuschließen, oder stellen Sie sicher, dass Clients die Richtlinienanforderungen erfüllen.

"Power Platform-API" wurde in der API-Auswahl nicht gefunden

Wenn die Suche nach der Power Platform-API anhand des Namens oder der GUID im Dialogfeld "API-Berechtigungen" keine Ergebnisse zurückgibt, wird der Dienstprinzipal nicht in Ihrem Mandanten erstellt. Führen Sie die Schritte zum Erzwingen der Aktualisierung in Schritt 2 aus, um sie zu erstellen.

Authentifizieren mit Power Platform-SDKs und PowerShell

Die folgenden Beispiele zeigen, wie Sie sich authentifizieren und einen Beispiel-API-Aufruf mithilfe der einzelnen SDK- und PowerShell-Aufrufe durchführen. Bevor Sie diese Beispiele ausführen, führen Sie die Schritte 1 bis 3 weiter oben in diesem Artikel aus, um Ihre App-Registrierung zu erstellen und zu konfigurieren.

Interaktive Authentifizierung (delegierter Benutzer)

Die interaktive Authentifizierung öffnet ein Browserfenster, in dem sich der Benutzer anmelden kann. Dieser Ablauf eignet sich am besten für Entwicklerskripts, Administratortools und jedes Szenario, in dem ein Benutzer vorhanden ist.

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

Vertraulicher Client (Dienstprinzipal)

Die vertrauliche Clientauthentifizierung verwendet einen geheimen Clientschlüssel oder ein Zertifikat und erfordert keine Benutzerinteraktion. Dieser Authentifizierungsfluss eignet sich am besten für Hintergrunddienste, Pipelines und Automatisierung.

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

Verwandte Inhalte

Lernprogramm: Zuweisen von RBAC-Rollen zu Dienstprinzipale
Rollenbasierte Zugriffssteuerung für das Power Platform Admin Center
Berechtigungsreferenz