Authenticatie

Dit artikel bevat een overzicht van de Installatie van Microsoft Entra voor het aanroepen van Power Platform-API. Als u toegang wilt krijgen tot resources die beschikbaar zijn via de Power Platform-API, moet u een bearer-token van Microsoft Entra ophalen en verzenden als header samen met elke aanvraag. Afhankelijk van het identiteitstype dat u ondersteunt (gebruiker versus service-principal) zijn er verschillende stromen om dit Bearer-token te verkrijgen, zoals beschreven in dit artikel.

Voer de volgende stappen uit om een Bearer-token met de juiste machtigingen te verkrijgen:

1. Een toepassingsregistratie maken in uw Microsoft Entra-tenant
2. API-machtigingen configureren
3. Platform en omleidings-URI configureren
4. (Optioneel) Certificaten en geheimen configureren
5. Een toegangstoken aanvragen

Stap 1. Een toepassingsregistratie maken in uw Microsoft Entra-tenant

1. Ga naar de Azure-portal.
2. Selecteer Microsoft Entra-id boven aan de pagina. Selecteer vervolgens +App-registratie toevoegen>.
3. Vul de pagina Een toepassing registreren in:
   1. Naam : geef de toepassing een herkenbare naam, zoals de Power Platform Admin SDK.
   2. Ondersteunde accounttypen : selecteer alleen één tenant- <uw bedrijfsnaam>.
   3. Omleidings-URI : sla dit voorlopig over. U configureert deze in stap 3.
4. Selecteer Registreren om de toepassing te maken. Nadat de registratie is voltooid, noteert u de id van de toepassing (client) en de map-id (tenant) op de overzichtspagina. U hebt beide waarden later nodig.

U kunt de registratie ook maken met behulp van Azure CLI:

az login

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

De opdracht retourneert een JSON-object. Let op de appId waarde: deze waarde is uw client-id.

Stap 2. API-machtigingen configureren

Ga in de nieuwe app-registratie naar het tabblad Beheren - API-machtigingen . Selecteer onder de sectie Machtigingen configureren de optie Een machtiging toevoegen. Selecteer in het dialoogvenster de API's die mijn organisatie gebruikt en zoek vervolgens naar de Power Platform-API. Mogelijk ziet u verschillende vermeldingen met een naam die vergelijkbaar is met deze, dus zorg ervoor dat u de vermelding gebruikt met de GUID 8578e004-a5c6-46e7-913e-12f58912df43.

Als u de Power Platform-API niet in de lijst ziet wanneer u zoekt op GUID, hebt u er mogelijk nog steeds toegang toe, maar wordt de zichtbaarheid niet vernieuwd. Voer het volgende script uit om een vernieuwing af te dwingen:

#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

Selecteer hier de machtigingen die u nodig hebt. Deze machtigingen worden gegroepeerd op naamruimten. In een naamruimte ziet u resourcetypen en acties, zoals AppManagement.ApplicationPackages.Read, die leesmachtigingen biedt voor toepassingspakketten. Zie het artikel Machtigingsreferentie voor meer informatie.

Nadat u de vereiste machtigingen aan de toepassing hebt toegevoegd, selecteert u Beheerderstoestemming verlenen om de installatie te voltooien. Door beheerderstoestemming te verlenen, autoriseert u de machtigingen voor alle gebruikers in de tenant, zodat ze niet worden gevraagd om een interactief toestemmingsdialoogvenster wanneer ze uw app voor het eerst gebruiken. Als u de voorkeur geeft aan interactieve toestemming per gebruiker, volgt u het Microsoft Identity Platform en de OAuth 2.0-autorisatiecodestroom.

U kunt ook beheerderstoestemming verlenen met behulp van Azure CLI:

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

Stap 3. Platform en omleidings-URI configureren

SDK's, PowerShell-scripts en bureaubladtoepassingen die namens een gebruiker worden geverifieerd, vereisen een omleidings-URI, zodat Microsoft Entra tokens na verificatie kan retourneren naar uw toepassing.

1. Ga in uw app-registratie naar Beheren - Verificatie.

2. Selecteer Een omleidings-URI toevoegenen kies vervolgens Mobiele en bureaubladtoepassingen.

3. Selecteer de volgende ingebouwde omleidings-URI:

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

4. Selecteer Configureren om op te slaan.

U kunt de omleidings-URI ook toevoegen met behulp van 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

Instelling van openbare client

In de sectie Geavanceerde instellingen op hetzelfde tabblad Verificatie staat u de wisselknop Openbare clientstromen toestaan . Stel deze wisselknop alleen in op Ja als u van plan bent om de ROPC-stroom (Password Credentials) van de resource-eigenaar te gebruiken, waarmee een gebruikersnaam en wachtwoord rechtstreeks in de hoofdtekst van de tokenaanvraag worden verzonden.

Deze stroom werkt niet voor accounts waarvoor meervoudige verificatie is ingeschakeld. Voor interactieve browser- of apparaatcodestromen hoeft u deze instelling niet in te schakelen.

Stap 4. (Optioneel) Certificaten en geheimen configureren

Als uw app lees- en schrijfbronnen als zichzelf vereist, ook wel een service-principal genoemd, zijn er twee manieren om te verifiëren. Als u certificaten wilt gebruiken, gaat u naar Beheren - Certificaten en geheimen. Upload in de sectie Certificaten een x509-certificaat dat u kunt gebruiken om te verifiëren.

De andere manier is om de sectie Geheimen te gebruiken om een clientgeheim te genereren. Bewaar het geheim op een veilige locatie voor gebruik bij uw automatiseringsbehoeften. Met de certificaat- of geheime opties kunt u zich verifiëren bij Microsoft Entra en een token ontvangen voor deze client, die u doorgeeft aan de REST API's of PowerShell-cmdlets.

Stap 5. Een toegangstoken aanvragen

U kunt op twee manieren een bearer-token voor toegang verkrijgen: een manier is voor gebruikersnaam en wachtwoord, en de andere manier is voor service-principals.

Gebruikersnaam en wachtwoord-stroom

Zorg ervoor dat u de sectie openbare client leest. Stuur dan een POST-aanvraag via HTTP naar Microsoft Entra ID met een nettolading gebruikersnaam en wachtwoord.

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

Het voorgaande voorbeeld bevat tijdelijke aanduidingen die u kunt ophalen uit uw clienttoepassing in Microsoft Entra-id. U ontvangt een antwoord dat u kunt gebruiken om volgende aanroepen naar de Power Platform-API uit te voeren.

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

Gebruik de toegangstoken-waarde in volgende aanroepen naar de Power Platform-API met behulp van de HTTP-header Autorisatie.

Service Principal-stroom

Lees de sectie Certificaten en geheimen configureren . Stuur dan een POST-aanvraag via HTTP naar Microsoft Entra met een clientgeheim-nettolading. Deze verificatiemethode wordt vaak service-principalverificatie genoemd.

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

Het voorgaande voorbeeld bevat tijdelijke aanduidingen die u kunt ophalen uit uw clienttoepassing in Microsoft Entra-id. U ontvangt een antwoord dat u kunt gebruiken om volgende aanroepen naar de Power Platform-API uit te voeren.

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

Gebruik de toegangstoken-waarde in volgende aanroepen naar de Power Platform-API met behulp van de HTTP-header Autorisatie. De effectieve machtigingen van de service-principal worden bepaald door de RBAC-rol die eraan is toegewezen. Zie Zelfstudie: RBAC-rollen toewijzen aan service-principals voor meer informatie over het toewijzen van een rol.

Snel aan de slag met Azure CLI

Met het volgende script wordt een end-to-end app-registratie gemaakt. Voer elke opdracht in volgorde uit en vervang tijdelijke aanduidingen door uw eigen waarden.

# 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

Nadat u deze opdrachten hebt uitgevoerd, kunt u uw app-registratie gebruiken met de SDK's, PowerShell of directe REST-aanroepen. Als u machtigings-id's voor de --api-permissions parameter wilt opzoeken, raadpleegt u de machtigingsreferentie.

Veelvoorkomende problemen oplossen

Fouten 'Toestemming vereist' of 'vereist goedkeuring door beheerder'

Deze fout treedt op wanneer de beheerder geen toestemming heeft gegeven voor de API-machtigingen voor uw app-registratie. Ga naar App-registraties> voor uw app-API-machtigingen> en selecteer Beheerderstoestemming verlenen.

U kunt ook het volgende uitvoeren:

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

Fouten 'Gebruiker is niet toegewezen aan een rol voor de toepassing'

Deze fout betekent dat voor de bedrijfstoepassing die is gekoppeld aan uw app-registratie , gebruikerstoewijzing is ingesteld op Ja. Wanneer deze instelling is ingeschakeld, kunnen alleen gebruikers of groepen die expliciet zijn toegewezen aan de toepassing zich aanmelden. Voer een van de volgende acties uit om deze fout op te lossen:

• Ga naar Microsoft Entra ID>Enterprise-toepassingen> voor uw app-eigenschappen> en stel toewijzing in opNee.
• Voeg de relevante gebruikers of beveiligingsgroepen toe onder Gebruikers en groepen.

Beleid voor voorwaardelijke toegang blokkeert de toegang

Als uw organisatie beleid voor voorwaardelijke toegang toepast, kunnen ze het verkrijgen van tokens voor uw app-registratie blokkeren. Veelvoorkomende oorzaken zijn nalevingsvereisten voor apparaten, locatiebeperkingen of beleid op basis van risico's. Neem contact op met uw Microsoft Entra-beheerder om uw app-registratie uit te sluiten van het beleid of ervoor te zorgen dat clients voldoen aan de beleidsvereisten.

'Power Platform-API' is niet gevonden in de API-kiezer

Als u zoekt naar Power Platform-API op naam of GUID in het dialoogvenster API-machtigingen, worden er geen resultaten geretourneerd, wordt de service-principal niet gemaakt in uw tenant. Volg de stappen voor geforceerd vernieuwen in stap 2 om deze te maken.

Verifiëren met Power Platform SDK's en PowerShell

In de volgende voorbeelden ziet u hoe u een voorbeeld-API-aanroep kunt uitvoeren en verifiëren met behulp van elke SDK en PowerShell. Voordat u deze voorbeelden uitvoert, voert u stap 1-3 eerder in dit artikel uit om uw app-registratie te maken en te configureren.

Interactieve verificatie (gedelegeerde gebruiker)

Interactieve verificatie opent een browservenster waarin de gebruiker zich kan aanmelden. Deze stroom werkt het beste voor ontwikkelaarsscripts, beheerhulpprogramma's en elk scenario waarin een gebruiker aanwezig is.

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

Vertrouwelijke client (service-principal)

Vertrouwelijke clientverificatie maakt gebruik van een clientgeheim of -certificaat en vereist geen gebruikersinteractie. Deze verificatiestroom is het beste voor achtergrondservices, pijplijnen en automatisering.

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

Verwante inhoud

Zelfstudie: RBAC-rollen toewijzen aan service-principals
Op rollen gebaseerd toegangsbeheer voor power platform-beheercentrum
Machtigingsreferentie