Einrichten der verwalteten Power Platform-Identität für Dataverse-Plug-Ins oder Plug-In-Pakete

Wenn Sie verwaltete Power Platform-Identität verwenden, können Dataverse-Plug-Ins oder Plug-In-Pakete eine Verbindung mit Azure Ressourcen herstellen, ohne Anmeldeinformationen zu verwalten. In diesem Artikel wird das empfohlene Setup (Version 2) beschrieben, das die Verbundidentitätsanmeldeinformationen (FIC) aus einem Hash des vollständigen Distinguished Name (DN) des Zertifikats erstellt.

Warum Version 2

Version 2 erzeugt einen Antragstellerbezeichner fester Länge, der nur aus ASCII-Zeichen besteht, sodass er mit jedem Zertifikatsnamen verwendet werden kann. Version 1 schlägt bei bestimmten Zertifikatnamen (CNs) fehl:

• Nicht-ASCII-Zeichen im CN (z. B. Akzentbuchstaben) → AADSTS70050: The Federated Managed Identity path is not properly formatted.
• Kommas im CN (z. B. CN=Contoso, Inc.) → AADSTS700213: No matching federated identity record found.

Voraussetzungen

• Ein Azure-Abonnement mit Zugriff auf die Bereitstellung von vom Benutzer zugewiesener verwalteter Identität (UAMI) oder Anwendungsregistrierung.
• Tools für Plug-Ins oder Plug-In-Pakete:
  • Integrierte Entwicklungsumgebung (Integrated Development Environment, IDE) wie Visual Studio zum Erstellen von Plug-Ins
  • Plug-in Registration Tool
  • SignTool.exe (Signiertool),, um die Plug-In-Assembly zu signieren
  • Power Platform CLI
• Ein gültiges Zertifikat zum Signieren der Plug-In-Assembly.

Einrichten einer verwalteten Identität

1. Erstellen Sie eine neue App-Registrierung oder eine benutzerseitig zugewiesene verwaltete Identität.
2. Erstellen, Signieren und Registrieren des Plug-Ins.
3. Konfigurieren Sie die Verbundidentitätsanmeldeinformationen.
4. Erstellen Sie den verwalteten Identitätsdatensatz in Dataverse.
5. Gewähren des Zugriffs auf die Azure-Ressource.
6. Überprüfen Sie die Integration.

Schritt 1: Erstellen einer App-Registrierung oder einer vom Benutzer zugewiesenen verwalteten Identität

Erstellen Sie entweder eine vom Benutzer zugewiesene verwaltete Identität oder eine Anwendung in Microsoft Entra ID:

• Verwenden Sie für eine app-Identität, die dem Plug-In zugeordnet ist (sodass Sie Azure Richtlinien anwenden können), die Anwendungsregistrierung.
• Stellen Sie für einen Dienstprinzipal eine vom Benutzer zugewiesene verwaltete Identität bereit.

Schritt 2: Erstellen, Signieren und Registrieren des Plug-Ins

1. Erstellen Sie ein Plug-In in Visual Studio. Verwenden Sie die Mandanten-ID aus Schritt 1 und einen Bereich wie https://{OrgName}.crm*.dynamics.com/.default. Verwenden Sie IManagedIdentityService , um ein Token anzufordern:

   string AcquireToken(IEnumerable<string> scopes);
   

2. Signieren Sie das Plug-In mit Ihrem Zertifikat.

   Plug-In-Paket (NuGet):

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

   Plug-in-Montage (SignTool):

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

3. Registrieren Sie das Plug-In mithilfe des Plug-In-Registrierungstools.

Schritt 3: Konfigurieren der Verbundidentitäts-Anmeldeinformationen

Öffnen Sie im Azure-Portal Ihre App oder Ihre benutzerseitig zugewiesene verwaltete Identität (UAMI), wechseln Sie zu Zertifikate & Geheimnisse>Verbundanmeldeinformationen>Anmeldeinformationen hinzufügen, und wählen Sie Anderer Aussteller aus. Geben Sie dann Folgendes ein:

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

• Typ — Expliziter Subjektbezeichner

• Subjektbezeichner — verwenden Sie das Format für Ihren Zertifikattyp:

  • Vertrauenswürdiges Ausstellerzertifikat (Produktion):

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

  • Selbstsigniertes Zertifikat (nur Entwicklung):

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

  Segmentreferenz

  Segment	Description
  eid1	Identitätsformatversion
  c/pub	Cloud-Code für öffentliche Cloud, GCC und erste Release-Station in GCC
  t/{encodedTenantId}	Mandanten-ID. Siehe Abrufen der codierten Mandanten-ID
  a/qzXoWDkuqUa3l6zM5mM0Rw/	Nur interne Verwendung. Nicht ändern
  n/plugin	Plug-In-Komponente
  e/{environmentId}	Umgebungs-ID
  i/{issuerHash} s/{subjectHash}	SHA-256 Base64URL-Hash des vollständigen Ausstellers/Betreffs DN. Siehe Issuer- und Subject-Hashes berechnen
  h/{hash}	SHA-256 des Zertifikats (nur selbstsigniert)

Aussteller- und Subjekt-Hash berechnen

Bilden Sie den SHA-256-Hash der vollständigen DN-Zeichenfolgen des Ausstellers und des Subjekts, wie sie im Zertifikat erscheinen, und kodieren Sie jede davon als URL-sicheres Base64. Abrufen der DN-Zeichenfolgen mit:

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

Berechnen der Hashes (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"

Oder in 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('=');
}

Die Ausgabe ist eine 43-stellige Zeichenfolge, die nur A-Z, a-z, 0-9, - und _ enthält.

Schritt 4: Erstellen des verwalteten Identitätsdatensatzes in Dataverse

Senden Sie eine HTTP POST-Anforderung mithilfe eines REST-Clients. Für Version 2 setzen Sie version auf 2.

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

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

Verknüpfen Sie dann die Plug-In-Assembly (oder das Paket) mit dem Datensatz:

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

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

Verwenden Sie pluginpackages(<<PluginPackageId>>) stattdessen für ein Plug-In-Paket.

Schritt 5: Gewähren des Zugriffs auf die Azure-Ressource

Gewähren Sie der Anwendung oder der vom Benutzer zugewiesenen verwalteten Identität Zugriff auf die benötigten Azure Ressource, z. B. Azure Key Vault.

Schritt 6: Überprüfen der Integration

Starten Sie das Plug-in und bestätigen Sie, dass es ein Token erhält und ohne gesonderte Anmeldeinformationen auf die Azure-Ressource zugreifen kann.

Upgrade auf Version 2

Wenn Sie über ein Plug-In mit Version 0 oder Version 1 verfügen, können Sie es auf Version 2 verschieben, ohne das Plug-In neu zu erstellen oder erneut zu registrieren.

Option 1: Power Platform CLI

1. Installieren Sie Power Platform CLI, Version 2.8.1 oder höher. Siehe Installieren Microsoft Power Platform CLI.
2. Erstellen Eines Authentifizierungsprofils: pac auth create
3. Überprüfen Sie die aktuelle Version: pac managed-identity show-fic --environment <orgUrl> --component-type PluginAssembly --component-id <pluginAssemblyId> --version 2
4. Upgrade: pac managed-identity upgrade-version --environment <orgUrl> --component-type PluginAssembly --component-id <pluginAssemblyId> --target-version 2 --confirm
5. Aktivieren Sie das Plug-in, um die Validierung durchzuführen.

Option 2: Manuell

1. Berechnen Sie die Hashes von Aussteller und Subjekt der Version 2. Siehe die Berechnung der Aussteller- und Subjekt-Hashes.

2. Fügen Sie ein neues FIC mit dem Subjektbezeichnerformat der Version 2 (Schritt 3) hinzu.

3. Aktualisieren sie den verwalteten Identitätsdatensatz auf Version 2:

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

   { "version": 2 }
   

4. Starten Sie das Plug-In, und überprüfen Sie, ob das Abrufen des Tokens erfolgreich ist.

5. Entfernen Sie die alte Version 1 FIC.

Reference

Rufen Sie die codierte Mandanten-ID ab

Die codierte Mandanten-ID ist die Mandanten-GUID, die in Bytes konvertiert und als Base64URL codiert wird (nicht als Base64-Standard):

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

Generieren eines selbstsignierten Zertifikats

Nur für Entwicklung oder Tests:

$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

Berechnen Sie die selbstsignierte {hash} (SHA-256 über .cer; falls nötig, exportieren Sie es zuerst aus einem .pfx):

CertUtil -hashfile <CertificateFilePath> SHA256

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

Spezialisierte Azure-Cloudumgebungen

Legen Sie das Präfix "Zielgruppe", "Aussteller-URL" und " Betreff" explizit fest, wenn Sie außerhalb der öffentlichen Cloud, GCC und der ersten Veröffentlichungsstation in GCC bereitstellen.

Häufig gestellte Fragen (FAQs)

Wie behebe ich AADSTS700213: Es wurde kein übereinstimmender Verbundidentitätsdatensatz gefunden?

Der zur Laufzeit berechnete Subjektbezeichner stimmt mit keinem FIC in der App überein. Überprüfen Sie Folgendes:

1. Sie haben den FIC konfiguriert und gespeichert.
2. Der Aussteller und der Betreff stimmen mit dem Format in Schritt 3 überein. Sie können auch das erwartete Format im Fehlerstapel finden.
3. Der Datensatz version ist 2 und der FIC verwendet das Hashformat der Version 2.
4. Der Hash wird aus der DN-Zeichenfolge (X509Certificate2.Issuer / X509Certificate2.Subject) der Laufzeit berechnet.
5. Der Aussteller ist https://login.microsoftonline.com/{tenantId}/v2.0 und die Zielgruppe ist api://AzureADTokenExchange (Groß-/Kleinschreibung beachten).

Wie behebt ich AADSTS70050: Der Pfad der verwalteten Verbundidentität ist nicht ordnungsgemäß formatiert?

Der Subjektbezeichner enthält Zeichen, die der Identitätsanbieter nicht akzeptiert – meistens nicht-ASCII-Zeichen im CN des Zertifikats der Version 1. Version 2 erzeugt einen nur ASCII-Zeichen enthaltenden Subjektbezeichner und behebt dadurch diesen Fehler.

Wie kann ich den Fehler "Keine Verbindung mit Power Platform herstellen" beheben?

Informationen dazu, dass Power Platform-Endpunkte erreichbar und zugelassen sind, finden Sie unter Power Platform-URLs und IP-Adressbereiche.