Menyiapkan identitas terkelola Power Platform untuk plug-in Dataverse atau paket plug-in

Saat Anda menggunakan identitas terkelola Power Platform, plug-in Dataverse atau paket plug-in dapat tersambung ke sumber daya Azure tanpa mengelola kredensial. Artikel ini menjelaskan penyiapan yang direkomendasikan (versi 2), yang membangun kredensial identitas federasi (FIC) dari hash Nama Khusus (DN) sertifikat lengkap.

Note

Gunakan identitas terkelola Power Platform versi 2 untuk semua plug-in baru dan yang sudah ada. Jika Anda mempertahankan plug-in yang masih menggunakan format versi 1 (berbasis CN), lihat Menyiapkan identitas terkelola versi 1. Untuk memindahkan plug-in yang sudah ada ke versi 2, lihat Meningkatkan ke versi 2.

Mengapa versi 2

Versi 2 menghasilkan pengidentifikasi subjek khusus ASCII dengan panjang tetap, sehingga berfungsi dengan nama sertifikat apa pun. Versi 1 gagal pada nama sertifikat tertentu (CN):

• Karakter non-ASCII dalam CN (misalnya, huruf beraksen) → AADSTS70050: The Federated Managed Identity path is not properly formatted.
• Tanda koma di CN (misalnya, CN=Contoso, Inc.) → AADSTS700213: No matching federated identity record found.

Prasyarat

• Langganan Azure dengan akses untuk menyediakan identitas terkelola yang ditetapkan oleh pengguna (UAMI) atau pendaftaran aplikasi.
• Alat untuk plug-in atau paket plug-in:
  • Lingkungan Pengembangan Terintegrasi (IDE), seperti Visual Studio, untuk membangun plug-in
  • Alat registrasi Plugin
  • SignTool.exe (Alat tanda tangan ) untuk menandatangani rakitan plug-in
  • Power Platform CLI
• Sertifikat yang valid untuk menandatangani rakitan plug-in.

Menyiapkan identitas terkelola

1. Buat pendaftaran aplikasi baru atau identitas terkelola yang ditetapkan pengguna.
2. Buat, tanda tangani, dan daftarkan plugin.
3. Konfigurasikan kredensial identitas federasi.
4. Buat rekaman identitas terkelola di Dataverse.
5. Berikan akses ke sumber daya Azure.
6. Validasikan integrasi.

Langkah 1: Membuat pendaftaran aplikasi atau identitas terkelola yang ditetapkan pengguna

Buat identitas terkelola yang ditetapkan pengguna atau aplikasi di Microsoft Entra ID:

• Untuk identitas aplikasi yang terkait dengan plug-in (sehingga Anda dapat menerapkan kebijakan Azure), gunakan pendaftaran aplikasi.
• Untuk prinsipal layanan, sediakan identitas terkelola yang ditetapkan pengguna.

Note

Ambil ID Aplikasi (klien) dan ID Penyewa — Anda menggunakannya di langkah selanjutnya.

Langkah 2: Kompilasi, tandatangani, dan daftarkan plug-in

1. Membuat plug-in di Visual Studio. Gunakan ID penyewa dari langkah 1 dan cakupan seperti https://{OrgName}.crm*.dynamics.com/.default. Gunakan IManagedIdentityService untuk meminta token:

   string AcquireToken(IEnumerable<string> scopes);
   

2. Tandatangani plug-in dengan sertifikat Anda.

   Paket pengaya (NuGet):

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

   Rakitan Plug-in (SignTool):

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

3. Daftarkan plug-in menggunakan alat pendaftaran plug-in.

Note

Gunakan sertifikat yang ditandatangani sendiri hanya untuk pengembangan atau pengujian. Jangan gunakan sertifikat yang ditandatangani sendiri dalam produksi. Untuk membuatnya, lihat Membuat sertifikat yang ditandatangani sendiri.

Langkah 3: Mengonfigurasi kredensial identitas federasi

Di portal Azure, buka aplikasi atau identitas terkelola yang ditetapkan pengguna (UAMI), lalu buka Sertifikat & rahasia>Kredensial federasi>Tambahkan kredensial, dan pilih Penerbit lain. Kemudian masukkan:

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

• Jenis — Pengidentifikasi subjek eksplisit

• Pengidentifikasi subjek — gunakan format untuk jenis sertifikat Anda:

  • Sertifikat penerbit tepercaya (produksi):

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

  • Sertifikat swatanda tangan (hanya pengembangan):

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

  Referensi segmen

  Segmen	Description
  eid1	Versi format identitas
  c/pub	Kode cloud untuk cloud publik, GCC, dan stasiun rilis pertama di GCC
  t/{encodedTenantId}	ID Penyewa. Lihat Mendapatkan ID penyewa yang dikodekan
  a/qzXoWDkuqUa3l6zM5mM0Rw/	Hanya penggunaan internal. Jangan ubah
  n/plugin	Komponen plugin
  e/{environmentId}	ID Lingkungan
  i/{issuerHash} s/{subjectHash}	Hash SHA-256 Base64URL dari DN lengkap penerbit/subjek. Lihat Menghitung hash penerbit dan subjek
  h/{hash}	SHA-256 sertifikat (hanya ditandatangani sendiri)

Komputasi hash penerbit dan subjek

Hitung hash SHA-256 dari string DN penerbit dan subjek lengkap sebagaimana tercantum pada sertifikat, lalu kodekan masing-masing sebagai Base64 yang aman untuk URL. Dapatkan string DN dengan:

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

Komputasi 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"

Atau di 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('=');
}

Outputnya adalah string dengan panjang 43 karakter yang berisi hanya A-Z, a-z, 0-9, -, dan _.

Important

Gunakan string DN yang tepat yang digunakan oleh runtime (properti .NET X509Certificate2.Issuer dan X509Certificate2.Subject). DN yang diformat berbeda tidak akan cocok dan gagal dengan AADSTS700213.

Note

Untuk penyebaran di luar cloud publik, atur nilai khusus cloud. Lihat Lingkungan cloud Azure khusus.

Langkah 4: Membuat rekaman identitas terkelola di Dataverse

Kirim permintaan HTTP POST dengan menggunakan klien REST. Untuk versi 2, atur version ke 2.

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

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

Kemudian, tautkan rakitan plugin (atau paket) ke record:

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

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

Untuk paket plug-in, gunakan pluginpackages(<<PluginPackageId>>) sebagai gantinya.

Langkah 5: Memberikan akses ke sumber daya Azure

Berikan aplikasi atau akses identitas terkelola yang ditetapkan pengguna ke sumber daya Azure yang dibutuhkannya, seperti Azure Key Vault.

Langkah 6: Memvalidasi integrasi

Jalankan plug-in tersebut dan konfirmasikan bahwa plug-in itu memperoleh token serta dapat mengakses sumber daya Azure tanpa kredensial terpisah.

Tingkatkan ke versi 2

Jika Anda memiliki plug-in pada versi 0 atau versi 1, Anda dapat memindahkannya ke versi 2 tanpa membangun kembali atau mendaftarkan ulang plug-in.

Opsi 1: Power Platform CLI

Note

Kata kerja identitas yang dikelola CLI tidak berfungsi pada sistem operasi berbasis Linux atau dengan identitas terkelola yang ditetapkan pengguna (UAMI). Jika CLI tidak berfungsi untuk sertifikat Anda, gunakan Opsi 2: Manual.

1. Instal Power Platform CLI versi 2.8.1 atau yang lebih baru. Lihat Menginstal CLI Microsoft Power Platform.
2. Membuat profil autentikasi: pac auth create
3. Periksa versi saat ini: pac managed-identity show-fic --environment <orgUrl> --component-type PluginAssembly --component-id <pluginAssemblyId> --version 2
4. Mutakhirkan: pac managed-identity upgrade-version --environment <orgUrl> --component-type PluginAssembly --component-id <pluginAssemblyId> --target-version 2 --confirm
5. Picu plug-in untuk memvalidasi.

Opsi 2: Manual

1. Komputasi hash penerbit dan subjek versi 2. Lihat Menghitung hash penerbit dan subjek.

2. Tambahkan FIC baru dengan format pengidentifikasi subjek versi 2 (Langkah 3).

3. Perbarui catatan identitas terkelola ke versi 2:

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

   { "version": 2 }
   

4. Jalankan plug-in dan verifikasi bahwa perolehan token berhasil.

5. Hapus FIC versi lama 1.

Note

Versi 0 tidak digunakan lagi. Dukungan CLI untuk menghasilkan FIC versi 2 sedang berlangsung.

Referensi

Dapatkan ID tenant yang dienkode

ID penyewa yang dikodekan adalah GUID penyewa yang dikonversi ke byte dan dikodekan sebagai Base64URL (bukan Base64 standar):

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

Membuat sertifikat yang ditandatangani sendiri

Hanya untuk pengembangan atau pengujian:

$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

Hitung {hash} yang ditandatangani sendiri (SHA-256 atas .cer; ekspor dari .pfx terlebih dahulu jika perlu):

CertUtil -hashfile <CertificateFilePath> SHA256

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

Lingkungan cloud Azure terkhusus

Atur Audiens, URL Penerbit, dan Awalan subjek secara eksplisit saat melakukan penyebaran di luar cloud publik, GCC, dan stasiun rilis pertama di GCC.

Cloud	Audiens	URL Pengeluar Sertifikat	Awalan subjek
GCC High dan DoD	api://AzureADTokenExchangeUSGov	https://login.microsoftonline.us	/eid1/c/usg
Mooncake (Tiongkok)	api://AzureADTokenExchangeChina	https://login.partner.microsoftonline.cn	/eid1/c/chn
Nasional AS (USNAT)	api://AzureADTokenExchangeUSNat	https://login.microsoftonline.eaglex.ic.gov	/eid1/c/uss
US Secure (USSec)	api://AzureADTokenExchangeUSSec	https://login.microsoftonline.scloud	/eid1/c/usn

Note

Nilai Audience peka terhadap huruf besar/kecil. Untuk cloud publik, GCC, dan saluran rilis pertama di GCC, default-nya adalah Audiens api://AzureADTokenExchange, Penerbit https://login.microsoftonline.com, dan Awalan subjek /eid1/c/pub.

Pertanyaan Umum

Bagaimana cara mengatasi AADSTS700213: Tidak ditemukan catatan identitas federasi yang cocok?

Pengidentifikasi subjek yang dihitung saat runtime tidak cocok dengan FIC apa pun di aplikasi. Periksa apakah:

1. Anda mengonfigurasi dan menyimpan FIC.
2. Penerbit dan subjek sesuai dengan format pada Langkah 3. Anda juga dapat menemukan format yang diharapkan dalam tumpukan kesalahan.
3. Catatannya version adalah 2 dan FIC menggunakan format hash versi 2.
4. Hash dihitung dari string DN runtime (X509Certificate2.Issuer / X509Certificate2.Subject).
5. Penerbit adalah https://login.microsoftonline.com/{tenantId}/v2.0 dan audiensnya api://AzureADTokenExchange (peka huruf besar/kecil).

Bagaimana cara mengatasi AADSTS70050: Jalur Identitas Terkelola Federasi tidak diformat dengan benar?

Pengenal subjek berisi karakter yang tidak diterima oleh penyedia identitas — paling sering karakter non-ASCII pada CN sertifikat versi 1. Versi 2 menghasilkan pengidentifikasi subjek khusus ASCII dan mengatasi kesalahan ini.

Bagaimana cara mengatasi kesalahan "Tidak dapat menjangkau atau menyambungkan ke Power Platform"?

Untuk memastikan endpoint Power Platform dapat dijangkau dan ditambahkan ke daftar yang diizinkan, lihat URL Power Platform dan rentang alamat IP.