אימות

מאמר זה מספק מבט כולל על תוכנית ההתקנה של 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. בחר מזהה Entra של Microsoft בחלק העליון של הדף. לאחר מכן בחר + הוסף>רישום אפליקציה.
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, ייתכן שעדיין יש לך גישה אליו, אך הניראות אינה מתרענן. כדי לכפות רענון, הפעל את קובץ ה- Script הבא:

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

az login

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

מכאן, בחר את ההרשאות הדרושות לך. הרשאות אלה מקובצות לפי מרחבי שמות. בתוך מרחב שמות, תראה סוגי משאבים ופעולות, כגון AppManagement.ApplicationPackages.Read, אשר מעניק הרשאות קריאה עבור חבילות יישומים. לקבלת מידע נוסף, עיין במאמר חומר עזר בנושא הרשאות .

הערה

ממשק ה- API של Power Platform משתמש בהרשאות מוקצות בלבד בשלב זה. עבור יישומים הפועלים עם הקשר משתמש, בקש הרשאות מוקצות באמצעות הפרמטר scope . הרשאות אלה מקצה את ההרשאות של המשתמש המחובר ליישום שלך, כך שהוא יכול לפעול כמשתמש בעת קריאה לנקודות קצה של API של Power Platform.

עבור זהויות ראשיות של שירות, אל תשתמש בהרשאות יישום. במקום זאת, לאחר יצירת רישום היישום, הקצה לו תפקיד RBAC כדי להעניק הרשאות בטווח (כגון 'משתתף ' או ' קורא '). לקבלת מידע נוסף, ראה ערכת לימוד: הקצאת תפקידי RBAC למנהלי שירות.

לאחר הוספת ההרשאות הנדרשות ליישום, בחר הענק הסכמת מנהל מערכת כדי להשלים את ההגדרה. על-ידי הענקת הסכמת מנהל מערכת, אתה מאשר את ההרשאות עבור כל המשתמשים בדייר כך שהם לא מתבקשים עם תיבת דו-שיח אינטראקטיבית של הסכמה בפעם הראשונה שהם משתמשים ביישום שלך. אם אתה מעדיף הסכמה אינטראקטיבית לכל משתמש, בצע את פלטפורמת הזהויות של Microsoft ואת זרימת קוד ההרשאה של OAuth 2.0.

באפשרותך גם להעניק הסכמת מנהל מערכת באמצעות ממשק המשתמש של Azure:

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

שלב 3. קביעת תצורה של פלטפורמה ו- URI של ניתוב מחדש

ערכות SDK, קבצי Script של PowerShell ויישומי שולחן עבודה שאומתו בשם משתמש דורשים URI של ניתוב מחדש כך ש- Microsoft Entra תוכל להחזיר אסימונים בחזרה ליישום שלך לאחר האימות.

1. במסגרת רישום האפליקציה שלך, עבור אל ניהול - אימות.

2. בחר הוסף URI של ניתוב מחדש ולאחר מכן בחר אפליקציות למכשירים ניידים ולשולחנות עבודה.

3. בחר את ה- URI המוכלל הבא של ניתוב מחדש:

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

4. בחר קבע תצורה לשמירה.

באפשרותך גם להוסיף את ה- URI של ניתוב מחדש באמצעות ממשק המשתמש של Azure:

# 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 ולקבל אסימון עבור לקוח זה, שאתה מעביר יחד עם רכיבי ה- cmdlet של 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 בקריאות הבאות ל- API של Power Platform עם כותרת ה- HTTP של אימות.

זרימת מנהל שירות

הקפד לקרוא את המקטע קביעת תצורה של אישורים וסודות . לאחר מכן, שלח בקשת POST דרך HTTP אל Microsoft Entra ID עם תוכן מנה של סוד לקוח. שיטת אימות זו נקראת לעתים קרובות אימות ראשי של שירות.

חשוב

לפני השימוש באימות ראשי של שירות, השלם את שלבים 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 בקריאות הבאות ל- API של Power Platform עם כותרת ה- HTTP של אימות. ההרשאות האפקטיביות של מנהל השירות נקבעות על-ידי תפקיד RBAC שהוקצה לו. כדי ללמוד כיצד להקצות תפקיד, ראה ערכת לימוד: הקצאת תפקידי RBAC למנהלי שירות.

התחלה מהירה עם ממשק ממשק משתמש של Azure

קובץ ה- Script הבא יוצר רישום יישום מקצה לקצה. הפעל כל פקודה לפי הסדר והחלף ערכי מצייני מיקום בפקודה משלך.

# 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 ברישום היישום שלך. עבור אל רישומי אפליקציות את> הרשאות ה >- API של היישום ובחר הענק הסכמת מנהל מערכת.

לחלופין, הפעל:

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

שגיאות "המשתמש אינו מוקצה לתפקיד עבור היישום"

שגיאה זו פירושה שהיישום הארגוני המשויך לרישום היישום שלך הוגדר ככן בהקצאתמשתמש. כאשר הגדרה זו זמינה, רק משתמשים או קבוצות שהוקצו ליישום באופן מפורש יכולים להיכנס. כדי לתקן שגיאה זו, בצע אחת מהפעולות הבאות:

• עבור אל יישומי Microsoft Entra ID>Enterprise,> מאפייני היישום >שלך והגדר את ההקצאה הנדרשתללא.
• הוסף את המשתמשים או קבוצות האבטחה הרלוונטיים תחת משתמשים וקבוצות.

מדיניות גישה מותנית חוסמת גישה

אם הארגון שלך מחיל מדיניות גישה מותנית, הוא עלול לחסום רכישת אסימון עבור רישום היישום שלך. הסיבות הנפוצות כוללות דרישות תאימות למכשירים, הגבלות מיקום או מדיניות מבוססת סיכונים. עבוד עם מנהל המערכת של Microsoft Entra כדי לא לכלול את רישום היישום שלך במדיניות או ודא שהלקוחות עומדים בדרישות המדיניות.

"Power Platform API" לא נמצא ב'בורר ה- API'

אם חיפוש ה- API של Power Platform לפי שם או GUID בתיבת הדו-שיח של הרשאות API אינו מחזיר תוצאות, מנהל השירות אינו נוצר בדייר שלך. בצע את השלבים לרענון כפה בשלב 2 כדי ליצור אותו.

אימות באמצעות תוכנות SDK של Power Platform ו- PowerShell

הדוגמאות הבאות מראים כיצד לאמת ולבצע שיחת API לדוגמה באמצעות כל SDK ו- PowerShell. לפני הפעלת דוגמאות אלה, השלם את שלבים 1-3 לעיל במאמר זה כדי ליצור ולהגדיר את רישום היישום שלך.

אימות אינטראקטיבי (משתמש מוסמך)

אימות אינטראקטיבי פותח חלון דפדפן כדי שהמשתמש ייכנס. זרימה זו פועלת בצורה הטובה ביותר עבור קבצי Script למפתחים, כלי ניהול וכל תרחיש שבו קיים משתמש.

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

לקוח סודי (מנהל שירות)

אימות לקוח סודי משתמש בסוד לקוח או באישור ואינו דורש אינטראקציה עם המשתמש. זרימת אימות זו מתאימה ביותר עבור שירותי רקע, קווי צינור ואוטומציה.

חשוב

לפני השימוש באימות ראשי של שירות, השלם את שלבים 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
הפניה להרשאות