為 Dataverse 外掛或外掛套件設定 Power Platform 管理身份

當你使用 Power Platform 管理身份時，Dataverse 外掛或外掛套件可以在不管理憑證的情況下連接到 Azure 資源。 本文說明 推薦的（版本2） 設定，該架構從憑證完整識別名稱（DN）的雜湊值中建立聯邦身份憑證（FIC）。

為什麼選擇版本 2

版本 2 產生固定長度、僅支援 ASCII 的主體識別碼，因此可使用任何憑證名稱。 版本 1 在某些憑證名稱（CN）上失敗：

• CN 中的非 ASCII 字元（例如帶重音符號的字母）→AADSTS70050: The Federated Managed Identity path is not properly formatted。
• CN 中的逗號（例如，CN=Contoso, Inc.）→AADSTS700213: No matching federated identity record found。

先決條件

• 有權佈建使用者指派的受控識別 (UAMI) 或應用程式註冊的 Azure 訂閱。
• 外掛工具或外掛套件：
  • 整合開發環境（IDE），類似 Visual Studio，用於建置外掛
  • 外掛程式註冊工具
  • SignTool.exe (簽署工具) ，用於對外掛程式集進行簽署
  • Power Platform CLI
• 用於簽署外掛程式組件的有效憑證。

設定受控身分識別

1. 建立新的應用程式註冊或使用者指派的受控識別。
2. 建立、簽名並註冊外掛。
3. 設定聯邦身份憑證。
4. 在 Dataverse 建立管理身份記錄。
5. 授予 Azure 資源的存取權限。
6. 驗證整合。

步驟 1：建立應用程式註冊或使用者指派的管理身份

在 Microsoft Entra ID 中建立使用者指派的受控識別或應用程式：

• 對於與外掛相關的應用程式身份（以便套用 Azure 政策），請使用 Application registration。
• 為服務主體佈建使用者指派的受控識別。

步驟 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}	租戶 ID. 請參閱 取得編碼租戶ID
  a/qzXoWDkuqUa3l6zM5mM0Rw/	僅供內部使用。 不要修改
  n/plugin	外掛元件
  e/{environmentId}	環境識別碼
  i/{issuerHash} s/{subjectHash}	完整簽發者/主體 DN 的 SHA-256 Base64URL 雜湊值。 參見 計算發行者與主體雜湊值
  h/{hash}	憑證的 SHA-256 (僅限自我簽署)

計算簽發者與主體雜湊

取得憑證上所顯示完整簽發者與主體 DN 字串的 SHA-256 雜湊，並將每個雜湊值編碼為 URL 安全 Base64。 使用以下方式取得 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-z、0-9、- 和 _。

步驟 4：在 Dataverse 建立受管理身份記錄

透過 REST 用戶端發送 HTTP POST 請求。 版本 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，而不必重建或重新註冊該外掛。

選項一：Power Platform CLI

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. 新增一個採用第 2 版主體識別碼格式的 FIC（步驟 3）。

3. 將管理身份記錄更新為版本 2：

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

   { "version": 2 }
   

4. 觸發外掛程式，並確認是否成功取得權杖。

5. 移除舊版的第 1 版 FIC。

參考

取得編碼的租戶 ID

編碼的租戶 ID 是租戶 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} (對 .cer 計算 SHA-256；如有需要，先從 .pfx 匯出)：

CertUtil -hashfile <CertificateFilePath> SHA256

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

專用 Azure 雲端環境

在部署於公有雲、GCC 及 GCC 首個發佈站外時，請明確設定 受眾、 發行者網址及 主題前綴 。

常見問題集 (FAQ)

我該如何解決AADSTS700213：找不到匹配的聯邦身份紀錄？

執行時計算的主題識別碼與應用程式中的任何 FIC 都不匹配。 請確定：

1. 你已經設定並儲存了 FIC。
2. 簽發者與主體的格式與 Step 3 相符。 您也可以在錯誤堆疊中找到預期的格式。
3. 記錄 version 為 2，且 FIC 使用第 2 版雜湊格式。
4. 雜湊值是根據執行時的 DN 字串（X509Certificate2.Issuer / X509Certificate2.Subject）計算而得。
5. 發行人是， https://login.microsoftonline.com/{tenantId}/v2.0 受眾是 api://AzureADTokenExchange （大小寫區分）。

如何解決 AADSTS70050：同盟式受控識別路徑的格式不正確？

主體識別碼包含身分提供者不接受的字元——最常見的是第 1 版憑證的 CN 中含有非 ASCII 字元。 版本 2 產生僅 ASCII 的主體識別碼並解決此錯誤。

如何解決「無法連線或連線到 Power Platform」錯誤？

為確保 Power Platform 端點可被存取並列入允許名單，請參閱 Power Platform 網址與 IP 位址範圍。