Аутентификация

Бұл мақалада Microsoft Entra Power Platform API-ін шақыру үшін орнатылған орнатуға шолу беріледі. Power Platform API арқылы қолжетімді ресурстарға қол жеткізу үшін Microsoft Entra-дан тасымалдаушы токен алып, оны әр сұраныспен бірге тақырып ретінде жіберуіңіз керек. Сіз қолдайтын идентификация түріне (пайдаланушы мен қызмет принципі) байланысты осы тасымалдаушы токенді алу үшін әртүрлі ағындар бар, бұл мақалада сипатталған.

Дұрыс рұқсаттары бар тасымалдаушы белгісін алу үшін келесі қадамдарды орындаңыз:

1. Microsoft Entra жалға алушылығыңызда қосымшаны тіркеу жасаңыз
2. API рұқсаттарын баптау
3. Платформаны баптау және URI-ді бағыттау
4. (Міндетті емес) Сертификаттар мен құпияларды баптау
5. Қол жеткізу токенін сұрау

1-қадам. Қолданбаны тіркеуді Microsoft Entra жалгеріңізде жасаңыз

1. Azure порталына кіріңіз.
2. Беттің жоғарғы жағында Microsoft Entra ID-ді таңдаңыз. Содан кейін қосымша тіркелуді +> қосу таңдаңыз.
3. Өтініш парақшасын толтырыңыз:
   1. Атауы — Қосымшаға танымал атау беріңіз, мысалы Power Platform Admin SDK.
   2. Қолдау көрсетілетін есептік жазба түрлері — Тек Бір жалға алушы таңдаңыз — <компанияңыздың атауы>.
   3. URI-ді қайта бағыттау — Әзірге мұны өткізіп жіберіңіз. Оны 3-қадамда баптайсың.
4. Қосымшаны жасау үшін Тіркеуді таңдаңыз. Тіркелу аяқталғаннан кейін, шолу бетінен Application (client) ID және Directory (tenant) ID-лерін байқаңыз — кейін екі мән де қажет болады.

Тіркеуді Azure CLI арқылы да жасай аласыз:

az login

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

Команда JSON объектісін қайтарады. Мәнге назар appId аударыңыз — бұл мән сіздің клиент идентификаторыңыз.

2-қадам. API рұқсаттарын конфигурациялау

Жаңа қосымшаны тіркеуде Manage - API Permissions қойындысына өтіңіз. Рократтарды конфигурациялау бөлімінде Add a Permission таңдаңыз. Диалогтық терезеде ұйымым қолданатын API-лерді таңдап, Power Platform API-ін іздеңіз. Осы атаумен ұқсас бірнеше жазбаларды көруіңіз мүмкін, сондықтан GUID 8578e004-a5c6-46e7-913e-12f58912df43 бар жазбаны таңдаңыз.

Егер GUID бойынша іздеу кезінде Power Platform API тізімде көрсетілмесе, оған әлі де қол жеткізе аласыз, бірақ көрініс жаңартылмайды. Жаңартуды мәжбүрлеп орындау үшін келесі сценарийді іске қосыңыз:

#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

Мұнда қажетті рұқсаттарды таңдаңыз. Бұл рұқсаттар Namespaces бойынша топтастырылған. Атау кеңістігінде сіз AppManagement.ApplicationPackages.Read сияқты ресурс түрлері мен әрекеттерін көресіз, ол қосымша пакеттеріне оқуға рұқсат береді. Қосымша ақпарат алу үшін Permission сілтеме мақаласын қараңыз.

Қажетті рұқсаттарды қосқаннан кейін, орнатуды аяқтау үшін Әкімші мақұлдауын беруді таңдаңыз. Әкімшінің келісімін беру арқылы сіз жалға алушы барлық пайдаланушыларға рұқсат бересіз, сондықтан олар сіздің қосымшаңды алғаш қолданғанда интерактивті келісім диалогымен сұрамайды. Егер пайдаланушыға арналған интерактивті келісімді ұнатсаңыз, 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 скрипттері және жұмыс үстелі қосымшалары Microsoft Entra аутентификациядан кейін токендерді қайтару үшін қайта бағыттау URI-ін талап етеді.

1. Қосымшаңыздың тіркелуінде Басқару - Аутентификация бөліміне өтіңіз.

2. Redirect URI қосуды таңдаңыз, содан кейін Mobile және десктоп қосымшаларын таңдаңыз.

3. Келесі кіріктірілген қайта бағыттау URI-ін таңдаңыз:

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

4. Сақтау үшін Конфигурацияны таңдаңыз.

Сондай-ақ, Azure CLI арқылы қайта бағыттау URI-ін қосуға болады:

# 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

Қоғамдық клиент орнату

Сол Аутентификация қойындысындағы Кеңейтілген баптаулар бөлімінде Қоғамдық клиент ағындарын рұқсат ету қосқышы бар. Егер сіз Resource Owner Password Credentials (ROPC) ағынын қолдануды жоспарласаңыз, бұл ауыстырғышты Yes деп қойыңыз, ол токен сұрау денесіне тікелей пайдаланушы аты мен құпия сөзін жібереді.

Бұл ағын көп факторлы аутентификация қосылған аккаунттар үшін жұмыс істемейді. Интерактивті браузер немесе құрылғы код ағындары үшін бұл баптауды қосудың қажеті жоқ.

4-қадам. (Міндетті емес) Сертификаттар мен құпияларды баптау

Егер сіздің қосымшаңыз оқу және жазу ресурстарын өзі, яғни қызмет принципі ретінде талап етсе, аутентификациялаудың екі жолы бар. Сертификаттарды пайдалану үшін Басқару - Сертификаттар мен құпиялар бөліміне кіріңіз. Сертификаттар бөлімінде аутентификация үшін қолдануға болатын x509 сертификатын жүктеңіз.

Екінші жолы — клиент құпиясын жасау үшін Құпиялар бөлімін пайдалану. Автоматтандыру қажеттіліктерімен пайдалану үшін құпияны қауіпсіз жерде сақтаңыз. Сертификат немесе құпия опциялар Microsoft Entra арқылы аутентификацияланып, осы клиентке арналған токен алуға мүмкіндік береді, оны REST API-ларына немесе PowerShell cmdlet-теріне бересіз.

5-қадам. Кіру токенін сұрау

Қолжетімділік тасымалдаушы токенді екі жолмен алуға болады: біреуі пайдаланушы аты мен құпиясөз үшін, екіншісі — қызмет принциптері үшін.

Пайдаланушы аты және құпиясөз ағыны

Қоғамдық клиент бөлімін міндетті түрде оқыңыз. Содан кейін пайдаланушы аты мен құпия сөздің пайдалы жүктемесі бар Microsoft Entra ID мекенжайына HTTP арқылы POST сұрауын жіберіңіз.

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-де клиент қосымшасынан алуға болатын уақытша орындар бар. Сіз Power Platform API-ге кейінгі қоңырауларды жасауға болатын жауап аласыз.

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

Авторизация HTTP тақырыбын пайдалану арқылы Power Platform API бағдарламасына келесі қоңырауларда access_token мәнін пайдаланыңыз.

Негізгі қызмет ағыны

Сертификаттар мен құпияларды конфигурациялау бөлімін міндетті түрде оқыңыз. Содан кейін HTTP арқылы POST сұрауын клиенттің құпия пайдалы жүктемесі бар 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&client_secret={SECRET_FROM_AZURE_CLIENT_APP}&grant_type=client_credentials

Алдыңғы мысалда Microsoft Entra ID-де клиент қосымшасынан алуға болатын уақытша орындар бар. Сіз Power Platform API-ге кейінгі қоңырауларды жасауға болатын жауап аласыз.

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

Авторизация HTTP тақырыбын пайдалану арқылы Power Platform API бағдарламасына келесі қоңырауларда access_token мәнін пайдаланыңыз. Қызмет басшысының тиімді рұқсаттары оған берілген 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 рұқсат идентификаторларын іздеу үшін Permission сілтемесіне қараңыз.

Жиі кездесетін мәселелерді анықтау

"Келісім қажет" немесе "әкімші мақұлдауы қажет" қателері

Бұл қате әкімші сіздің қосымшаңыздағы API рұқсаттарына келісім бермеген кезде пайда болады. Қосымша тіркеулеріңізге>> кіріп,Әкімші мақұлдауын беруді таңдаңыз.

Немесе іске қосыңыз:

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

"Пайдаланушыға қосымша рөліне тағайындалмаған" қателері

Бұл қате сіздің қосымшаңызға тіркелумен байланысты кәсіпорын қосымшасында User тағайындау қажетібар екенін білдіреді. Бұл баптау қосулы болғанда, тек қолданбаға арнайы тағайындалған пайдаланушылар немесе топтар ғана кіре алады. Бұл қатені түзету үшін келесі әрекеттердің бірін орындаңыз:

• Microsoft Entra ID>Enterprise қосымшаларыңыздың>>Қасиеттері бөліміне кіріп, Тағайындауқажеттілігін No. деп қойыңыз.
• Тиісті пайдаланушылар немесе қауіпсіздік топтарын Users және groups бөліміне қосыңыз.

Қолжетімділікті бұғаттайтын шартты қолжетімділік саясаттары

Егер сіздің ұйымыңыз шартты қолжетімділік саясатын қолданса, олар қосымшаңызды тіркеу үшін токен алуды бұғаттауы мүмкін. Жиі кездесетін себептерге құрылғының сәйкестік талаптары, орналасу шектеулері немесе тәуекелге негізделген саясаттар жатады. Microsoft Entra әкімшіңізбен бірге қолданбаңызды тіркеуді саясаттан алып тастаңыз немесе клиенттердің саясат талаптарына сай екеніне көз жеткізіңіз.

"Power Platform API" API таңдаушысында жоқ

Егер API рұқсаттары диалогында Power Platform API-ді атауы немесе GUID бойынша іздеу нәтиже шықпаса, қызмет басшысы сіздің жалға алушыда жасалмайды. Оны жасау үшін 2-қадамдағы күшпен жаңарту қадамдарын орындаңыз.

Power Platform SDK және PowerShell арқылы аутентификация

Төмендегі мысалдар әр SDK мен PowerShell арқылы аутентификация және үлгі API шақыруын жасау жолдарын көрсетеді. Бұл мысалдарды іске қоспас бұрын, осы мақалада 1-3 қадамдарды орындап, қосымшаны тіркеуді жасап, баптаңыз.

Интерактивті аутентификация (өкілдетілген пайдаланушы)

Интерактивті аутентификация пайдаланушыға кіру үшін браузер терезесін ашады. Бұл ағын әзірлеуші скрипттері, әкімшілік құралдар және пайдаланушы бар кез келген жағдайда ең жақсы жұмыс істейді.

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

Құпия клиент (қызмет басшысы)

Құпия клиенттік аутентификация клиенттің құпиясын немесе сертификатын пайдаланады және пайдаланушымен араласуды талап етпейді. Бұл аутентификация ағыны фондық қызметтер, құбырлар және автоматтандыру үшін ең қолайлы.

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

Қатысты мазмұн

Оқулық: RBAC рөлдерін қызмет көрсету басшыларына тағайындау
Power Platform әкімшілік орталығына арналған рөлдік қолжетімділікті басқару
Рұқсат сілтемесі