تهيئة الهُوِيَّة المُدارة في Power Platform للإضافات أو حزم الإضافات في Dataverse.

عند استخدام الهوية المدارة في Power Platform، يمكن لمكونات Dataverse الإضافية أو حزم المكونات الإضافية الاتصال بموارد Azure دون إدارة بيانات الاعتماد. توضح هذه المقالة الإعداد الموصى به (الإصدار 2)، الذي ينشئ بيانات اعتماد الهوية الموحدة (FIC) من تجزئة الاسم المميز الكامل للشهادة (DN).

ملاحظة

استخدم الإصدار 2 من الهوية المدارة من Power Platform لجميع المكونات الإضافية الجديدة والحالية. إذا قمت بالاحتفاظ بمكون إضافي لا يزال يستخدم تنسيق الإصدار 1 (المستند إلى CN)، فشاهد إعداد إصدار الهوية المدارة 1. لنقل مكون إضافي موجود إلى الإصدار 2، راجع الترقية إلى الإصدار 2.

لماذا الإصدار 2

ينتج الإصدار 2 معرف موضوع ASCII ثابت الطول فقط، لذلك يعمل مع أي اسم شهادة. يتعذّر على الإصدار 1 العمل مع أسماء شهادات معينة (CNs):

  • الأحرف غير ASCII في CN (على سبيل المثال، الأحرف المميزة) → AADSTS70050: The Federated Managed Identity path is not properly formatted.
  • الفواصل في CN (على سبيل المثال، CN=Contoso, Inc.) → AADSTS700213: No matching federated identity record found.

المتطلبات الأساسية

  • اشتراك Azure مع إمكانية الوصول إلى توفير الهوية المُدارة المعينة من قبل المستخدم (UAMI) أو تسجيل التطبيق.
  • أدوات للمكونات الإضافية أو حزم المكونات الإضافية:
  • شهادة صالحة لتوقيع المكون الإضافي تجميع.

إعداد الهوية المُدارة

  1. أنشئ تسجيل تطبيق جديد أو هوية مدارة معينة من قبل المستخدم.
  2. إنشاء المكون الإضافي وتوقيعه وتسجيله.
  3. تكوين بيانات اعتماد الهوية الموحدة.
  4. إنشاء سجل الهوية المدارة في Dataverse.
  5. منح حق الوصول إلى مورد Azure.
  6. التحقق من صحة التكامل.

الخطوة 1: إنشاء تسجيل تطبيق أو هوية مدارة يعينها المستخدم

أنشئ إما هوية مُدارة معيّنة من قِبل المستخدم أو تطبيقًا في Microsoft Entra ID:

ملاحظة

التقاط معرف التطبيق (العميل)ومعرف المستأجر — يمكنك استخدامهما في خطوات لاحقة.

الخطوة 2: إنشاء المكون الإضافي وتوقيعه وتسجيله

  1. إنشاء مكون إضافي في Visual Studio. استخدم معرف المستأجر من الخطوة 1 ونطاق مثل https://{OrgName}.crm*.dynamics.com/.default. استخدم IManagedIdentityService لطلب رمز مميز:

    string AcquireToken(IEnumerable<string> scopes);

  2. قم بتسجيل المكون الإضافي باستخدام الشهادة الخاصة بك.

    حزمة المكوّن الإضافي (NuGet):

    nuget sign YourPlugin.nupkg `
  -CertificatePath MyCert.pfx `
  -CertificatePassword "MyPassword" `
  -Timestamper http://timestamp.digicert.com

    تجميع البرنامج المساعد (SignTool):

    signtool sign /f MyCert.pfx /p MyPassword /t http://timestamp.digicert.com /fd SHA256 MyAssembly.dll

  3. تسجيل المكون الإضافي باستخدام أداة تسجيل المكون الإضافي.

ملاحظة

استخدم شهادة موقعة ذاتيا فقط للتطوير أو الاختبار. لا تستخدم الشهادات الموقعة ذاتيا في الإنتاج. لإنشاء شهادة، راجع إنشاء شهادة موقعة ذاتيا.

الخطوة 3: تكوين بيانات اعتماد الهوية الموحدة

في مدخل Azure، افتح التطبيق أو الهوية المدارة المعينة من قبل المستخدم (UAMI)، وانتقل إلى الشهادات والأسرار>بيانات الاعتماد الموحدة>إضافة بيانات اعتماد، وحدد مصدر آخر. ثم أدخل:

  • المصدر — https://login.microsoftonline.com/{tenantID}/v2.0

  • النوع — معرف الموضوع الصريح

  • معرف الموضوع — استخدم تنسيق نوع الشهادة:

    • شهادة جهة الإصدار الموثوقة (الإنتاج):

      /eid1/c/pub/t/{encodedTenantId}/a/qzXoWDkuqUa3l6zM5mM0Rw/n/plugin/e/{environmentId}/i/{issuerHash}/s/{subjectHash}

    • شهادة موقعة ذاتيا (تطوير فقط):

      /eid1/c/pub/t/{encodedTenantId}/a/qzXoWDkuqUa3l6zM5mM0Rw/n/plugin/e/{environmentId}/h/{hash}

    مرجع المقطع

    الشريحة الوصف
    eid1 إصدار تنسيق الهوية
    c/pub البرمجة السحابية للسحابة العامة وGCC ومحطة الإصدار الأولى في GCC
    t/{encodedTenantId} معرف المستأجر. راجع الحصول على معرف المستأجر المشفر
    a/qzXoWDkuqUa3l6zM5mM0Rw/ الاستخدام الداخلي فقط. عدم التعديل
    n/plugin مكون إضافي
    e/{environmentId} معرف البيئة
    i/{issuerHash} s/{subjectHash} تجزئة SHA-256 بترميز Base64URL للاسم المميّز الكامل (DN) لجهة الإصدار/الموضوع. راجع حساب تجزئات المُصدر والموضوع
    h/{hash} SHA-256 للشهادة (موقعة ذاتيا فقط)

احسب تجزئتَي الجهة المصدرة والموضوع

احسب تجزئة SHA-256 لسلسلتي الاسم المميز (DN) الكاملتين لكلٍّ من جهة الإصدار وصاحب الشهادة كما تظهران في الشهادة، ثم شفّر كلًّا منهما بتنسيق Base64 الآمن لعناوين URL. احصل على سلاسل DN باستخدام:

$cert = Get-PfxCertificate -FilePath "path\to\your.pfx"
Write-Host "Issuer:  $($cert.Issuer)"
Write-Host "Subject: $($cert.Subject)"

حساب التجزئات (PowerShell):

function Get-Sha256Base64Url {
    param([string]$InputString)
    $bytes = [System.Text.Encoding]::UTF8.GetBytes($InputString)
    $sha256 = [System.Security.Cryptography.SHA256]::Create()
    $hash = $sha256.ComputeHash($bytes)
    $base64 = [Convert]::ToBase64String($hash)
    return $base64.Replace('+', '-').Replace('/', '_').TrimEnd('=')
}

$issuerHash = Get-Sha256Base64Url -InputString "<full issuer DN string>"
$subjectHash = Get-Sha256Base64Url -InputString "<full subject DN string>"
Write-Host "Issuer Hash:  $issuerHash"
Write-Host "Subject Hash: $subjectHash"

أو في C#‎:

using System.Security.Cryptography;
using System.Text;

static string ComputeSha256Base64Url(string input)
{
    using var sha256 = SHA256.Create();
    byte[] hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(input));
    return Convert.ToBase64String(hashBytes)
        .Replace('+', '-')
        .Replace('/', '_')
        .TrimEnd('=');
}

الإخراج عبارة عن سلسلة مكونة من 43 حرفا تحتوي فقط A-Zعلى وa-z0-9-_.

مهم

استخدم سلسلة DN الدقيقة التي يستخدمها وقت التشغيل (.NET X509Certificate2.Issuer والخصائصX509Certificate2.Subject). لن يتطابق DN ذو التنسيق المختلف وسيفشل مع AADSTS700213.

ملاحظة

بالنسبة إلى عمليات النشر خارج السحابة العامة، قم بتعيين قيم خاصة بالسحابة. راجع البيئات السحابية Azure المتخصصة.

الخطوة 4: إنشاء سجل الهوية المدارة في Dataverse

إرسال طلب HTTP POST باستخدام عميل REST. بالنسبة للإصدار 2، قم بتعيين version إلى 2.

POST https://<<orgURL>>/api/data/v9.0/managedidentities

{
  "applicationid": "<<appId>>",
  "managedidentityid": "<<anyGuid>>",
  "credentialsource": 2,
  "subjectscope": 1,
  "tenantid": "<<tenantId>>",
  "version": 2
}

ثم قم بربط تجميع المكون الإضافي (أو الحزمة) بالسجل:

PATCH https://<<orgURL>>/api/data/v9.0/pluginassemblies(<<PluginAssemblyId>>)

{
  "managedidentityid@odata.bind": "/managedidentities(<<ManagedIdentityGuid>>)"
}

بالنسبة إلى حزمة مكوّن إضافي، استخدم pluginpackages(<<PluginPackageId>>) بدلًا من ذلك.

الخطوة 5: منح حق الوصول إلى مورد Azure

امنح التطبيق أو الهوية المدارة المعيّنة من قبل المستخدم حق الوصول إلى مورد Azure الذي يحتاج إليه، مثل Azure Key Vault.

الخطوة 6: التحقق من صحة التكامل

قم بتشغيل المكون الإضافي وتأكد من أنه يكتسب رمزا مميزا ويصل إلى مورد Azure دون بيانات اعتماد منفصلة.

الترقية إلى الإصدار 2

إذا كان لديك مكون إضافي في الإصدار 0 أو الإصدار 1، فيمكنك نقله إلى الإصدار 2 دون إعادة إنشاء المكون الإضافي أو إعادة تسجيله.

الخيار 1: Power Platform CLI

ملاحظة

لا تعمل أوامر الهوية المُدارة في واجهة سطر الأوامر (CLI) على أنظمة التشغيل المستندة إلى Linux أو مع الهوية المُدارة المعيّنة من قِبل المستخدم (UAMI). إذا لم يعمل CLI لشهادتك، فاستخدم الخيار 2: يدوي.

  1. تثبيت Power Platform CLI الإصدار 2.8.1 أو أحدث. راجع تثبيت Microsoft Power Platform CLI.
  2. إنشاء ملف تعريف مصادقة: pac auth create
  3. تحقق من الإصدار الحالي: pac managed-identity show-fic --environment <orgUrl> --component-type PluginAssembly --component-id <pluginAssemblyId> --version 2
  4. ترقيه: pac managed-identity upgrade-version --environment <orgUrl> --component-type PluginAssembly --component-id <pluginAssemblyId> --target-version 2 --confirm
  5. قم بتشغيل المكون الإضافي للتحقق من الصحة.

الخيار 2: يدوي

  1. احسب تجزئتَي الجهة المُصدِرة والموضوع للإصدار 2. راجع احسب تجزئات المُصدِر والموضوع.

  2. أضف رمز تعريف FIC جديدًا بتنسيق معرف موضوع الإصدار 2 (الخطوة 3).

  3. تحديث سجل الهوية المدارة إلى الإصدار 2:

    PATCH https://<<orgURL>>/api/data/v9.0/managedidentities(<<ManagedIdentityId>>)

    { "version": 2 }

  4. تشغيل المكون الإضافي والتحقق من نجاح اكتساب الرمز المميز.

  5. إزالة الإصدار القديم 1 FIC.

ملاحظة

تم إهمال الإصدار 0. يجري العمل على دعم إنشاء FIC الإصدار 2 عبر واجهة سطر الأوامر (CLI).

المرجع

الحصول على معرف المستأجر المشفر

معرف المستأجر المشفرة هو المعرف الفريد العمومي للمستأجر الذي تم تحويله إلى وحدات البايت وترميزه على أنه Base64URL (وليس Base64 القياسي):

$tenantId = "<your-tenant-guid>"
$tenantGuid = [System.Guid]::Parse($tenantId)
$tenantBytes = $tenantGuid.ToByteArray()
$base64 = [System.Convert]::ToBase64String($tenantBytes)
$encodedTenantId = $base64.Replace('+', '-').Replace('/', '_').TrimEnd('=')
$encodedTenantId

إنشاء شهادة موقعة ذاتيا

للتطوير أو الاختبار فقط:

$params = @{
    Type = 'Custom'
    Subject = 'E=admin@contoso.com,CN=Contoso'
    TextExtension = @(
        '2.5.29.37={text}1.3.6.1.5.5.7.3.4',
        '2.5.29.17={text}email=admin@contoso.com' )
    KeyAlgorithm = 'RSA'
    KeyLength = 2048
    SmimeCapabilities = $true
    CertStoreLocation = 'Cert:\CurrentUser\My'
}
New-SelfSignedCertificate @params

احسب {hash} ذاتي التوقيع (SHA-256 على .cer؛ صدِّره أولًا من .pfx إذا لزم الأمر):

CertUtil -hashfile <CertificateFilePath> SHA256

$cert = Get-PfxCertificate -FilePath "path\to\your.pfx"
$cert.RawData | Set-Content -Encoding Byte -Path "extracted.cer"

بيئات سحابة Azure المتخصصة

تعيين الجمهور وعنوان URL المصدروبادئة الموضوع بشكل صريح عند النشر خارج السحابة العامة و GCC ومحطة الإصدار الأولى في GCC.

مجموعة الجمهور عنوان URL المصدر بادئة الموضوع
جي سي سي هاي و وزارة الدفاع api://AzureADTokenExchangeUSGov https://login.microsoftonline.us /eid1/c/usg
Mooncake (الصين) api://AzureADTokenExchangeChina https://login.partner.microsoftonline.cn /eid1/c/chn
US National (USNAT) api://AzureADTokenExchangeUSNat https://login.microsoftonline.eaglex.ic.gov /eid1/c/uss
US Secure (USSec) api://AzureADTokenExchangeUSSec https://login.microsoftonline.scloud /eid1/c/usn

ملاحظة

قيمة الجمهور تراعي التمييز بين الأحرف الكبيرة والصغيرة. بالنسبة إلى السحابة العامة و GCC ومحطة الإصدار الأولى في GCC، تكون الإعدادات الافتراضية هي Audience api://AzureADTokenExchangeو Issuer https://login.microsoftonline.comو Subject prefix /eid1/c/pub.

الأسئلة المتداولة

كيف يمكنني حل AADSTS700213: لم يتم العثور على سجل هوية متحد مطابق؟

لا يتطابق معرف الموضوع المحسوب في وقت التشغيل مع أي FIC على التطبيق. تحقق مما يلي:

  1. لقد قمت بتكوين FIC وحفظه.
  2. تتوافق جهة الإصدار والموضوع مع التنسيق في الخطوة 3. يمكنك أيضا العثور على التنسيق المتوقع في مكدس الأخطاء.
  3. السجل version هو 2 ويستخدم FIC تنسيق التجزئة للإصدار 2.
  4. يتم حساب التجزئة من سلسلة DN الخاصة بوقت التشغيل (X509Certificate2.Issuer / X509Certificate2.Subject).
  5. المُصدر هو https://login.microsoftonline.com/{tenantId}/v2.0 والجمهور هو api://AzureADTokenExchange (تحسس حالة الأحرف).

كيف يمكنني حل AADSTS70050: لم يتم تنسيق مسار الهوية المدارة الموحدة بشكل صحيح؟

يحتوي معرف الموضوع على أحرف لا يقبلها موفر الهوية — غالبا الأحرف غير ASCII في الشهادة CN ضمن الإصدار 1. ينتج الإصدار 2 معرف موضوع ASCII فقط ويحل هذا الخطأ.

كيف يمكنني حل الخطأ "غير قادر على الوصول إلى Power Platform أو الاتصال به"؟

لضمان إمكانية الوصول إلى نقاط نهاية Power Platform وأن تكون مُدرجة في قوائم السماح، اطلع على عناوين URL ونطاقات عناوين IP الخاصة بـ Power Platform.

  • تاريخ آخر تحديث في