Authentication

Ez a cikk áttekintést nyújt a Power Platform API meghívására szolgáló Microsoft Entra beállításról. A Power Platform API-val elérhető erőforrások eléréséhez le kell kérnie egy tulajdonosi jogkivonatot a Microsoft Entra-tól, és fejlécként kell elküldenie azokat az egyes kérésekkel együtt. A támogatott identitástípustól függően (a felhasználó és a szolgáltatásnév) különböző folyamatokkal szerezheti be ezt a tulajdonosi jogkivonatot a jelen cikkben leírtak szerint.

A megfelelő engedélyekkel rendelkező tulajdonosi jogkivonat beszerzéséhez hajtsa végre a következő lépéseket:

1. Alkalmazásregisztráció létrehozása a Microsoft Entra-bérlőben
2. API-engedélyek konfigurálása
3. Platform konfigurálása és átirányítási URI
4. (Nem kötelező) Tanúsítványok és titkos kódok konfigurálása
5. Hozzáférési jogkivonat kérése

1. lépés. Alkalmazásregisztráció létrehozása a Microsoft Entra bérlőben

1. Nyissa meg az Azure Portalt.
2. Válassza a Microsoft Entra-azonosítót a lap tetején. Ezután válassza a +Alkalmazásregisztráció> lehetőséget.
3. Töltse ki az Alkalmazás regisztrálása lapot:
   1. Név – Adjon egy felismerhető nevet az alkalmazásnak, például a Power Platform felügyeleti SDK-jának.
   2. Támogatott fióktípusok – Csak egy bérlő kiválasztása – <a vállalat neve>.
   3. Átirányítási URI – Ezt egyelőre hagyja ki. Ezt a 3. lépésben konfigurálhatja.
4. Válassza a Regisztráció lehetőséget az alkalmazás létrehozásához. A regisztráció befejezése után jegyezze fel az alkalmazás (ügyfél) azonosítóját és a címtár (bérlő) azonosítóját az áttekintési oldalról – később mindkét értékre szüksége lesz.

A regisztrációt az Azure CLI használatával is létrehozhatja:

az login

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

A parancs egy JSON-objektumot ad vissza. Jegyezze fel az appId értéket – ez az ügyfélazonosító.

2. lépés. API-engedélyek konfigurálása

Az új alkalmazásregisztrációban lépjen a Kezelés – API Engedélyek lapra . Az Engedélyek konfigurálása szakaszban válassza az Engedély hozzáadása lehetőséget. A párbeszédpanelen válassza ki a szervezet által használt API-kat , majd keresse meg a Power Platform API-t. Több, ehhez hasonló nevű bejegyzést is láthat, ezért ügyeljen arra, hogy a GUID 8578e004-a5c6-46e7-913e-12f58912df43 azonosítójú bejegyzést használja.

Ha nem látja a Power Platform API-t a listában a GUID-alapú kereséskor, előfordulhat, hogy továbbra is rendelkezik hozzáféréssel, de a láthatóság nem frissül. Frissítés kényszerítéséhez futtassa a következő szkriptet:

PowerShell

#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"

Azure CLI-

az login

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

Innen válassza ki a szükséges engedélyeket. Ezek az engedélyek névterek szerint vannak csoportosítva. A névtéren belül megjelennek az erőforrástípusok és műveletek, például az AppManagement.ApplicationPackages.Read, amely olvasási engedélyeket biztosít az alkalmazáscsomagokhoz. További információkért tekintse meg az Engedély hivatkozási cikket.

Megjegyzés:

A Power Platform API jelenleg csak delegált engedélyeket használ. Felhasználói környezettel futtatott alkalmazások esetén delegált engedélyeket kérhet a hatókörparaméter használatával. Ezek az engedélyek delegálják a bejelentkezett felhasználó jogosultságait az alkalmazásnak, hogy felhasználóként működjenek a Power Platform API-végpontok hívása során.

Szolgáltatásnév-identitások esetén ne használjon alkalmazásengedélyeket. Ehelyett az alkalmazásregisztráció létrehozása után rendeljen hozzá egy RBAC-szerepkört a hatókörön belüli engedélyek (például Közreműködő vagy Olvasó) megadásához. További információ : Oktatóanyag: RBAC-szerepkörök hozzárendelése szolgáltatásnevekhez.

Miután hozzáadta a szükséges engedélyeket az alkalmazáshoz, válassza a rendszergazdai hozzájárulás megadása lehetőséget a telepítés befejezéséhez. A rendszergazdai hozzájárulás megadásával engedélyezi a bérlő összes felhasználójának engedélyeit, így az alkalmazás első használatakor nem kapnak interaktív hozzájárulási párbeszédpanelt. Ha felhasználónként interaktív hozzájárulást szeretne, kövesse a Microsoft identitásplatformját és az OAuth 2.0 engedélyezési kód folyamatát.

Rendszergazdai hozzájárulást az Azure CLI használatával is megadhat:

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

3. lépés. Platform konfigurálása és átirányítási URI

A felhasználó nevében hitelesítést végző SDK-k, PowerShell-szkriptek és asztali alkalmazások átirányítási URI-t igényelnek, hogy a Microsoft Entra a hitelesítés után vissza tudja adni a jogkivonatokat az alkalmazásnak.

1. Az alkalmazásregisztráción belül válassza a Kezelés – Hitelesítés lehetőséget.

2. Válassza az Átirányítási URI hozzáadása, majd a Mobil és asztali alkalmazások lehetőséget.

3. Válassza ki a következő beépített átirányítási URI-t:

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

4. Válassza a Konfigurálás a mentéshez lehetőséget.

Az átirányítási URI-t az Azure CLI használatával is hozzáadhatja:

# 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

Nyilvános ügyfél beállítása

A Hitelesítés lap Speciális beállítások szakaszában a Nyilvános ügyfélfolyamatok engedélyezése kapcsoló van bekapcsolva. Ezt a kapcsolót csak akkor állítsa Igen értékre, ha az erőforrás-tulajdonosi jelszó hitelesítő adatait (ROPC) szeretné használni, amely felhasználónevet és jelszót küld közvetlenül a jogkivonat-kérelem törzsében.

Ez a folyamat nem működik a többtényezős hitelesítést engedélyező fiókok esetében. Az interaktív böngésző- vagy eszközkódfolyamatokhoz nem kell engedélyeznie ezt a beállítást.

4. lépés. (Nem kötelező) Tanúsítványok és titkos kódok konfigurálása

Ha az alkalmazásnak szüksége van az erőforrások olvasására és írására, más néven szolgáltatásnévre, kétféleképpen hitelesíthető. A tanúsítványok használatához lépjen a Kezelés – Tanúsítványok és titkos kódok elemre. A Tanúsítványok szakaszban töltsön fel egy x509-tanúsítványt, amelyet hitelesítésre használhat.

Másik lehetőségként használhatja a Titkos kódok szakaszt a titkos ügyfélkód létrehozásához. Mentse a titkos kódot biztonságos helyre az automatizálási szükségletek használatához. A tanúsítvány- vagy titkos kódbeállítások lehetővé teszik a Microsoft Entra hitelesítését, és jogkivonatot kap az ügyfélhez, amelyet a REST API-knak vagy a PowerShell-parancsmagoknak ad át.

5. lépés Hozzáférési jogkivonat kérése

A hozzáférési jogkivonat kétféleképpen szerezhető be: az egyik a felhasználónév és a jelszó, a másik pedig a szolgáltatásnevek.

Felhasználónév és jelszó folyamat

Mindenképpen olvassa el a nyilvános ügyfél szakaszt. Ezután küldjön egy POST kérést HTTP-n keresztül az azonosítóhoz Microsoft Entra felhasználónévvel és jelszóval hasznos adatokkal.

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

Az előző példa helyőrzőket tartalmaz, amelyeket lekérhet az ügyfélalkalmazásból a Microsoft Entra ID-ban. Olyan választ kap, amellyel további hívásokat indíthat a Power Platform API-ba.

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

Használja az access_token értéket a Power Platform API-ba irányuló későbbi hívásokban a Hitelesítés HTTP-fejléccel.

Egyszerű szolgáltatásnév folyamata

Mindenképpen olvassa el a Tanúsítványok és titkos kódok konfigurálása szakaszt. Ezután küldjön egy POST kérést HTTP-n keresztül egy Microsoft Entra titkos ügyfélkulcs hasznos adatával. Ezt a hitelesítési módszert gyakran egyszerű szolgáltatáshitelesítésnek is nevezik.

Important

A szolgáltatásnév-hitelesítés használata előtt végezze el a jelen cikk 1–4. lépését az alkalmazásregisztráció tanúsítványsal vagy titkos ügyfélkóddal való létrehozásához és konfigurálásához. Ezután rendeljen hozzá egy RBAC-szerepkört a szolgáltatásnévhez a hozzáférés szintjének szabályozásához. További információ : Oktatóanyag: RBAC-szerepkörök hozzárendelése szolgáltatásnevekhez.

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

Az előző példa helyőrzőket tartalmaz, amelyeket lekérhet az ügyfélalkalmazásból a Microsoft Entra ID-ban. Olyan választ kap, amellyel további hívásokat indíthat a Power Platform API-ba.

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

Használja az access_token értéket a Power Platform API-ba irányuló későbbi hívásokban a Hitelesítés HTTP-fejléccel. A szolgáltatásnév érvényes engedélyeit a hozzá rendelt RBAC-szerepkör határozza meg. A szerepkörök hozzárendeléséről a következő oktatóanyagban olvashat: RBAC-szerepkörök hozzárendelése szolgáltatásnevekhez.

Rövid útmutató az Azure CLI-vel

A következő szkript végpontok közötti alkalmazásregisztrációt hoz létre. Futtassa az egyes parancsokat sorrendben, és cserélje le a helyőrző értékeket a sajátjára.

# 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

A parancsok futtatása után használhatja az alkalmazásregisztrációt az SDK-kkal, a PowerShell-lel vagy a közvetlen REST-hívásokkal. A paraméter engedélyazonosítóinak kereséséhez --api-permissions tekintse meg az Engedély referenciát.

Gyakori problémák megoldása

"Hozzájárulás szükséges" vagy "rendszergazdai jóváhagyás szükséges" hibaüzenetek

Ez a hiba akkor fordul elő, ha a rendszergazda nem járult hozzá az alkalmazásregisztráció API-engedélyéhez. Nyissa meg az alkalmazásregisztrációkat az alkalmazás >> között, és válassza a Rendszergazdai hozzájárulás megadása lehetőséget.

Alternatívaként futtassa:

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

"A felhasználó nincs hozzárendelve az alkalmazás szerepköréhez" hibaüzenetek

Ez a hiba azt jelenti, hogy az alkalmazásregisztrációhoz társított vállalati alkalmazás felhasználói hozzárendeléseigen értékre van állítva. Ha ez a beállítás engedélyezve van, csak az alkalmazáshoz explicit módon hozzárendelt felhasználók vagy csoportok jelentkezhetnek be. A hiba kijavításához hajtsa végre az alábbi műveletek egyikét:

• Nyissa meg a Microsoft Entra ID>Enterprise-alkalmazásokat> az alkalmazás >tulajdonságai között, és adja meg a Nem értékre kötelező hozzárendelést.
• Adja hozzá a megfelelő felhasználókat vagy biztonsági csoportokat a Felhasználók és csoportok csoportban.

A hozzáférést letiltó feltételes hozzáférési szabályzatok

Ha a szervezet feltételes hozzáférési szabályzatokat alkalmaz, letilthatják az alkalmazásregisztráció jogkivonat-beszerzését. A gyakori okok közé tartoznak az eszközmegfelelési követelmények, a helykorlátozások vagy a kockázatalapú szabályzatok. A Microsoft Entra rendszergazdájával együttműködve zárja ki az alkalmazásregisztrációt a szabályzatból, vagy győződjön meg arról, hogy az ügyfelek megfelelnek a szabályzat követelményeinek.

A "Power Platform API" nem található az API-választóban

Ha a Power Platform API név vagy GUID alapján történő keresése az API-engedélyek párbeszédpanelen nem ad eredményül, a szolgáltatásnév nem jön létre a bérlőben. A létrehozáshoz kövesse a 2. lépés kényszerítő frissítési lépéseit.

Hitelesítés Power Platform SDK-kkal és PowerShell-lel

Az alábbi példák bemutatják, hogyan hitelesíthet és kezdeményezhet minta API-hívásokat az egyes SDK-k és PowerShell-lel. A példák futtatása előtt végezze el a jelen cikk 1–3. lépését az alkalmazásregisztráció létrehozásához és konfigurálásához.

Interaktív hitelesítés (delegált felhasználó)

Az interaktív hitelesítés megnyitja a böngészőablakot, amelyben a felhasználó bejelentkezhet. Ez a folyamat a legjobban használható fejlesztői szkriptekhez, rendszergazdai eszközökhöz és minden olyan forgatókönyvhöz, ahol egy felhasználó jelen van.

PowerShell

# 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

C# SDK

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}");
}

Python SDK

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

Bizalmas ügyfél (szolgáltatásnév)

A bizalmas ügyfélhitelesítés ügyféltitkot vagy tanúsítványt használ, és nem igényel felhasználói beavatkozást. Ez a hitelesítési folyamat a legjobb háttérszolgáltatásokhoz, folyamatokhoz és automatizáláshoz.

Important

A szolgáltatásnév-hitelesítés használata előtt végezze el a fenti 1–4. lépést az alkalmazásregisztráció tanúsítványsal vagy ügyféltitkosítással való létrehozásához és konfigurálásához. Ezután rendeljen hozzá egy RBAC-szerepkört a szolgáltatásnévhez a hozzáférés szintjének szabályozásához. További információ: Oktatóanyag: RBAC-szerepkörök hozzárendelése szolgáltatásnevekhez.

PowerShell

$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

C# SDK

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}");
}

Python SDK

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

Kapcsolódó tartalom

Oktatóanyag: RBAC-szerepkörök hozzárendelése szolgáltatásnevekhez
Szerepköralapú hozzáférés-vezérlés a Power Platform Felügyeleti központhoz
Engedélyhivatkozás