Todentaminen

Tässä artikkelissa on yleiskatsaus Microsoft Entran määrityksestä Power Platform -ohjelmointirajapinnan kutsumista varten. Jotta voit käyttää Power Platform -ohjelmointirajapinnan kautta käytettävissä olevia resursseja, sinun on hankittava haltijatunnus Microsoft Entralta ja lähetettävä se otsikkona kunkin pyynnön yhteydessä. Tukemasi käyttäjätietotyypin (käyttäjä ja palvelun päänimi) mukaan tämän haltijatunnuksen hankkimiseen on erilaisia työnkulkuja, kuten tässä artikkelissa kerrotaan.

Jos haluat haltijatunnuksen, jolla on oikeat käyttöoikeudet, suorita seuraavat vaiheet:

1. Sovelluksen rekisteröinnin luominen Microsoft Entra -vuokraajassa
2. Ohjelmointirajapinnan käyttöoikeuksien määrittäminen
3. Määritä käyttöympäristö ja ohjaa URI-osoite uudelleen
4. (Valinnainen) Varmenteiden ja salaisten koodien määrittäminen
5. Käyttöoikeustietueen pyytäminen

Vaihe 1. Luo sovellusrekisteröinti Microsoft Entra -vuokraajassa

1. Siirry Azure-portaaliin.
2. Valitse Microsoft Entra ID sivun yläreunasta. Valitse sitten + Lisää>sovelluksen rekisteröinti.
3. Täytä Sovelluksen rekisteröiminen -sivu:
   1. Nimi – Anna sovellukselle tunnistettava nimi, kuten Power Platform Admin SDK.
   2. Tuetut tilityypit – Valitse vain yksittäinen vuokraaja – <yrityksesi nimi>.
   3. Uudelleenohjauksen URI – Ohita tämä toistaiseksi. Voit määrittää sen vaiheessa 3.
4. Luo sovellus valitsemalla Rekisteröi . Kun rekisteröinti on valmis, huomaa Yleiskatsaus-sivulta Sovelluksen (asiakasohjelman) tunnus ja Hakemiston (vuokraajan) tunnus – tarvitset molemmat arvot myöhemmin.

Voit luoda rekisteröinnin myös azure-komentorivikäyttöliittymän avulla:

az login

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

Komento palauttaa JSON-objektin. appId Huomaa arvo – tämä arvo on asiakastunnuksesi.

Vaihe 2. API-oikeuksien määritys

Siirry uuden sovelluksen rekisteröinnissä Hallinta – ohjelmointirajapinnan käyttöoikeudet -välilehteen . Valitse Määritä käyttöoikeudet -osiossa Lisää käyttöoikeus. Valitse valintaikkunassa organisaationi käyttämät ohjelmointirajapinnat -välilehti ja etsi sitten Power Platform -ohjelmointirajapinta. Saatat nähdä useita merkintöjä, joiden nimi on tämän kaltainen, joten varmista, että käytät sitä, jonka GUID-tunnus on 8578e004-a5c6-46e7-913e-12f58912df43.

Jos luettelossa ei näy Power Platform -ohjelmointirajapintaa GUID-tunnuksen perusteella, voit ehkä edelleen käyttää sitä, mutta näkyvyyttä ei päivitetä. Jos haluat pakottaa päivityksen, suorita seuraava komentosarja:

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"

az login

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

Valitse täältä tarvitsemasi käyttöoikeudet. Nämä käyttöoikeudet on ryhmitelty Nimitilat-kohdan mukaan. Nimitilassa näet resurssityypit ja toiminnot, kuten AppManagement.ApplicationPackages.Read, joka antaa sovelluspakettien lukuoikeudet. Lisätietoja on artikkelissa Käyttöoikeusviittaus .

Muistiinpano

Power Platform -ohjelmointirajapinta käyttää delegoituja käyttöoikeuksia vain tällä hetkellä. Jos sovellus käyttää käyttäjäkontekstia, pyydä delegoituja käyttöoikeuksia vaikutusalueparametrin avulla. Nämä oikeudet delegoivat kirjautuneen käyttäjän oikeudet sovellukseesi, jotta se voi toimia käyttäjänä kutsuessaan Power Platform -ohjelmointirajapinnan päätepisteitä.

Älä käytä palvelun päänimen käyttäjätietoja sovellusten käyttöoikeuksilla. Kun olet luonut sovelluksen rekisteröinnin, määritä sille sen sijaan RBAC-rooli, joka myöntää vaikutusalueen käyttöoikeudet (kuten Osallistuja tai Lukija). Lisätietoja on artikkelissa Opetusohjelma: RBAC-roolien määrittäminen palvelun päänimille.

Kun olet lisännyt tarvittavat käyttöoikeudet sovellukseen, valitse Myönnä järjestelmänvalvojan suostumus määrityksen suorittamiseksi. Myöntämällä järjestelmänvalvojan suostumuksen valtuutat käyttöoikeudet kaikille vuokraajan käyttäjille, jotta heille ei kysytä vuorovaikutteista suostumusvalintaikkunaa, kun he käyttävät sovellustasi ensimmäistä kertaa. Jos haluat käyttäjäkohtaisen vuorovaikutteisen suostumuksen, noudata Microsoftin käyttäjätietoympäristöä ja OAuth 2.0 -valtuutuskoodin työnkulkua.

Voit myös antaa järjestelmänvalvojan suostumuksen AzureN komentorivikäyttöliittymän avulla:

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

Vaihe 3. Määritä käyttöympäristö ja ohjaa URI-osoite uudelleen

SDK:t, PowerShell-komentosarjat ja käyttäjän puolesta todennettavat työpöytäsovellukset edellyttävät uudelleenohjauksen URI-osoitetta, jotta Microsoft Entra voi palauttaa tunnukset takaisin sovellukseesi todentamisen jälkeen.

1. Siirry sovelluksen rekisteröinnissä kohtaan Hallitse – todentaminen.

2. Valitse Lisää uudelleenohjauksen URI-osoite ja valitse sitten Mobiili- ja työpöytäsovellukset.

3. Valitse seuraava sisäinen uudelleenohjauksen URI:

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

4. Tallenna valitsemalla Määritä .

Voit lisätä uudelleenohjauksen URI:n myös käyttämällä Azuren komentorivikäyttöliittymää:

# 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

Julkisen asiakkaan asetus

Saman Todennus-välilehdenLisäasetukset-osassa on Salli julkisten asiakastyönkulkujen vaihtopainike. Määritä tämän vaihtopainikkeen arvoksi Kyllä vain, jos aiot käyttää resource owner password credentials (ROPC) -työnkulkua, joka lähettää käyttäjänimen ja salasanan suoraan tunnuspyynnön leipätekstissä.

Tämä työnkulku ei toimi tileillä, joissa on käytössä monimenetelmäinen todentaminen. Vuorovaikutteisissa selain- tai laitekoodityönkuluissa tätä asetusta ei tarvitse ottaa käyttöön.

Vaihe 4. (Valinnainen) Varmenteiden ja salaisten koodien määrittäminen

Jos sovelluksesi edellyttää resurssien lukemista ja kirjoittamista sellaisenaan, eli palvelun päänimeä, todentamiseen on kaksi tapaa. Jos haluat käyttää varmenteita, siirry kohtaan Varmenteiden ja salaisten koodien hallinta. Lataa Varmenteet-osiossa x509-varmenne, jota voit käyttää todentamiseen.

Voit myös luoda asiakassalaisuuden Salaisuudet-osassa. Tallenna salainen koodi turvalliseen paikkaan automaattisia toimintoja varten. Varmenteen tai salaisen koodin asetusten avulla voit todentautua Microsoft Entran avulla ja vastaanottaa asiakkaalle tunnuksen, jonka voit välittää joko REST-ohjelmointirajapintoihin tai PowerShellin cmdlet-komentoihin.

Vaihe 5. Pyydä käyttöoikeustunnusta

Voit hankkia haltijatunnuksen kahdella tavalla: yksi tapa on käyttäjänimi ja salasana ja toinen palvelun päänimiä varten.

Käyttäjänimi ja salasana -työnkulku

Lue julkisen asiakkaan osio. Lähetä sitten POST-pyyntö HTTP:n kautta Microsoft Entra ID:hen käyttäjänimellä ja salasanalla.

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

Edellisessä esimerkissä on paikkamerkit, jotka voit noutaa asiakassovelluksesta Microsoft Entra -tunnuksella. Saat vastauksen, jonka avulla voit tehdä myöhempiä kutsuja Power Platform -ohjelmointirajapintaan.

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

Käytä access_token-arvoa seuraavissa Power Platformin ohjelmointirajapinnan kutsuissa käyttämällä Authorization -HTTP-otsikkoa.

Palvelun päänimen työnkulku

Muista lukea osio Varmenteiden ja salaisten koodien määrittäminen . Lähetä sitten POST-pyyntö HTTP:n kautta Microsoft Entra ID:hen asiakasohjelman salaisen koodin tiedoilla. Tätä todentamismenetelmää kutsutaan usein palvelun päänimen todentamiseksi.

Tärkeää

Ennen kuin käytät palvelun päänimen todentamista, suorita tämän artikkelin vaiheet 1–4, jotta voit luoda ja määrittää sovelluksen rekisteröinnin varmenteen tai asiakassalaisuuden avulla. Määritä sitten palvelun päänimelle RBAC-rooli, jotta se voi hallita sen käyttöoikeustasoa. Lisätietoja on artikkelissa Opetusohjelma: RBAC-roolien määrittäminen palvelun päänimille.

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

Edellisessä esimerkissä on paikkamerkit, jotka voit noutaa asiakassovelluksesta Microsoft Entra -tunnuksella. Saat vastauksen, jonka avulla voit tehdä myöhempiä kutsuja Power Platform -ohjelmointirajapintaan.

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

Käytä access_token-arvoa seuraavissa Power Platformin ohjelmointirajapinnan kutsuissa käyttämällä Authorization -HTTP-otsikkoa. Palvelun päänimen voimassa olevat käyttöoikeudet määräytyy sille määritetyn RBAC-roolin mukaan. Jos haluat lisätietoja roolin määrittämisestä, katso Opetusohjelma: RBAC-roolien määrittäminen palvelun päänimille.

Pikaopas Azuren komentorivikäyttöliittymän avulla

Seuraava komentosarja luo sovelluksen rekisteröinnin päästä päähän. Suorita jokainen komento järjestyksessä ja korvaa paikkamerkkiarvot omalla komennollasi.

# 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

Kun olet suoritellut nämä komennot, voit käyttää sovelluksesi rekisteröintiä SDK:iden, PowerShellin tai suorien REST-kutsujen kanssa. Jos haluat etsiä parametrin käyttöoikeustunnuksia --api-permissions , katso käyttöoikeusviittaus.

Yleisten ongelmien vianetsintä

"Suostumus vaaditaan" tai "edellyttää järjestelmänvalvojan hyväksyntää" -virheet

Tämä virhe ilmenee, kun järjestelmänvalvoja ei ole antanut suostumusta sovelluksen rekisteröinnin ohjelmointirajapinnan käyttöoikeuksille. Siirry kohtaan Sovelluksen rekisteröinnit> sovelluksen ohjelmointirajapinnan> käyttöoikeudet ja valitse Myönnä järjestelmänvalvojan suostumus.

Vaihtoehtoisesti voidaan suorittaa

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

"Käyttäjälle ei ole määritetty roolia sovelluksen" virheistä

Tämä virhe tarkoittaa, että sovelluksen rekisteröintiin liittyvässä yrityssovelluksessa käyttäjän määrityksen arvoksi on määritetty Kyllä. Kun tämä asetus on käytössä, vain käyttäjä tai ryhmä, joka on nimenomaisesti määritetty sovellukselle, voi kirjautua sisään. Voit korjata tämän virheen jollain seuraavista toiminnoista:

• Siirry Microsoft Entra ID>Enterprise -sovelluksiin>, ja> määritä määrityksen arvoksiEi.
• Lisää tarvittavat käyttäjät tai käyttöoikeusryhmät Käyttäjät ja ryhmät -kohtaan.

Ehdolliset käyttöoikeuskäytännöt estävät käytön

Jos organisaatiosi käyttää ehdollisia käyttöoikeuskäytäntöjä, niiden hankkiminen saattaa estää tunnuksen hankkimisen sovelluksen rekisteröintiä varten. Yleisiä syitä ovat laitteen yhteensopivuusvaatimukset, sijaintirajoitukset tai riskipohjaiset käytännöt. Pyydä Microsoft Entra -järjestelmänvalvojaasi joko jättämään sovelluksesi rekisteröinti pois käytännöstä tai varmistamaan, että asiakkaat täyttävät käytäntövaatimukset.

"Power Platform API" ei löydy ohjelmointirajapinnan valitsimesta

Jos haku Power Platform -ohjelmointirajapintaa nimen tai GUID-tunnuksen avulla ei palauta tuloksia ohjelmointirajapinnan käyttöoikeuksien valintaikkunassa, palvelun päänimeä ei luoda vuokraajassa. Luo vaihe 2 noudattamalla pakottamisen päivityksen vaiheita.

Todentaminen Power Platform SDK:iden ja PowerShellin avulla

Seuraavissa esimerkeissä näytetään, miten voit todentaa ja tehdä API-mallikutsun kunkin SDK:n ja PowerShellin avulla. Ennen kuin suoritat nämä esimerkit, suorita tämän artikkelin vaiheet 1–3 sovelluksen rekisteröinnin luomiseksi ja määrittämiseksi.

Vuorovaikutteinen todentaminen (delegoitu käyttäjä)

Vuorovaikutteinen todentaminen avaa selainikkunan, jossa käyttäjä voi kirjautua sisään. Tämä työnkulku toimii parhaiten kehittäjien komentosarjoissa, järjestelmänvalvojatyökaluissa ja kaikissa tilanteissa, joissa käyttäjä on läsnä.

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

Luottamuksellinen asiakas (palvelun päänimi)

Luottamuksellinen asiakastodentaminen käyttää asiakassalaisuutta tai varmennetta, eikä se edellytä käyttäjän toimia. Tämä todennustyönkulku sopii parhaiten taustapalveluille, putkille ja automaatiolle.

Tärkeää

Ennen kuin käytät palvelun päänimen todentamista, luo ja määritä sovelluksen rekisteröinti varmenteella tai asiakassalaisilla koodilla suorittamalla yllä vaiheet 1–4. Määritä sitten palvelun päänimelle RBAC-rooli, jotta se voi hallita sen käyttöoikeustasoa. Lisätietoja on ohjeaiheessa Opetusohjelma: RBAC-roolien määrittäminen palvelun päänimille.

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

Liittyvä sisältö

Opetusohjelma: RBAC-roolien määrittäminen palvelun päänimille
Roolipohjaisen käytön hallinta Power Platform -hallintakeskuksessa
Käyttöoikeusviittaus