Gebruik certificaten met Microsoft. Identity.Web

Microsoft. Identity.Web ondersteunt verificatie op basis van certificaten als een veilig alternatief voor clientgeheimen voor vertrouwelijke clienttoepassingen. Certificaten gebruiken asymmetrische cryptografie, zodat alleen de houder van de persoonlijke sleutel kan verifiëren.

In dit artikel configureert u certificaatreferenties uit verschillende bronnen, registreert u deze bij uw app en beheert u deze in productie.

Waarom certificaten gebruiken?

Hoe werkt het?

1. U genereert of verkrijgt een X.509-certificaat met een persoonlijke sleutel.
2. U registreert de public key (of vingerafdruk) van het certificaat bij de registratie van uw Microsoft Entra-app.
3. Tijdens runtime Microsoft. Identity.Web laadt het certificaat (inclusief de persoonlijke sleutel) van uw geconfigureerde bron.
4. De bibliotheek gebruikt de persoonlijke sleutel om een clientbevestiging te ondertekenen, die wordt verzonden naar Microsoft Entra ID om tokens te verkrijgen.

Certificaatbronnen

Microsoft. Identity.Web ondersteunt het laden van certificaten uit meerdere bronnen:

U configureert certificaatreferenties in de array binnen uw ClientCertificatesAzureAd (of AzureAdB2C) configuratiesectie. U kunt meerdere certificaten opgeven voor rotatiescenario's, Microsoft. Identity.Web gebruikt het eerste geldige certificaat dat wordt gevonden.

Van Azure Key Vault (aanbevolen)

Azure Key Vault is de aanbevolen bron voor certificaten in productie. Het biedt gecentraliseerd beheer, toegangsbeheer, controle en mogelijkheden voor automatische rotatie.

Configuratie

Voeg de certificaatconfiguratie toe aan uw appsettings.json:

{
  "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"
      }
    ]
  }
}

Toegangsbeleid voor Key Vault instellen

De identiteit van uw toepassing moet gemachtigd zijn om certificaten uit de Key Vault te lezen. Hoe u dit toekent, is afhankelijk van of u het toegangsbeleidsmodel voor de kluis of Azure Role-Based Access Control (RBAC) gebruikt.

Optie 1: Toegangsbeleid voor kluis

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

Optie 2: Azure RBAC

Wijs de rol Key Vault Certificate User toe aan de identiteit van uw toepassing:

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>

Beheerde identiteit gebruiken voor toegang tot Key Vault

Wanneer uw app wordt uitgevoerd in Azure (App Service, Azure Functions, Azure Kubernetes Service, VM's), gebruikt u Beheerde identiteit om te verifiëren bij Key Vault. Hierdoor hoeven er geen inloggegevens meer te worden gebruikt om toegang te krijgen tot de kluis zelf.

Door het systeem toegewezen beheerde identiteit

Als voor uw app een door het systeem toegewezen beheerde identiteit is ingeschakeld, Microsoft. Identity.Web gebruikt automatisch DefaultAzureCredential om te verifiëren bij Key Vault. Er is geen extra configuratie nodig buiten de ClientCertificates vermelding:

{
  "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"
      }
    ]
  }
}

Door de gebruiker toegewezen beheerde identiteit

Geef voor een door de gebruiker toegewezen beheerde identiteit de ManagedIdentityClientId op de Key Vault certificaatdescriptor op:

{
  "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"
      }
    ]
  }
}

Uit het certificaatarchief (alleen Windows)

Op Windows kunt u certificaten uit het Windows certificaatarchief laden. Dit is gebruikelijk voor on-premises of door IIS gehoste implementaties.

Op vingerafdruk

Gebruik StoreWithThumbprint dit om het certificaat te identificeren met behulp van de SHA-1-vingerafdruk:

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

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

Door belangrijke naam

Gebruik StoreWithDistinguishedName dit om het certificaat te identificeren op basis van de onderwerpnaam:

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

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

Locaties van certificaatopslag

De volgende tabel bevat veelgebruikte certificaatarchiefpaden en de machtigingen die nodig zijn om ze te openen:

Van bestandspad

U kunt een certificaat rechtstreeks vanuit een .pfx (PKCS#12)-bestand op schijf laden.

Configuratie

Voeg het pad en het wachtwoord van het certificaatbestand toe aan uw 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"

Van base64-gecodeerde waarde

U kunt het certificaat opgeven als een met Base64 gecodeerde tekenreeks. Deze methode is handig wanneer u certificaten injecteert via omgevingsvariabelen, Kubernetes-geheimen of CI/CD-pijplijnvariabelen.

Configuratie

Voeg de met Base64 gecodeerde certificaatwaarde toe aan uw appsettings.json:

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

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

De Base64-waarde genereren

.pfx Een bestand converteren naar een Base64-tekenreeks:

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

Gebruiken met Kubernetes-geheimen

Sla het met Base64 gecodeerde certificaat op in een Kubernetes-geheim en wijs het toe aan een omgevingsvariabele:

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

Verwijs naar het geheim in uw implementatie:

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

Gebruiken in CI/CD-pijplijnen

Sla in Azure DevOps of GitHub Actions het met Base64 gecodeerde certificaat op als een geheime variabele en stel het vervolgens in als een omgevingsvariabele tijdens runtime.

GitHub Actions voorbeeld:

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

Azure DevOps voorbeeld:

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

Certificaten configureren in C#-code

Naast de JSON-configuratie kunt u certificaatreferenties programmatisch configureren met behulp van de klasse CredentialDescription van Microsoft.Identity.Abstractions.

Helpermethoden

De CredentialDescription klasse biedt statische helpermethoden voor elk certificaatbrontype:

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...");

Gebruiken in ASP.NET Core

Geef de referentiebeschrijvingen rechtstreeks door bij het configureren van verificatie:

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")
        };
    });

Een zelfondertekend certificaat maken voor ontwikkeling

Voor lokale ontwikkeling en testen kunt u een zelfondertekend certificaat maken. Gebruik geen zelfondertekende certificaten in productie.

PowerShell (Windows) gebruiken

Voer de volgende opdrachten uit om een zelfondertekend certificaat te maken, te exporteren en de vingerafdruk weer te geven:

$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)"

OpenSSL gebruiken (platformoverschrijdend)

Voer de volgende opdrachten uit om een certificaat te genereren, in te pakken als een .pfx bestand en de vingerafdruk weer te geven:

# 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

.NET CLI gebruiken

Een HTTPS-ontwikkelingscertificaat exporteren als een .pfx bestand:

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

Het certificaat registreren in Microsoft Entra ID

Nadat u een certificaat hebt gemaakt of verkregen, moet u de openbare sleutel registreren bij uw app-registratie in Microsoft Entra ID.

De Azure-portal gebruiken

1. Ga naar de Azure portal en navigeer naar Microsoft Entra ID>App-registraties.
2. Selecteer uw toepassing.
3. Selecteer Certificaten en geheimen>Certificaten>Certificaat uploaden.
4. Upload het .cer of .pem bestand dat alleen de openbare sleutel bevat. Upload het .pfx bestand niet, dat de persoonlijke sleutel bevat.
5. Noteer de vingerafdrukwaarde die wordt weergegeven na het uploaden. Mogelijk hebt u deze nodig voor configuratie.

Azure CLI gebruiken

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

Met de --append vlag wordt het certificaat toegevoegd zonder bestaande referenties te verwijderen.

Microsoft Graph PowerShell gebruiken

$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)

Certificaatrotatie

Certificaatrotatie vervangt een verlopend certificaat door een nieuw certificaat voordat het verloopt, waardoor een ononderbroken service wordt gegarandeerd.

Strategie: Overlappende certificaten

De aanbevolen benadering maakt gebruik van overlappende geldigheidsperioden:

1. Genereer een nieuw certificaat voordat het huidige certificaat verloopt (bijvoorbeeld 30-60 dagen van tevoren).
2. Registreer het nieuwe certificaat in de registratie van uw Microsoft Entra-app naast het bestaande. Microsoft Entra ID accepteert tokens die zijn ondertekend door een geregistreerd certificaat.
3. Implementeer het nieuwe certificaat naar de certificaatbron van uw toepassing (Key Vault, certificaatarchief enzovoort).
4. Werk de configuratie bij (indien nodig) om naar het nieuwe certificaat te verwijzen.
5. Verwijder het oude certificaat uit de app-registratie nadat u hebt bevestigd dat alle exemplaren het nieuwe gebruiken.

Meerdere certificaten in configuratie

Microsoft. Identity.Web ondersteunt het opgeven van meerdere certificaten. De bibliotheek probeert ze in volgorde en gebruikt het eerste geldige certificaat.

{
  "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 rotatie met Azure Key Vault

Azure Key Vault ondersteunt automatische verlenging van certificaten. Wanneer u automatische rotatie inschakelt:

1. Key Vault genereert een nieuwe certificaatversie voordat deze verloopt.
2. Microsoft. Identity.Web haalt automatisch de nieuwste versie op (bij het ophalen van het volgende certificaat).
3. De oude certificaatversie blijft geldig totdat deze verloopt.

Automatische rotatie configureren in Key Vault:

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

Certificaatfouten oplossen

In deze sectie vindt u veelvoorkomende foutberichten en de bijbehorende oplossingen.

Veelvoorkomende fouten

Certificaat niet gevonden

Foutbericht:

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

Mogelijke oorzaken en oplossingen:

Toegang geweigerd tot Key Vault

Foutbericht:

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

Oplossingen:

• Controleer of toegangsbeleid machtigingen verleent get voor zowel certificaten als geheimen.
• Als u Azure RBAC gebruikt, moet u ervoor zorgen dat de identiteit de rol Key Vault Certificate User heeft.
• Controleer voor Beheerde Identiteit of de identiteit ingeschakeld is en de juiste object-ID in het beleid wordt gebruikt.

Persoonlijke sleutel van certificaat is niet toegankelijk

Foutbericht:

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

Oplossingen:

• Controleer of de identiteit van de applicatiepool in Windows/IIS lees toegang heeft tot de persoonlijke sleutel. Gebruik de MMC-module Certificaten om toegang te verlenen via Persoonlijke sleutels beheren.
• Controleer in Linux of het .pfx bestand de juiste bestandsmachtigingenchmod 600 () heeft.
• Zorg ervoor dat het certificaat is geëxporteerd met de persoonlijke sleutel (Export-PfxCertificate of openssl pkcs12 -export).

Certificaat is verlopen

Foutbericht:

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

Oplossingen:

• Controleer de geldigheidsperiode van het certificaat: openssl x509 -in cert.pem -noout -dates.
• Genereer een nieuw certificaat en werk zowel de app-registratie als de configuratie van uw toepassing bij.
• Implementeer certificaatrotatie om toekomstige verloopproblemen te voorkomen. Zie certificaatrotatie.

Onjuist certificaatwachtwoord

Foutbericht:

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

Oplossingen:

• Controleer of CertificatePassword het wachtwoord overeenkomt met het wachtwoord dat wordt gebruikt bij het exporteren van het .pfx bestand.
• Als u omgevingsvariabelen gebruikt, controleert u op coderingsproblemen (afsluitende regeleinden, speciale tekens).
• Exporteer het certificaat opnieuw met een bekend wachtwoord.

Controlelijst voor diagnostische gegevens

Gebruik deze controlelijst wanneer certificaatverificatie niet werkt:

• [ ] Geldigheid van certificaat — Is het certificaat binnen de geldigheidsperiode? Controleren NotBefore en NotAfter datums.
• [ ] App-registratie — Wordt de openbare sleutel van het certificaat geüpload naar de juiste app-registratie?
• [ ] Vingerafdruk komt overeen - Komt de vingerafdruk in uw configuratie overeen met het certificaat in de app-registratie?
• [ ] Toegang tot persoonlijke sleutel — Kan het toepassingsproces de persoonlijke sleutel van het certificaat lezen?
• [ ] Key Vault machtigingen — Heeft de identiteit voor Key Vault bronnen zowel certificates/get als secrets/get machtigingen?
• [] Configuratiesectie — Bevindt de certificaatconfiguratie zich onder de juiste sectie (AzureAd of AzureAdB2C)?
• [ ] NuGet-pakketten — Is Microsoft.Identity.Web bijgewerkt? Oudere versies hebben mogelijk geen ondersteuning voor bepaalde certificaatbrontypen.

Logboekregistratie inschakelen

Als u gedetailleerde diagnostische gegevens wilt ophalen, schakelt u MSAL-logboekregistratie in:

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

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

Bekijk de logboeken voor berichten over het laden van certificaten, het maken van clientverklaringen en het verkrijgen van tokens.

Verwante inhoud

• Overzicht van referenties
• Verificatie zonder certificaat - Federatie van beheerde identiteit en workloadidentiteit
• Clientgeheimen : alternatief referentietype voor vertrouwelijke apps
• Tokenontsleuteling : certificaten gebruiken voor tokenontsleuteling
• Logboekregistratie en diagnostische gegevens