Автентифікація

У цій статті наведено огляд налаштування Microsoft Entra для виклику API Power Platform. Щоб отримати доступ до ресурсів, доступних через API Платформи Power Platform, потрібно отримати маркер носія від Microsoft Entra та надіслати його як заголовок разом із кожним запитом. Залежно від типу посвідчення, який ви підтримуєте (користувач і принципал служби), є різні потоки, щоб отримати цей маркер носія, як описано в цій статті.

Щоб отримати маркер носія з правильними дозволами, виконайте такі дії:

1. Створення реєстрації програми в клієнті Microsoft Entra
2. Настроювання дозволів API
3. Настроювання платформи та URI переспрямування
4. (Необов'язково) Настроювання сертифікатів і секретів
5. Запит маркера доступу

Крок 1. Створіть заявку на реєстрацію у вашому Microsoft Entra орендарі

1. Перейдіть на портал Azure.
2. Виберіть Microsoft Entra ID у верхній частині сторінки. Потім виберіть + Додати>реєстрацію програми.
3. Заповніть сторінку Реєстрація застосунку :
   1. Name (Ім'я ) – надайте програмі зрозуміле ім'я, наприклад пакет SDK для адміністраторів Платформи Power Platform.
   2. Підтримувані типи облікових записів. Виберіть лише один клієнт – <назва> вашої компанії.
   3. URI переспрямування – пропустіть це зараз. Ви налаштовуєте його на кроці 3.
4. Натисніть кнопку Зареєструвати , щоб створити програму. Після завершення реєстрації зверніть увагу на ідентифікатор програми (клієнта) та ідентифікатор каталогу (клієнта) на сторінці огляду . Пізніше вам знадобляться обидва значення.

Ви також можете створити реєстрацію за допомогою Azure CLI:

az login

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

Команда повертає об'єкт JSON. Зверніть увагу на appId значення – це значення ідентифікатора клієнта.

Крок 2. Настроювання дозволів API

У новій реєстрації програми перейдіть на вкладку Керування дозволами API . У розділі Настроювання дозволів виберіть елемент Додати дозвіл. У діалоговому вікні виберіть вкладку API, які використовує моя організація , а потім знайдіть API платформи Power Platform. Можуть відображатися кілька записів з іменем, подібним до цього, тому переконайтеся, що ви використовуєте цей запис із GUID 8578e004-a5c6-46e7-913e-12f58912df43.

Якщо інтерфейс API платформи Power Platform не відображається в списку під час пошуку за ідентифікатором GUID, можливо, ви все одно маєте до нього доступ, але видимість не оновлюється. Щоб примусово оновити оновлення, виконайте такий сценарій:

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

Тут виберіть потрібні дозволи. Ці дозволи згруповано за просторами імен. У просторі імен відображаються типи та дії ресурсів, наприклад AppManagement.ApplicationPackages.Read, що надає дозволи на читання пакетів програм. Докладні відомості див. в статті Довідник із дозволів .

Нотатка

API Power Platform використовує делеговані дозволи лише в цей час. Для програм, які працюють із контекстом користувача, запитайте делеговані дозволи за допомогою параметра області . Ці дозволи делеговують права користувача, що ввійшов, до вашої програми, щоб він міг виступати користувачем під час виклику кінцевих точок API платформи Power Platform.

Для посвідчень основних служб не використовуйте дозволи програми. Натомість, створивши реєстрацію програми, призначте їй роль RBAC, щоб надати області дозволів (наприклад , Співавтор або Читач). Докладні відомості див. в статті Посібник. Призначення ролей RBAC принципалам служби.

Додаючи необхідні дозволи до програми, виберіть надати згоду адміністратора , щоб завершити настроювання. Надаючи згоду адміністратора, ви дозволяєте дозволи для всіх користувачів у клієнті, щоб вони не запитували в діалоговому вікні інтерактивної згоди під час першого використання програми. Якщо ви віддаєте перевагу інтерактивній згоді кожного користувача, дотримуйтеся платформи ідентичностей Microsoft і потоку коду авторизації OAuth 2.0.

Ви також можете надати згоду адміністратора, використовуючи Azure CLI:

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

Крок 3. Настроювання платформи та URI переспрямування

SDK, сценарії PowerShell і класичні програми, які автентифікують від імені користувача, потребують переспрямування URI, щоб Microsoft Entra міг повернути маркери до програми після автентифікації.

1. У межах реєстрації програми перейдіть до розділу Керування автентифікацією.

2. Натисніть кнопку Додати URI переспрямування, а потім виберіть мобільні та класичні програми.

3. Виберіть такий вбудований URI переспрямування:

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

4. Натисніть кнопку Настроїти , щоб зберегти.

Ви також можете додати URI переспрямування за допомогою 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

Параметр загальнодоступного клієнта

У розділі Додаткові параметри на тій самій вкладці Автентифікація є перемикач Дозволити передавання загальнодоступних клієнтів . Установіть цей перемикач так , лише якщо ви плануєте використовувати потік облікових даних пароля власника ресурсу (ROPC), який надсилає ім'я користувача та пароль безпосередньо в тексті запиту маркера.

Цей потік не працює для облікових записів, для яких активовано багатофакторну автентифікацію. Для інтерактивних потоків коду браузера або пристрою не потрібно вмикати цей параметр.

Крок 4. (Необов'язково) Настроювання сертифікатів і секретів

Якщо програма вимагає читання та написання ресурсів як сама, також відома як принципал служби, існує два способи автентифікації. Щоб використовувати сертифікати, перейдіть до розділу Керування – Сертифікати та секрети. У розділі Сертифікати передайте сертифікат x509, який можна використовувати для автентифікації.

Інший спосіб зробити це — за допомогою розділу Секрети можна створити секрет клієнта. Збережіть секретний ключ у безпечному місці для використання для потреб автоматизації. Сертифікат або таємні параметри дають змогу автентифікуватися в Microsoft Entra та отримувати маркер для цього клієнта, який ви передаєте командлетам REST API або PowerShell.

Крок 5. Запит маркера доступу

Маркер носія доступу можна отримати двома способами: один із способів – для імені користувача та пароля, а інший – для принципалів служби.

Цикл для імені користувача та пароля

Обов'язково прочитайте розділ загальнодоступного клієнта. Потім надішліть запит POST через HTTP на Microsoft Entra ID з корисним набором імені користувача та пароля.

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

У попередньому прикладі містяться покажчики місця заповнення, які можна отримати з клієнтської програми в microsoft Entra ID. Ви отримуєте відповідь, за допомогою яких можна здійснювати подальші виклики до 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..."
}

Використовуйте значення access_token у наступних викликах Power Platform API у заголовку HTTP Авторизація.

Основний потік послуг

Обов'язково прочитайте розділ Настроювання сертифікатів і секретів . Потім надішліть запит POST через HTTP на Microsoft Entra ID із секретним корисним навантаженням клієнта. Цей метод автентифікації часто називають автентифікацією основного учасника служби.

Important

Перш ніж використовувати автентифікацію основної служби, виконайте кроки 1–4 вище в цій статті, щоб створити та настроїти реєстрацію програми за допомогою сертифіката або секрету клієнта. Потім призначте принципалу служби роль RBAC, щоб керувати рівнем доступу. Докладні відомості див. в статті Посібник: Призначення ролей RBAC принципалам служби.

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

У попередньому прикладі містяться покажчики місця заповнення, які можна отримати з клієнтської програми в microsoft Entra ID. Ви отримуєте відповідь, за допомогою яких можна здійснювати подальші виклики до API Power Platform.

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

Використовуйте значення access_token у наступних викликах Power Platform API у заголовку HTTP Авторизація. Ефективні дозволи принципала служби визначаються призначеною йому роллю RBAC. Щоб дізнатися, як призначити роль, див . статтю Посібник. Призначення ролей RBAC принципалам служби.

Короткий посібник з Azure CLI

Наведений нижче сценарій створює кінцеву реєстрацію програми. Виконайте кожну команду по порядку та замініть значення покажчиків місця заповнення на власні.

# 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

Після виконання цих команд можна використовувати реєстрацію програм за допомогою SDK, PowerShell або прямих викликів REST. Щоб знайти ідентифікатори дозволів для --api-permissions параметра, див. посилання на дозвіл.

Вирішення поширених проблем

Помилки "Потрібна згода" або "потребує затвердження адміністратором"

Ця помилка виникає, коли адміністратор не дав згоди на дозволи API під час реєстрації програми. Перейдіть до розділу> Реєстрації програм, > програми та виберіть надати згоду адміністратора.

Або запустіть:

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

Помилки "Користувачу не призначено роль для застосунку"

Ця помилка означає, що корпоративна програма, пов'язана з реєстрацією програми, має для призначення користувача значенняТак. Якщо цей параметр увімкнуто, увійти можуть лише користувачі або групи, явно призначені програмі. Щоб виправити цю помилку, виконайте одну з таких дій:

• Перейдіть допрограм>Microsoft Entra ID> Enterprise і встановіть для >Завдання обов'язковезначення Ні.
• Додайте відповідних користувачів або групи безпеки в розділі Користувачі та групи.

Політики умовного доступу, які блокують доступ

Якщо ваша організація застосовує політики умовного доступу, вони можуть заблокувати придбання маркерів для реєстрації програми. Поширені причини: вимоги до відповідності пристрою, обмеження розташування або політики на основі ризиків. Зверніться до адміністратора Microsoft Entra, щоб виключити реєстрацію програми з політики або забезпечити відповідність клієнтів вимогам політики.

"API Power Platform" не знайдено в засобі вибору API

Якщо пошук API Power Platform за іменем або GUID у діалоговому вікні дозволів API не повертає жодних результатів, принципал служби не створюється у вашому клієнті. Виконайте кроки примусового оновлення на кроці 2 , щоб створити його.

Автентифікація за допомогою SDK і PowerShell на платформі Power Platform

У наведених нижче прикладах показано, як автентифікувати та здійснити вибірковий виклик API за допомогою кожного пакета SDK і PowerShell. Перш ніж запускати ці приклади, виконайте кроки 1–3 вище в цій статті, щоб створити та настроїти реєстрацію програми.

Інтерактивна автентифікація (делегований користувач)

Інтерактивна автентифікація відкриває вікно браузера для входу користувача. Цей потік найкраще підходить для сценаріїв розробників, засобів адміністрування та будь-якого сценарію, у якому присутній користувач.

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

Конфіденційний клієнт (принципал служби)

Конфіденційна автентифікація клієнта використовує секрет клієнта або сертифікат і не вимагає взаємодії з користувачем. Цей потік автентифікації найкраще підходить для фонових служб, трубопроводів і автоматизації.

Important

Перш ніж використовувати автентифікацію основної служби, виконайте кроки 1–4 вище, щоб створити та настроїти реєстрацію програми за допомогою сертифіката або секрету клієнта. Потім призначте принципалу служби роль RBAC, щоб керувати рівнем доступу. Докладні відомості див. в статті Посібник: Призначення ролей RBAC принципалам служби.

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

Пов’язаний вміст

Навчальний посібник. Призначення ролей RBAC принципалам служби
Керування доступом на основі ролей для Центру адміністрування Power Platform
Посилання на дозвіл