Utilisez des certificats avec Microsoft. Identity.Web

Microsoft. Identity.Web prend en charge l’authentification basée sur des certificats comme alternative sécurisée aux secrets clients pour les applications clientes confidentielles. Les certificats utilisent le chiffrement asymétrique, de sorte que seul le titulaire de clé privée peut s’authentifier.

Dans cet article, vous allez configurer des informations d’identification de certificat à partir de différentes sources, les inscrire auprès de votre application et les gérer en production.

Pourquoi utiliser des certificats ?

Fonctionnement

1. Vous générez ou obtenez un certificat X.509 avec une clé privée.
2. Vous inscrivez la clé publique du certificat (ou empreinte numérique) auprès de votre inscription d'application Microsoft Entra.
3. Au moment de l’exécution, Microsoft. Identity.Web charge le certificat (y compris la clé privée) à partir de votre source configurée.
4. La bibliothèque utilise la clé privée pour signer une assertion cliente, qu’elle envoie à Microsoft Entra ID pour obtenir des jetons.

Sources de certificat

Microsoft. Identity.Web prend en charge le chargement de certificats à partir de plusieurs sources :

Vous configurez les informations d’identification du certificat dans le ClientCertificates tableau dans votre AzureAd section de configuration (ou AzureAdB2C). Vous pouvez spécifier plusieurs certificats pour les scénarios de rotation : Microsoft. Identity.Web utilise le premier certificat valide qu’il trouve.

À partir de Azure Key Vault (recommandé)

Azure Key Vault est la source recommandée pour les certificats en production. Il fournit des fonctionnalités de gestion centralisée, de contrôle d’accès, d’audit et de rotation automatique.

Paramétrage

Ajoutez la configuration du certificat à votre 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"
      }
    ]
  }
}

Configurer des stratégies d’accès Key Vault

L'identité de votre application doit avoir l'autorisation de lire des certificats à partir du Key Vault. La manière dont vous accordez cela dépend si vous utilisez le modèle de stratégie d’accès au coffre ou le contrôle d'accès basé sur les rôles d’Azure (RBAC).

Option 1 : Stratégie d’accès au coffre

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

Affectez le rôle Key Vault Utilisateur de certificat à l'identité de votre application :

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>

Utiliser l’identité managée pour accéder à Key Vault

Lorsque votre application s’exécute dans Azure (App Service, Azure Functions, Azure Kubernetes Service, machines virtuelles), utilisez l’identité managée pour s’authentifier auprès de Key Vault. Cela évite d’avoir besoin d’informations d’identification pour accéder au coffre lui-même.

Identité gérée par le système

Si votre application dispose d’une identité managée affectée par le système activée, Microsoft. Identity.Web utilise automatiquement DefaultAzureCredential pour s’authentifier auprès de Key Vault. Aucune configuration supplémentaire n’est nécessaire au-delà de l’entrée 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"
      }
    ]
  }
}

Identité gérée attribuée par l'utilisateur

Pour une identité managée affectée par l’utilisateur, spécifiez la ManagedIdentityClientId sur le descripteur de certificat Key Vault :

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

À partir du magasin de certificats (Windows uniquement)

Sur Windows, vous pouvez charger des certificats à partir du magasin de certificats Windows. Cela est courant pour les déploiements locaux ou hébergés par IIS.

Par empreinte numérique

Permet StoreWithThumbprint d’identifier le certificat par son empreinte SHA-1 :

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

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

Par nom distingué

Permet StoreWithDistinguishedName d’identifier le certificat par son nom d’objet :

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

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

Emplacements du magasin de certificats

Le tableau suivant répertorie les chemins d’accès courants du magasin de certificats et les autorisations requises pour y accéder :

À partir du chemin d’accès au fichier

Vous pouvez charger un certificat directement à partir d’un .pfx fichier (PKCS#12) sur le disque.

Paramétrage

Ajoutez le chemin d’accès et le mot de passe du fichier de certificat à votre 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"

À partir de la valeur encodée en Base64

Vous pouvez fournir le certificat en tant que chaîne encodée en Base64. Cette approche est utile lorsque vous injectez des certificats via des variables d’environnement, des secrets Kubernetes ou des variables de pipeline CI/CD.

Paramétrage

Ajoutez la valeur du certificat codé en Base64 à votre appsettings.json:

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

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

Générer la valeur Base64

Convertissez un .pfx fichier en chaîne Base64 :

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

Utilisation avec les secrets de Kubernetes

Stockez le certificat encodé en Base64 dans un secret Kubernetes et mappez-le à une variable d’environnement :

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

Référencez le secret dans votre déploiement :

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

Utilisation dans les pipelines CI/CD

Dans Azure DevOps ou GitHub Actions, stockez le certificat encodé en Base64 en tant que variable secrète, puis définissez-le comme variable d’environnement au moment de l’exécution.

GitHub Actions example :

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

Azure DevOps example :

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

Configurer des certificats dans le code C#

Outre la configuration JSON, vous pouvez configurer des informations d’identification de certificat par programmation à l’aide de la classe CredentialDescription à partir de Microsoft.Identity.Abstractions.

Méthodes d’assistance

La CredentialDescription classe fournit des méthodes d’assistance statiques pour chaque type de source de certificat :

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

Utiliser dans ASP.NET Core

Transmettez les descriptions des informations d’identification directement lors de la configuration de l’authentification :

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

Créer un certificat auto-signé pour le développement

Pour le développement et les tests locaux, vous pouvez créer un certificat auto-signé. N’utilisez pas de certificats auto-signés en production.

Utilisation de PowerShell (Windows)

Exécutez les commandes suivantes pour créer un certificat auto-signé, l’exporter et afficher l’empreinte numérique :

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

Utilisation d’OpenSSL (multiplateforme)

Exécutez les commandes suivantes pour générer un certificat, le empaqueter en tant que .pfx fichier et afficher l’empreinte numérique :

# 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

Utilisation de l’interface CLI .NET

Exportez un certificat HTTPS de développement en tant que .pfx fichier :

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

Inscrire le certificat dans Microsoft Entra ID

Après avoir créé ou obtenu un certificat, vous devez inscrire sa clé publique auprès de votre inscription d’application dans Microsoft Entra ID.

Utilisation du portail Azure

1. Accédez au portail Azure et accédez à Microsoft Entra ID>inscriptions d'applications.
2. Sélectionnez votre application.
3. Sélectionnez Certificats et secrets>Certificats>Charger un certificat.
4. Téléchargez le fichier .cer ou .pem contenant uniquement la clé publique. Ne chargez pas le .pfx fichier, qui contient la clé privée.
5. Notez la valeur de l’empreinte numérique affichée après le chargement. Vous en aurez peut-être besoin pour la configuration.

Utilisation de Azure CLI

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

L’indicateur --append ajoute le certificat sans supprimer les informations d’identification existantes.

Utilisation de 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 des certificats

La rotation des certificats remplace un certificat arrivant à expiration par un nouveau certificat avant son expiration, ce qui garantit un service ininterrompu.

Stratégie : chevauchement des certificats

L’approche recommandée utilise des périodes de validité qui se chevauchent :

1. Générez un nouveau certificat avant l’expiration du certificat actuel (par exemple, 30 à 60 jours à l’avance).
2. Registrer le nouveau certificat dans votre inscription d’application Microsoft Entra en même temps que celle existante. Microsoft Entra ID accepte les jetons signés par n’importe quel certificat inscrit.
3. Déployez le nouveau certificat vers la source de certificats de votre application (Key Vault, magasin de certificats, etc.).
4. Mettez à jour la configuration (si nécessaire) pour pointer vers le nouveau certificat.
5. Supprimez l’ancien certificat de l’inscription de l’application après avoir confirmé que toutes les instances utilisent la nouvelle.

Plusieurs certificats dans la configuration

Microsoft. Identity.Web prend en charge la spécification de plusieurs certificats. La bibliothèque les essaye dans l’ordre et utilise le premier certificat valide :

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

Rotation automatique avec Azure Key Vault

Azure Key Vault prend en charge le renouvellement automatique des certificats. Lorsque vous activez la rotation automatique :

1. Key Vault génère une nouvelle version de certificat avant l’expiration.
2. Microsoft. Identity.Web récupère automatiquement la dernière version (lors de la récupération de certificat suivante).
3. L’ancienne version du certificat reste valide jusqu’à son expiration.

Pour configurer la rotation automatique dans Key Vault :

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

Résoudre les erreurs de certificat

Cette section répertorie les messages d’erreur courants et leurs solutions.

Erreurs courantes

Certificat introuvable

Message d’erreur :

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

Causes et solutions possibles :

Accès refusé à Key Vault

Message d’erreur :

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

Solutions :

• Vérifiez que les stratégies d’accès accordent get l’autorisation pour les certificats et les secrets.
• Si vous utilisez Azure RBAC, vérifiez que l’identité a le rôle Utilisateur de certificats Key Vault.
• Pour Managed Identity, vérifiez que l’identité est activée et que l’ID d’objet approprié est utilisé dans la stratégie.

Clé privée de certificat non accessible

Message d’erreur :

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

Solutions :

• Sur Windows/IIS, vérifiez que l’identité du pool d’applications dispose de l'accès en lecture à la clé privée. Utilisez l'outil snap-in MMC Certificat pour accorder l’accès via Gérer les clés privées.
• Sur Linux, vérifiez que le .pfx fichier dispose des autorisations de fichier appropriées (chmod 600).
• Vérifiez que le certificat a été exporté avec la clé privée (Export-PfxCertificate ou openssl pkcs12 -export).

Le certificat a expiré.

Message d’erreur :

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

Solutions :

• Vérifiez la période de validité du certificat : openssl x509 -in cert.pem -noout -dates.
• Générez un nouveau certificat et mettez à jour l’inscription de l’application et la configuration de votre application.
• Implémentez la rotation des certificats pour éviter les problèmes d’expiration futurs. Consultez la rotation des certificats.

Mot de passe de certificat incorrect

Message d’erreur :

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

Solutions :

• Vérifiez que CertificatePassword correspond au mot de passe utilisé lors de l’exportation du fichier .pfx.
• Si vous utilisez des variables d’environnement, recherchez les problèmes d’encodage (lignes de fin, caractères spéciaux).
• Réexportez le certificat avec un mot de passe connu.

Liste de contrôle de diagnostic

Utilisez cette liste de contrôle lorsque l’authentification par certificat ne fonctionne pas :

• [ ] Validité du certificat : le certificat est-il dans sa période de validité ? Vérifiez NotBefore et NotAfter dates.
• [ ] Enregistrement de l'application : la clé publique du certificat est-elle chargée dans l'enregistrement correct de l'application ?
• [ ] Correspondance de l’empreinte numérique — L’empreinte numérique de votre configuration correspond-elle au certificat dans l’enregistrement de l’application ?
• [ ] Accès à la clé privée : le processus d’application peut-il lire la clé privée du certificat ?
• [ ] autorisations Key Vault : pour les sources Key Vault, l’identité dispose-t-elle des autorisations certificates/get et secrets/get ?
• [ ] Section Configuration : la configuration du certificat est-elle sous la section correcte (AzureAd ou AzureAdB2C) ?
• [ ] paquets NuGet — Est-ce Microsoft.Identity.Web à jour ? Les versions antérieures peuvent ne pas prendre en charge certains types de sources de certificat.

Activation de la journalisation

Pour obtenir des informations de diagnostic détaillées, activez la journalisation MSAL :

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

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

Passez en revue les journaux pour les messages concernant le chargement de certificats, la création d’assertions clientes et l’acquisition de jetons.

Contenu connexe

• Vue d’ensemble des informations d’identification
• Authentification sans certificat : Fédération des identités managées et des identités de charge de travail
• Secrets client : autre type d’informations d’identification pour les applications confidentielles
• Déchiffrement de jeton : utilisation de certificats pour le déchiffrement de jeton
• Journalisation et diagnostics