Authentication

В этой статье представлен обзор установки 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 в верхней части страницы. Затем нажмите кнопку +Добавить>регистрацию приложения.
3. Заполните страницу регистрации приложения :
   1. Имя — присвойте приложению распознаваемое имя, например пакет 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"

Azure CLI

az login

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

Здесь выберите необходимые разрешения. Эти разрешения группируются по пространствам имен. В пространстве имен отображаются типы ресурсов и действия, такие как AppManagement.ApplicationPackages.Read, которые предоставляют разрешения на чтение для пакетов приложений. Дополнительные сведения см. в справочной статье о разрешениях .

Замечание

API Power Platform использует делегированные разрешения только в настоящее время. Для приложений, работающих с контекстом пользователя, запрашивайте делегированные разрешения с помощью параметра области . Эти разрешения делегирует привилегии пользователя, вошедшего в систему, приложению, поэтому он может выступать в качестве пользователя при вызове конечных точек API Power Platform.

Для удостоверений субъекта-службы не используйте разрешения приложения. Вместо этого после создания регистрации приложения назначьте ему роль RBAC, чтобы предоставить разрешения на область действия (например , участник или читатель). Дополнительные сведения см. в руководстве. Назначение ролей RBAC субъектам-службам.

После добавления необходимых разрешений в приложение выберите "Предоставить согласие администратора ", чтобы завершить настройку. Предоставив согласие администратора, вы авторизуете разрешения для всех пользователей в клиенте, чтобы они не запрашивались в интерактивном диалоговом окне согласия при первом использовании приложения. Если вы предпочитаете интерактивное согласие для каждого пользователя, следуйте инструкциям по платформе удостоверений Майкрософт и потоку кода авторизации 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. Вы получите ответ, который можно использовать для последующих вызовов к 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 в последующих вызовах API Power Platform с помощью заголовка 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. Вы получите ответ, который можно использовать для последующих вызовов к API Power Platform.

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

Используйте значение access_token в последующих вызовах API Power Platform с помощью заголовка 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 для Power Platform и PowerShell

В следующих примерах показано, как выполнить проверку подлинности и выполнить пример вызова 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}");
}

Пакет SDK для Python

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

Пакет SDK для Python

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
Справочник по разрешениям