הגדרת זהות מנוהלת של Power Platform עבור יישומי Plug-in או חבילות יישומי Plug-in של Dataverse

בעת שימוש זהות מנוהלת של Power Platform, יישומי Plug-in או חבילות יישומי Plug-in של Dataverse יכולים להתחבר Azure משאבים ללא ניהול אישורים. מאמר זה מתאר את ההגדרה המומלצת (גירסה 2), אשר בונה את אישור הזהות המאוחדת (FIC) מ- Hash של השם הייחודי המלא (DN) של האישור.

הערה

השתמש בגירסה 2 של הזהות המנוהלת של Power Platform עבור כל יישומי ה- Plug-in החדשים והקיימים. אם אתה שומר תוסף שעדיין משתמש בתבנית של גירסה 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) או רישום יישומים שהוקצה למשתמש.
• כלים לתוסף או חבילות תוסף:
  • סביבת פיתוח משולבת (IDE), כגון Visual Studio, לבניית תוסף
  • Plug-in Registration Tool
  • SignTool.exe (כלי החתימה - Sign Tool) כדי לחתום על הרכבה של יישום plug-in
  • Power Platform CLI
• אישור חוקי כדי לחתום על הרכבת התוסף.

הגדרת זהות מנוהלת

1. צור רישום אפליקציה חדש או זהות מנוהלת שהוקצתה על-ידי המשתמש.
2. בנה, חתום ורשום את התוסף.
3. קבע את התצורה של אישור הזהות המאוחדת.
4. צור את רשומת הזהות המנוהלת ב- Dataverse.
5. הענק גישה אל משאב Azure.
6. אמת את האינטגרציה.

שלב 1: יצירת רישום יישום או זהות מנוהלת שהוקצתה למשתמש

צור זהות מנוהלת שהוקצתה למשתמש או יישום ב- Microsoft Entra ID:

• עבור זהות יישום המשויכת לתוסף (כדי שתוכל להחיל מדיניות Azure), השתמש ברישום יישומים.
• עבור מנהל שירות, הקצה זהות מנוהלת שהוקצתה למשתמש.

הערה

רשום את מזהה היישום (לקוח) ואת מזהה הדייר — תשתמש בהם בשלבים הבאים.

שלב 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), >> עבור אל אישורים וסודות אישורים מאוחדים הוסףאישור ובחר באפשרות נפפיק אחר. לאחר מכן הזן:

• Issuer — https://login.microsoftonline.com/{tenantID}/v2.0

• Type — מזהה נושא מפורש

• מזהה נושא – השתמש בתבנית עבור סוג האישור שלך:

  • אישור של מנפיק מהימן (סביבת ייצור):

    /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 המלא של המנפיק/הנושא. עיינו במאמר חישוב קודי Hash של נושאים ומנפיקים
  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)"

חשב את קוד ה- Hash (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-z, 0-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 של קודי Hash של נושאים ומנפיקים. ראה חשב את ערכי הגיבוב של המנפיק ושל הנושא.

2. הוסף FIC חדש עם תבנית מזהה הנושא של גירסה 2 (שלב 3).

3. עדכן את רשומת הזהות המנוהלת לגירסה 2:

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

   { "version": 2 }
   

4. הפעל את התוסף וודא שהרכישה של האסימון הצליחה.

5. הסר את הגירסה הישנה 1 FIC.

הערה

גירסה 0 אינה נמצאת עוד בשימוש. תמיכה ב- CLI ליצירת גירסה 2 FIC מתבצעת.

אסמכתא

קבל את מזהה הדייר המקודד

מזהה הדייר המקודד הוא ה- GUID של הדייר שהומר לבתים ומקודד כ- 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 של המנפיק	קידומת נושא
GCC High ו-DoD	api://AzureADTokenExchangeUSGov	https://login.microsoftonline.us	/eid1/c/usg
עוגת ירח (סין)	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, ברירות המחדל הן קהל api://AzureADTokenExchange, https://login.microsoftonline.comנושא , קידומת נושא /eid1/c/pub.

שאלות נפוצות (FAQ)

כיצד ניתן לפתור AADSTS700213: לא נמצאה רשומת זהות מאוחדת תואמת?

מזהה הנושא שחושב בזמן ריצה אינו תואם ל- FIC כלשהו ביישום. בדוק זאת:

1. קבעת את תצורת ה- FIC ושמרת אותו.
2. המנפיק והנושא תואמים לפורמט שב־שלב 3. באפשרותך גם למצוא את התבנית הצפויה בערימת השגיאות.
3. הרשומה version היא וה 2 - FIC משתמש בתבנית Hash של גירסה 2.
4. ה- Hash מחושב ממחרוזת ה- 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.