Verwenden Sie Zertifikate mit Microsoft. Identity.Web

Microsoft. Identity.Web unterstützt zertifikatbasierte Authentifizierung als sichere Alternative zu geheimen Clientschlüsseln für vertrauliche Clientanwendungen. Zertifikate verwenden asymmetrische Kryptografie, sodass sich nur der private Schlüsselinhaber authentifizieren kann.

In diesem Artikel konfigurieren Sie Zertifikatanmeldeinformationen aus verschiedenen Quellen, registrieren sie bei Ihrer App und verwalten sie in der Produktion.

Warum Zertifikate verwenden?

So funktioniert es

1. Sie generieren oder erhalten ein X.509-Zertifikat mit einem privaten Schlüssel.
2. Sie registrieren den public-Schlüssel (oder Fingerabdruck) des Zertifikats bei Ihrer Microsoft Entra App-Registrierung.
3. Zur Laufzeit Microsoft. Identity.Web lädt das Zertifikat (einschließlich des privaten Schlüssels) aus Ihrer konfigurierten Quelle.
4. Die Bibliothek verwendet den privaten Schlüssel, um eine Client assertion zu signieren, die an Microsoft Entra ID gesendet wird, um Token abzurufen.

Zertifikatquellen

Microsoft. Identity.Web unterstützt das Laden von Zertifikaten aus mehreren Quellen:

Sie konfigurieren Zertifikatanmeldeinformationen im Array in ClientCertificates Ihrem AzureAd (oder AzureAdB2C) Konfigurationsabschnitt. Sie können mehrere Zertifikate für Drehungsszenarien angeben – Microsoft. Identity.Web verwendet das erste gültige Zertifikat, das gefunden wird.

Von Azure Key Vault (empfohlen)

Azure Key Vault ist die empfohlene Quelle für Zertifikate in der Produktion. Es bietet zentrale Verwaltung, Zugriffssteuerung, Überwachung und automatische Rotationsfunktionen.

Konfiguration

Fügen Sie die Zertifikatkonfiguration zu Ihrer appsettings.json hinzu:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

Einrichten von Key Vault Zugriffsrichtlinien

Die Identität Ihrer Anwendung muss über die Berechtigung zum Lesen von Zertifikaten aus dem Key Vault verfügen. Wie Sie dies gewähren, hängt davon ab, ob Sie das Richtlinienmodell für den Tresorzugriff oder Azure rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) verwenden.

Option 1: Tresorzugriffsrichtlinie

az keyvault set-policy \
  --name your-keyvault-name \
  --object-id <app-or-managed-identity-object-id> \
  --certificate-permissions get list \
  --secret-permissions get

Option 2: Azure RBAC

Weisen Sie die Rolle Key Vault Zertifikatbenutzer der Identität Ihrer Anwendung zu:

az role assignment create \
  --role "Key Vault Certificate User" \
  --assignee <app-or-managed-identity-object-id> \
  --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>

Verwenden der verwalteten Identität für den Zugriff auf Key Vault

Wenn Ihre App in Azure ausgeführt wird (App Service, Azure Functions, Azure Kubernetes Service, VMs), verwenden Sie verwaltete Identität, um sich bei Key Vault zu authentifizieren. Dadurch wird die Notwendigkeit von Anmeldeinformationen für den Zugriff auf den Tresor selbst beseitigt.

Vom System zugewiesene verwaltete Identität

Wenn Ihre App eine vom System zugewiesene verwaltete Identität aktiviert hat, Microsoft. Identity.Web verwendet automatisch DefaultAzureCredential, um sich bei Key Vault zu authentifizieren. Über den ClientCertificates Eintrag hinaus ist keine zusätzliche Konfiguration erforderlich:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

Benutzerdefinierte verwaltete Identität

Geben Sie für eine vom Benutzer zugewiesene verwaltete Identität den ManagedIdentityClientId für den Key Vault Zertifikatdeskriptor an:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Aus dem Zertifikatspeicher (nur Windows)

Auf Windows können Sie Zertifikate aus dem Windows Zertifikatspeicher laden. Dies ist üblich für lokale oder von IIS gehostete Bereitstellungen.

Durch Fingerabdruck

Wird StoreWithThumbprint verwendet, um das Zertifikat anhand seines SHA-1-Fingerabdrucks zu identifizieren:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateThumbprint": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2"
      }
    ]
  }
}

Nach dem Distinguished Name

Verwenden Sie StoreWithDistinguishedName, um das Zertifikat anhand des Betreffnamens zu identifizieren:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateDistinguishedName": "CN=MyAppCertificate"
      }
    ]
  }
}

Zertifikatspeicherorte

In der folgenden Tabelle sind allgemeine Zertifikatspeicherpfade und die berechtigungen aufgeführt, die für den Zugriff erforderlich sind:

Vom Dateipfad

Sie können ein Zertifikat direkt aus einer .pfx (PKCS#12)-Datei auf dem Datenträger laden.

Konfiguration

Fügen Sie den Zertifikatdateipfad und das Kennwort zu Ihrem appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/path/to/certificate.pfx",
        "CertificatePassword": "your-certificate-password"
      }
    ]
  }
}

dotnet user-secrets set "AzureAd:ClientCertificates:0:CertificatePassword" "your-password"

export AzureAd__ClientCertificates__0__CertificatePassword="your-password"

Von Base64-enkodiertem Wert

Sie können das Zertifikat als base64-codierte Zeichenfolge bereitstellen. Dieser Ansatz ist nützlich, wenn Sie Zertifikate über Umgebungsvariablen, Kubernetes-Schlüssel oder CI/CD-Pipelinevariablen einfügen.

Konfiguration

Fügen Sie den Base64-codierten Zertifikatwert zu Ihrem appsettings.json:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg..."
      }
    ]
  }
}

Generieren des Base64-Werts

Konvertieren einer .pfx Datei in eine Base64-Zeichenfolge:

PowerShell:

$certBytes = [System.IO.File]::ReadAllBytes("path/to/certificate.pfx")
$base64 = [System.Convert]::ToBase64String($certBytes)
$base64 | Set-Clipboard  # Copies to clipboard

Bash:

base64 -w 0 path/to/certificate.pfx

Verwendung mit Geheimschlüsseln von Kubernetes

Speichern Sie das Base64-codierte Zertifikat in einem Kubernetes-Schlüssel, und ordnen Sie es einer Umgebungsvariable zu:

apiVersion: v1
kind: Secret
metadata:
  name: app-cert-secret
type: Opaque
data:
  AzureAd__ClientCertificates__0__Base64EncodedValue: <base64-encoded-pfx>

Verweisen Sie in Ihrer Bereitstellung auf das Geheimnis:

env:
  - name: AzureAd__ClientCertificates__0__SourceType
    value: "Base64Encoded"
  - name: AzureAd__ClientCertificates__0__Base64EncodedValue
    valueFrom:
      secretKeyRef:
        name: app-cert-secret
        key: AzureAd__ClientCertificates__0__Base64EncodedValue

Verwendung in CI/CD-Pipelines

Speichern Sie in Azure DevOps oder GitHub Actions das base64-codierte Zertifikat als geheime Variable, und legen Sie es dann zur Laufzeit als Umgebungsvariable fest.

GitHub Actions beispiel:

env:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: ${{ secrets.APP_CERTIFICATE_BASE64 }}

Azure DevOps beispiel:

variables:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: $(AppCertificateBase64)

Konfigurieren von Zertifikaten im C#-Code

Zusätzlich zur JSON-Konfiguration können Sie Zertifikatanmeldeinformationen programmgesteuert mithilfe der klasse CredentialDescription aus Microsoft.Identity.Abstractions konfigurieren.

Hilfsmethoden

Die CredentialDescription Klasse stellt statische Hilfsmethoden für jeden Zertifikatquelltyp bereit:

using Microsoft.Identity.Abstractions;

// From Azure Key Vault
var kvCredential = CredentialDescription.FromKeyVault(
    "https://your-keyvault-name.vault.azure.net",
    "your-certificate-name");

// From certificate store (by thumbprint)
var thumbprintCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2");

// From certificate store (by distinguished name)
var dnCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=MyAppCertificate");

// From file path
var pathCredential = CredentialDescription.FromCertificatePath(
    "/path/to/certificate.pfx",
    "your-certificate-password");

// From Base64-encoded string
var base64Credential = CredentialDescription.FromBase64String(
    "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg...");

Verwendung in ASP.NET Core

Übergeben Sie die Beschreibungen der Anmeldeinformationen direkt beim Konfigurieren der Authentifizierung:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "your-client-id";
        options.ClientCredentials = new[]
        {
            CredentialDescription.FromKeyVault(
                "https://your-keyvault-name.vault.azure.net",
                "your-certificate-name")
        };
    });

Erstellen eines selbstsignierten Zertifikats für die Entwicklung

Für lokale Entwicklung und Tests können Sie ein selbstsigniertes Zertifikat erstellen. Verwenden Sie keine selbstsignierten Zertifikate in der Produktion.

Verwenden von PowerShell (Windows)

Führen Sie die folgenden Befehle aus, um ein selbstsigniertes Zertifikat zu erstellen, zu exportieren und den Fingerabdruck anzuzeigen:

$cert = New-SelfSignedCertificate `
  -Subject "CN=MyDevCertificate" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyExportPolicy Exportable `
  -KeySpec Signature `
  -KeyLength 2048 `
  -KeyAlgorithm RSA `
  -HashAlgorithm SHA256 `
  -NotAfter (Get-Date).AddYears(2)

# Export the .pfx file (with private key)
$password = ConvertTo-SecureString -String "YourPassword123!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath ".\MyDevCertificate.pfx" -Password $password

# Export the .cer file (public key only — for app registration)
Export-Certificate -Cert $cert -FilePath ".\MyDevCertificate.cer"

# Display the thumbprint
Write-Host "Thumbprint: $($cert.Thumbprint)"

Verwenden von OpenSSL (plattformübergreifend)

Führen Sie die folgenden Befehle aus, um ein Zertifikat zu generieren, es als .pfx Datei zu packen und den Fingerabdruck anzuzeigen:

# Generate a self-signed certificate and private key
openssl req -x509 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -days 730 -nodes \
  -subj "/CN=MyDevCertificate"

# Package into a .pfx file
openssl pkcs12 -export \
  -out MyDevCertificate.pfx \
  -inkey key.pem -in cert.pem \
  -passout pass:YourPassword123!

# Get the thumbprint
openssl x509 -in cert.pem -noout -fingerprint -sha1

Verwenden der .NET CLI

Exportieren eines HTTPS-Entwicklungszertifikats als .pfx Datei:

dotnet dev-certs https --export-path ./MyDevCertificate.pfx --password YourPassword123!

Registrieren des Zertifikats in Microsoft Entra ID

Nachdem Sie ein Zertifikat erstellt oder erhalten haben, müssen Sie den öffentlichen Schlüssel bei Ihrer App-Registrierung in Microsoft Entra ID registrieren.

Verwenden des Azure-Portals

1. Wechseln Sie zum portal Azure und navigieren Sie zu Microsoft Entra ID>App-Registrierungen.
2. Wählen Sie Ihre Anwendung aus.
3. Wählen Sie Zertifikate und Geheimnisse>Zertifikate>Zertifikat hochladen aus.
4. Laden Sie die .cer oder .pem Datei hoch, die nur den öffentlichen Schlüssel enthält. Laden Sie die .pfx Datei nicht hoch, die den privaten Schlüssel enthält.
5. Notieren Sie sich den Fingerabdruckwert , der nach dem Upload angezeigt wird . Möglicherweise benötigen Sie ihn für die Konfiguration.

Verwenden von Azure CLI

az ad app credential reset \
  --id <application-client-id> \
  --cert @/path/to/certificate.pem \
  --append

Das --append Flag fügt das Zertifikat hinzu, ohne vorhandene Anmeldeinformationen zu entfernen.

Verwenden von Microsoft Graph PowerShell

$certData = [System.IO.File]::ReadAllBytes(".\MyDevCertificate.cer")
$base64Cert = [System.Convert]::ToBase64String($certData)

$keyCredential = @{
    type = "AsymmetricX509Cert"
    usage = "Verify"
    key = [System.Convert]::FromBase64String($base64Cert)
    displayName = "MyAppCertificate"
}

Update-MgApplication -ApplicationId <app-object-id> -KeyCredentials @($keyCredential)

Rotation für Zertifikate

Die Zertifikatrotation ersetzt ein ablaufendes Zertifikat durch ein neues Zertifikat, bevor es abläuft, und stellt einen unterbrechungsfreien Dienst sicher.

Strategie: Überlappende Zertifikate

Der empfohlene Ansatz verwendet überlappende Gültigkeitszeiträume:

1. Generieren Sie ein neues Zertifikat , bevor das aktuelle Zertifikat abläuft (z. B. 30 bis 60 Tage im Voraus).
2. Registern Sie das neue Zertifikat in Ihrer Microsoft Entra App-Registrierung zusammen mit dem vorhandenen. Microsoft Entra ID akzeptiert Token, die von einem registrierten Zertifikat signiert sind.
3. Stellen Sie das neue Zertifikat bereit in der Zertifikatsquelle Ihrer Anwendung (Key Vault, Zertifikatspeicher usw.).
4. Aktualisieren Sie die Konfiguration (falls erforderlich), um auf das neue Zertifikat zu verweisen.
5. Entfernen Sie das alte Zertifikat aus der App-Registrierung, nachdem Sie bestätigt haben, dass alle Instanzen das neue Zertifikat verwenden.

Mehrere Zertifikate in der Konfiguration

Microsoft. Identity.Web unterstützt das Angeben mehrerer Zertifikate. Die Bibliothek probiert sie der Reihe nach aus und verwendet das erste gültige Zertifikat.

{
  "AzureAd": {
    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "new-cert-2026"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "current-cert-2025"
      }
    ]
  }
}

Automatische Rotation mit Azure Key Vault

Azure Key Vault unterstützt die automatische Zertifikatverlängerung. Wenn Sie die automatische Drehung aktivieren:

1. Key Vault generiert vor Ablauf eine neue Zertifikatversion.
2. Microsoft. Identity.Web nimmt die neueste Version automatisch auf (beim nächsten Zertifikatabruf).
3. Die alte Zertifikatversion bleibt gültig, bis sie abläuft.

So konfigurieren Sie die automatische Drehung in Key Vault:

az keyvault certificate set-attributes \
  --vault-name your-keyvault-name \
  --name your-certificate-name \
  --policy @rotation-policy.json

Beheben von Zertifikatfehlern

In diesem Abschnitt werden allgemeine Fehlermeldungen und deren Lösungen aufgeführt.

Häufige Fehler

Das Zertifikat wurde nicht gefunden

Fehlermeldung:

System.Security.Cryptography.CryptographicException: The certificate cannot be found.

Mögliche Ursachen und Lösungen:

Zugriff verweigert auf Key Vault

Fehlermeldung:

Azure.RequestFailedException: The user, group or application '...' does not have certificates get permission on key vault '...'

Lösungen :

• Überprüfen Sie, ob Zugriffsrichtlinien Berechtigungen für get und geheime Schlüssel erteilen.
• Stellen Sie bei Verwendung Azure RBAC sicher, dass die Identität über die Rolle Key Vault Certificate User verfügt.
• Bestätigen Sie bei verwalteter Identität, dass die Identität aktiviert ist und die richtige Objekt-ID in der Richtlinie verwendet wird.

Auf den privaten Zertifikatschlüssel kann nicht zugegriffen werden

Fehlermeldung:

System.Security.Cryptography.CryptographicException: Keyset does not exist.

Lösungen :

• Stellen Sie bei Windows/IIS sicher, dass die Anwendungspoolidentität über read Zugriff auf den privaten Schlüssel verfügt. Verwenden Sie das MMC-Snap-In "Zertifikate", um zugriff über "Private Schlüssel verwalten" zu gewähren.
• Überprüfen Sie unter Linux, ob die .pfx Datei über entsprechende Dateiberechtigungen verfügt (chmod 600).
• Stellen Sie sicher, dass das Zertifikat mit dem privaten Schlüssel (Export-PfxCertificate oder openssl pkcs12 -export) exportiert wurde.

Das Zertifikat ist abgelaufen.

Fehlermeldung:

AADSTS700027: Client assertion contains an invalid signature. The key was expired.

Lösungen :

• Überprüfen Sie den Gültigkeitszeitraum des Zertifikats: openssl x509 -in cert.pem -noout -dates.
• Generieren Sie ein neues Zertifikat, und aktualisieren Sie sowohl die App-Registrierung als auch die Konfiguration Ihrer Anwendung.
• Implementieren Sie die Zertifikatrotation, um zukünftige Ablaufprobleme zu verhindern. Siehe Zertifikatswechsel.

Falsches Zertifikatkennwort

Fehlermeldung:

System.Security.Cryptography.CryptographicException: The specified network password is not correct.

Lösungen :

• Überprüfen Sie, ob CertificatePassword mit dem Kennwort übereinstimmt, das beim Exportieren der .pfx Datei verwendet wurde.
• Wenn Sie Umgebungsvariablen verwenden, überprüfen Sie auf Codierungsprobleme (nachfolgende Zeilenumbrüche, Sonderzeichen).
• Exportieren Sie das Zertifikat mit einem bekannten Kennwort erneut.

Diagnoseprüfliste

Verwenden Sie diese Checkliste, wenn die Zertifikatauthentifizierung nicht funktioniert:

• [ ] Gültigkeit des Zertifikats — Ist das Zertifikat innerhalb seiner Gültigkeitsdauer? Überprüfen Sie die Datumsangaben von NotBefore und NotAfter.
• [ ] App-Registrierung – Wird der öffentliche Schlüssel des Zertifikats in die richtige App-Registrierung hochgeladen?
• [ ] Fingerabdruck-Übereinstimmung – Stimmt der Fingerabdruck in Ihrer Konfiguration mit dem Zertifikat in der App-Registrierung überein?
• [ ] Zugriff auf private Schlüssel – Kann der Anwendungsprozess den privaten Schlüssel des Zertifikats lesen?
• [ ] Key Vault Berechtigungen — Für Key Vault Quellen verfügt die Identität über berechtigungen certificates/get und secrets/get?
• [ ] Konfigurationsabschnitt – Befindet sich die Zertifikatkonfiguration im richtigen Abschnitt (AzureAd oder AzureAdB2C)?
• [ ] NuGet-Pakete — Ist Microsoft.Identity.Web auf dem neuesten Stand? Ältere Versionen unterstützen möglicherweise bestimmte Zertifikatquellentypen nicht.

Aktivieren der Protokollierung

Um detaillierte Diagnoseinformationen zu erhalten, aktivieren Sie die MSAL-Protokollierung:

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

builder.Logging.AddFilter("Microsoft.Identity", LogLevel.Debug);

Überprüfen Sie die Protokolle auf Nachrichten zum Laden von Zertifikaten, zur Erstellung von Client assertionen und zum Tokenerwerb.

Verwandte Inhalte

• Übersicht über Anmeldeinformationen
• Zertifikatlose Authentifizierung – Verwaltung von Identitäten und Arbeitsbelastungs-Identitätsverbund
• Geheime Clientschlüssel – alternativer Anmeldeinformationstyp für vertrauliche Apps
• Tokenentschlüsselung – Verwenden von Zertifikaten für die Tokenentschlüsselung
• Protokollierung und Diagnose