Använd certifikat med Microsoft. Identity.Web

Microsoft. Identity.Web stöder certifikatbaserad autentisering som ett säkert alternativ till klienthemligheter för konfidentiella klientprogram. Certifikat använder asymmetrisk kryptografi, så endast den privata nyckelhållaren kan autentisera.

I den här artikeln konfigurerar du certifikatautentiseringsuppgifter från olika källor, registrerar dem med din app och hanterar dem i produktion.

Varför ska jag använda certifikat?

Så här fungerar det

1. Du genererar eller hämtar ett X.509-certifikat med en privat nyckel.
2. Du registrerar certifikatets public nyckel (eller tumavtryck) med din Microsoft Entra appregistrering.
3. Vid körning Microsoft. Identity.Web läser in certifikatet (inklusive den privata nyckeln) från din konfigurerade källa.
4. Biblioteket använder den privata nyckeln för att signera ett klientintyg som den skickar till Microsoft Entra ID för att erhålla token.

Certifikatkällor

Microsoft. Identity.Web stöder inläsning av certifikat från flera källor:

Du konfigurerar certifikatautentiseringsuppgifter i matrisen ClientCertificates i konfigurationsavsnittet AzureAd (eller AzureAdB2C). Du kan ange flera certifikat för rotationsscenarier – Microsoft. Identity.Web använder det första giltiga certifikatet som hittas.

Från Azure Key Vault (rekommenderas)

Azure Key Vault är den rekommenderade källan för certifikat i produktion. Det ger centraliserad hantering, åtkomstkontroll, granskning och automatiska rotationsfunktioner.

Konfiguration

Lägg till certifikatkonfigurationen i :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"
      }
    ]
  }
}

Konfigurera Key Vault åtkomstprinciper

Applikationens identitet måste ha behörighet för att läsa certifikat från Key Vault. Hur du beviljar detta beror på om du använder principmodellen för valvåtkomst eller Azure rollbaserad åtkomstkontroll (RBAC).

Alternativ 1: Åtkomstpolicy för valv

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

Alternativ 2: Azure RBAC

Tilldela rollen Key Vault certifikatanvändare till programmets identitet:

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>

Använda hanterad identitet för att få åtkomst till Key Vault

När din app körs i Azure (App Service, Azure Functions, Azure Kubernetes Service, virtuella datorer) använder du Azure Managed Identity för att autentisera mot Key Vault. Detta eliminerar behovet av autentiseringsuppgifter för att komma åt själva valvet.

Systemtilldelad hanterad identitet

Om din app har en systemtilldelad hanterad identitet aktiverad Microsoft. Identity.Web använder automatiskt DefaultAzureCredential för att autentisera till Key Vault. Ingen extra konfiguration krävs utöver posten ClientCertificates :

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

Användartilldelad hanterad identitet

För en användartilldelad hanterad identitet anger du ManagedIdentityClientId på Key Vault-certifikatbeskrivningen:

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

Från certifikatarkivet (endast Windows)

På Windows kan du läsa in certifikat från Windows Certificate Store. Detta är vanligt för lokala distributioner eller IIS-värdbaserade distributioner.

Genom tumavtryck

Använd StoreWithThumbprint för att identifiera certifikatet med dess SHA-1 tumavtryck:

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

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

Efter unikt namn

Använd StoreWithDistinguishedName för att identifiera certifikatet med dess ämnesnamn:

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

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

Platser för certifikatslagring

I följande tabell visas vanliga sökvägar för certifikatarkiv och de behörigheter som krävs för att få åtkomst till dem:

Från filsökväg

Du kan läsa in ett certifikat direkt från en .pfx (PKCS#12)-fil på disken.

Konfiguration

Lägg till certifikatfilens sökväg och lösenord i 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"

Från Base64-kodat värde

Du kan ange certifikatet som en Base64-kodad sträng. Den här metoden är användbar när du matar in certifikat via miljövariabler, Kubernetes-hemligheter eller CI/CD-pipelinevariabler.

Konfiguration

Lägg till det Base64-kodade certifikatvärdet till din appsettings.json:

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

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

Generera Base64-värdet

Konvertera en .pfx fil till en Base64-sträng:

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

Använd med Kubernetes secrets

Lagra det Base64-kodade certifikatet i en Kubernetes-hemlighet och mappa det till en miljövariabel:

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

Referera till hemligheten i distributionen:

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

Användning i CI/CD-pipelinesystemen

Lagra det Base64-kodade certifikatet som en hemlig variabel i Azure DevOps eller GitHub Actions och ange det sedan som en miljövariabel vid körning.

GitHub Actions exempel:

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

Azure DevOps exempel:

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

Konfigurera certifikat i C#-kod

Förutom JSON-konfiguration kan du konfigurera certifikatautentiseringsuppgifter programmatiskt med hjälp av klassen CredentialDescription från Microsoft.Identity.Abstractions.

Hjälpmetoder

Klassen CredentialDescription innehåller statiska hjälpmetoder för varje certifikatkällatyp:

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

Använd i ASP.NET Core

Skicka beskrivningarna av autentiseringsuppgifterna direkt när du konfigurerar autentisering:

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

Skapa ett självsignerat certifikat för utveckling

För lokal utveckling och testning kan du skapa ett självsignerat certifikat. Använd inte självsignerade certifikat i produktion.

Använda PowerShell (Windows)

Kör följande kommandon för att skapa ett självsignerat certifikat, exportera det och visa tumavtrycket:

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

Använda OpenSSL (plattformsoberoende)

Kör följande kommandon för att generera ett certifikat, paketera det som en .pfx fil och visa tumavtrycket:

# 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

Använda .NET CLI

Exportera ett HTTPS-certifikat för utveckling som en .pfx fil:

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

Registrera certifikatet i Microsoft Entra ID

När du har skapat eller skaffat ett certifikat måste du registrera dess offentliga nyckel med din appregistrering i Microsoft Entra ID.

Använda Azure-portalen

1. Gå till portalen Azure och gå till Microsoft Entra ID>App registrations.
2. Välj ditt program.
3. Välj Certifikat och hemligheter>Certifikat>Ladda upp certifikat.
4. Ladda upp .cer- eller .pem-filen som endast innehåller den offentliga nyckeln. Ladda inte upp .pfx filen som innehåller den privata nyckeln.
5. Observera tumavtrycksvärdet som visas efter uppladdningen – du kan behöva det för konfigurationen.

Använda Azure CLI

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

Flaggan --append lägger till certifikatet utan att ta bort befintliga autentiseringsuppgifter.

Använda 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)

Certifikatrotation

Certifikatrotation ersätter ett utgående certifikat med ett nytt innan det upphör att gälla, vilket säkerställer kontinuerlig drift av tjänsten.

Strategi: Överlappande certifikat

Den rekommenderade metoden använder överlappande giltighetsperioder:

1. Generera ett nytt certifikat innan det aktuella upphör att gälla (till exempel 30–60 dagar i förväg).
2. Registrera det nya certifikatet i din Microsoft Entra appregistrering tillsammans med det befintliga. Microsoft Entra ID accepterar token som signerats av ett registrerat certifikat.
3. Distribuera det nya certifikatet till programmets certifikatkälla (Key Vault, certifikatarkiv och så vidare).
4. Uppdatera konfigurationen (om det behövs) för att peka på det nya certifikatet.
5. Ta bort det gamla certifikatet från appregistreringen när du har bekräftat att alla instanser använder det nya.

Flera certifikat i konfigurationen

Microsoft. Identity.Web har stöd för att ange flera certifikat. Biblioteket testar dem i tur och ordning och använder det första giltiga certifikatet.

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

Automatisk rotation med Azure Key Vault

Azure Key Vault stöder automatisk certifikatförnyelse. När du aktiverar automatisk rotation:

1. Key Vault genererar en ny certifikatversion innan den upphör att gälla.
2. Microsoft. Identity.Web hämtar den senaste versionen automatiskt (vid nästa certifikathämtning).
3. Den gamla certifikatversionen är giltig tills den upphör att gälla.

Så här konfigurerar du automatisk rotation i Key Vault:

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

Felsöka certifikatfel

I det här avsnittet visas vanliga felmeddelanden och deras lösningar.

Vanliga fel

Certifikatet hittades inte

Felmeddelande:

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

Möjliga orsaker och lösningar:

Åtkomst nekad till Key Vault

Felmeddelande:

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

Lösningar:

• Kontrollera att åtkomstprinciper get behörighet för både certifikat och hemligheter.
• Om du använder Azure RBAC kontrollerar du att identiteten har rollen Key Vault certifikatanvändare.
• För Managed Identity bekräftar du att identiteten är aktiverad och att rätt objekt-ID används i policyn.

Certifikatets privata nyckel är inte tillgänglig

Felmeddelande:

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

Lösningar:

• På Windows/IIS kontrollerar du att programpoolens identitet har read åtkomst till den privata nyckeln. Använd MMC-snapin-modulen Certifikat för att bevilja åtkomst via Hantera privata nycklar.
• I Linux kontrollerar du att .pfx filen har rätt filbehörigheter (chmod 600).
• Kontrollera att certifikatet exporterades med den privata nyckeln (Export-PfxCertificate eller openssl pkcs12 -export).

Certifikatet har upphört att gälla

Felmeddelande:

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

Lösningar:

• Kontrollera certifikatets giltighetsperiod: openssl x509 -in cert.pem -noout -dates.
• Generera ett nytt certifikat och uppdatera både appregistreringen och programmets konfiguration.
• Implementera certifikatrotation för att förhindra framtida förfalloproblem. Se Certifikatrotation.

Fel certifikatlösenord

Felmeddelande:

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

Lösningar:

• Kontrollera CertificatePassword att det lösenord som används vid export av .pfx filen matchar.
• Om du använder miljövariabler ska du kontrollera efter kodningsproblem (efterföljande radbrytningar, specialtecken).
• Exportera certifikatet igen med ett känt lösenord.

Checklista för diagnostik

Använd den här checklistan när certifikatautentisering inte fungerar:

• [ ] Certifikatets giltighet – ligger certifikatet inom dess giltighetsperiod? Kontrollera NotBefore och NotAfter datum.
• [ ] Appregistrering – laddas certifikatets offentliga nyckel upp till rätt appregistrering?
• [ ] Matchning av tumavtryck – Matchar tumavtrycket i din konfiguration certifikatet i appregistreringen?
• [ ] Åtkomst till privat nyckel – Kan programprocessen läsa certifikatets privata nyckel?
• [ ] Key Vault behörigheter – För Key Vault källor har identiteten både certificates/get och secrets/get behörigheter?
• [ ] Konfigurationsavsnitt – Är certifikatkonfigurationen under rätt avsnitt (AzureAd eller AzureAdB2C)?
• [ ] NuGet-paket – Är Microsoft.Identity.Web uppdaterat? Äldre versioner kan sakna stöd för vissa typer av certifikatkällor.

Aktivera loggning

Aktivera MSAL-loggning för att få detaljerad diagnostikinformation:

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

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

Granska loggarna för meddelanden om certifikatinläsning, skapande av klientkontroll och tokenförvärv.

Relaterat innehåll

• Översikt över autentiseringsuppgifter
• Certifikatlös autentisering – Hanterad identitets- och arbetsbelastningsidentitetsfederation
• Klienthemligheter – alternativ typ av autentiseringsuppgifter för konfidentiella appar
• Tokendekryptering – använda certifikat för tokendekryptering
• Loggning och diagnostik