المصادقة

توفر هذه المقالة نظرة عامة على إعداد Microsoft Entra لاستدعاء واجهة برمجة تطبيقات Power Platform. للوصول إلى الموارد المتوفرة من خلال واجهة برمجة تطبيقات Power Platform، يجب الحصول على رمز حامل من 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. حدد Register لإنشاء التطبيق. بعد اكتمال التسجيل، لاحظ معرف التطبيق (العميل)ومعرف الدليل (المستأجر) من صفحة النظرة العامة — تحتاج إلى كلتا القيمتين لاحقا.

يمكنك أيضا إنشاء التسجيل باستخدام Azure CLI:

az login

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

يقوم الأمر بإرجاع كائن JSON. appId لاحظ القيمة — هذه القيمة هي معرف العميل الخاص بك.

الخطوة 2. تكوين أذونات API

في تسجيل التطبيق الجديد، انتقل إلى علامة التبويب إدارة - أذونات واجهة برمجة التطبيقات . ضمن قسم تكوين الأذونات ، حدد إضافة إذن. في مربع الحوار، حدد علامة التبويب واجهات برمجة التطبيقات التي تستخدمها مؤسستي ، ثم ابحث عن واجهة برمجة تطبيقات Power Platform. قد ترى العديد من الإدخالات باسم مشابه لهذا الاسم، لذا تأكد من استخدام الإدخال مع GUID 8578e004-a5c6-46e7-913e-12f58912df43.

إذا كنت لا ترى واجهة برمجة تطبيقات 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، والتي تمنح أذونات القراءة لحزم التطبيقات. لمزيد من المعلومات، راجع مقالة مرجع الإذن .

‏‫ملاحظة‬

تستخدم واجهة برمجة تطبيقات Power Platform الأذونات المفوضة فقط في هذا الوقت. بالنسبة للتطبيقات التي تعمل مع سياق مستخدم، اطلب الأذونات المفوضة باستخدام معلمة النطاق . تفوض هذه الأذونات امتيازات المستخدم الذي قام بتسجيل الدخول إلى التطبيق الخاص بك، بحيث يمكن أن يعمل كمستخدم عند استدعاء نقاط نهاية Power Platform API.

بالنسبة للهويات الأساسية للخدمة، لا تستخدم أذونات التطبيق. بدلا من ذلك، بعد إنشاء تسجيل التطبيق، قم بتعيين دور 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

تتطلب SDKs والبرامج النصية 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

إعداد العميل العام

ضمن قسم Advanced settings في علامة التبويب Authentication نفسها، يوجد تبديل Allow public client flows . قم بتعيين هذا التبديل إلى نعم فقط إذا كنت تخطط لاستخدام تدفق بيانات اعتماد كلمة مرور مالك المورد (ROPC)، والذي يرسل اسم مستخدم وكلمة مرور مباشرة في نص طلب الرمز المميز.

لا يعمل هذا التدفق للحسابات التي تم تمكين المصادقة متعددة العوامل فيها. بالنسبة إلى تدفقات التعليمات البرمجية للمستعرض التفاعلي أو الجهاز، لا تحتاج إلى تمكين هذا الإعداد.

الخطوة 4. (اختياري) تكوين الشهادات والأسرار

إذا كان تطبيقك يتطلب قراءة الموارد وكتابتها بنفسها، والمعروفة أيضا باسم كيان الخدمة، فهناك طريقتان للمصادقة. لاستخدام الشهادات، انتقل إلى إدارة - الشهادات والأسرار. ضمن قسم Certificates ، قم بتحميل شهادة x509 التي يمكنك استخدامها للمصادقة.

الطريقة الأخرى هي استخدام قسم "الأسرار " لإنشاء سر العميل. احفظ السر في مكان آمن لاستخدامه مع احتياجات الأتمتة الخاصة بك. تسمح لك خيارات الشهادة أو البيانات السرية بالمصادقة مع Microsoft Entra وتلقي رمز مميز لهذا العميل، والذي تمرره إما إلى واجهات برمجة تطبيقات REST أو PowerShell cmdlets.

الخطوة 5. طلب رمز مميز للوصول

يمكنك الحصول على رمز مميز لحامل الوصول بطريقتين: إحدى الطرق هي اسم المستخدم وكلمة المرور، والطريقة الأخرى هي لكيانات الخدمة.

سير عمل اسم المستخدم وكلمة المرور

تأكد من قراءة قسم العميل العام. بعد ذلك، أرسل طلب POST عبر HTTP إلى معرف Microsoft Entra مع حمولة اسم مستخدم وكلمة مرور.

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. تتلقى استجابة يمكنك استخدامها لإجراء مكالمات لاحقة إلى واجهة برمجة تطبيقات 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 مع حمولة سر العميل. غالبا ما يشار إلى أسلوب المصادقة هذا باسم المصادقة الأساسية للخدمة.

مهم

قبل استخدام المصادقة الأساسية للخدمة، أكمل الخطوات من 1 إلى 4 سابقا في هذه المقالة لإنشاء وتكوين تسجيل التطبيق الخاص بك باستخدام شهادة أو سر العميل. ثم قم بتعيين دور 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. تتلقى استجابة يمكنك استخدامها لإجراء مكالمات لاحقة إلى واجهة برمجة تطبيقات Power Platform.

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

استخدم قيمة access_token في الاستدعاءات التالية لواجهة API في Power Platform مع رأس HTTP التفويض. يتم تحديد الأذونات الفعالة لمدير الخدمة من خلال دور التحكم في الوصول استنادا إلى الدور المعين له. لمعرفة كيفية تعيين دور، راجع البرنامج التعليمي: تعيين أدوار 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

بعد تشغيل هذه الأوامر، يمكنك استخدام تسجيل التطبيق الخاص بك مع SDKs أو PowerShell أو مكالمات REST المباشرة. للبحث عن معرفات الأذونات للمعلمة --api-permissions ، راجع مرجع الإذن.

استكشاف المشكلات الشائعة وإصلاحها

أخطاء "الموافقة مطلوبة" أو "يحتاج إلى موافقة المسؤول"

يحدث هذا الخطأ عندما لا يوافق المسؤول على أذونات واجهة برمجة التطبيقات في تسجيل التطبيق. انتقل إلى تسجيلات> التطبيقات أذونات واجهة برمجة تطبيقات التطبيق > وحدد منح موافقة المسؤول.

بدلا من ذلك، قم بتشغيل:

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

أخطاء "لم يتم تعيين المستخدم لدور للتطبيق"

يعني هذا الخطأ أن تطبيق المؤسسة المقترن بتسجيل التطبيق الخاص بك تم تعيين تعيين المستخدم المطلوب إلى نعم. عند تمكين هذا الإعداد، يمكن فقط للمستخدمين أو المجموعات المعينة صراحة للتطبيق تسجيل الدخول. لإصلاح هذا الخطأ، اتخذ أحد الإجراءات التالية:

• انتقل إلىتطبيقات>Microsoft Entra ID> Enterprise لتطبيقك خصائص التطبيق > وقم بتعيين التعيين المطلوب إلى لا.
• أضف المستخدمين أو مجموعات الأمان ذات الصلة ضمن المستخدمين والمجموعات.

نهج الوصول المشروط التي تمنع الوصول

إذا كانت مؤسستك تطبق نهج الوصول المشروط، فقد تمنع الحصول على الرمز المميز لتسجيل تطبيقك. تتضمن الأسباب الشائعة متطلبات توافق الجهاز أو قيود الموقع أو النهج المستندة إلى المخاطر. اعمل مع مسؤول Microsoft Entra إما لاستبعاد تسجيل التطبيق من النهج أو التأكد من أن العملاء يستوفون متطلبات النهج.

لم يتم العثور على "Power Platform API" في منتقي واجهة برمجة التطبيقات

إذا لم يرجع البحث عن واجهة برمجة تطبيقات Power Platform حسب الاسم أو GUID في مربع حوار أذونات واجهة برمجة التطبيقات أي نتائج، فلن يتم إنشاء كيان الخدمة في المستأجر الخاص بك. اتبع خطوات فرض التحديث في الخطوة 2 لإنشائها.

المصادقة باستخدام Power Platform SDKs وPowerShell

توضح الأمثلة التالية كيفية المصادقة وإجراء نموذج استدعاء واجهة برمجة التطبيقات باستخدام كل 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}");
}

حزمة تطوير التطوير الخاصة لبايثون

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 لمدير الخدمة للتحكم في مستوى الوصول الخاص به. لمزيد من المعلومات، راجع البرنامج التعليمي: تعيين أدوار التحكم في الوصول استنادا إلى الدور لكيانات الخدمة.

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

حزمة تطوير التطوير الخاصة لبايثون

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

المحتوى ذو الصلة

البرنامج التعليمي: تعيين أدوار التحكم في الوصول استنادا إلى الدور لكيانات الخدمة
التحكم في الوصول استنادا إلى الدور لمركز إدارة Power Platform
مرجع الإذن