Use certificados con Microsoft. Identity.Web

Microsoft. Identity.Web admite la autenticación basada en certificados como alternativa segura a los secretos de cliente para las aplicaciones cliente confidenciales. Los certificados usan criptografía asimétrica, por lo que solo el titular de la clave privada puede autenticarse.

En este artículo, configurará certificados de varios orígenes, los registrará en su aplicación y los gestionará en el entorno de producción.

¿Por qué usar certificados?

Cómo funciona

1. Genere o obtenga un certificado X.509 con una clave privada.
2. Registra la clave pública del certificado (o huella digital) con el registro de la aplicación de Microsoft Entra.
3. En tiempo de ejecución, Microsoft. Identity.Web carga el certificado (incluida la clave privada) desde el origen configurado.
4. La biblioteca usa la clave privada para firmar una aserción de cliente, que envía a Microsoft Entra ID para obtener tokens.

Orígenes de certificados

Microsoft. Identity.Web admite la carga de certificados desde varios orígenes:

Las credenciales de certificado se configuran en la matriz ClientCertificates dentro de la sección de configuración AzureAd (o AzureAdB2C). Puede especificar varios certificados para escenarios de rotación: Microsoft. Identity.Web usa el primer certificado válido que encuentra.

Desde Azure Key Vault (recomendado)

Azure Key Vault es el origen recomendado para los certificados en producción. Proporciona funcionalidades centralizadas de administración, control de acceso, auditoría y rotación automática.

Configuración

Agregue la configuración del certificado a 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"
      }
    ]
  }
}

Configurar las directivas de acceso de Key Vault

La identidad de la aplicación debe tener permiso para leer certificados desde el Key Vault. La forma de conceder esto depende de si utiliza el modelo de directiva de acceso de la bóveda o el Control de Acceso Basado en Rol (RBAC) de Azure.

Opción 1: Política de acceso de la bóveda

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

Opción 2: Azure RBAC

Asigne el rol Usuario de certificados de Key Vault a la identidad de la aplicación.

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>

Uso de identidad administrada para acceder a Key Vault

Cuando la aplicación se ejecuta en Azure (App Service, Azure Functions, Azure Kubernetes Service, VM), use identidad administrada para autenticarse en Key Vault. Esto elimina la necesidad de cualquier credencial para acceder a la propia bóveda.

Identidad administrada asignada por el sistema

Si la aplicación tiene habilitada una identidad administrada asignada por el sistema, Microsoft. Identity.Web usa automáticamente DefaultAzureCredential para autenticarse en Key Vault. No se necesita ninguna configuración adicional más allá de la ClientCertificates entrada:

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

Identidad administrada asignada por el usuario

Para una identidad administrada asignada por el usuario, especifique el ManagedIdentityClientId en el descriptor de certificado de 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"
      }
    ]
  }
}

Desde el almacén de certificados (solo Windows)

En Windows, puede cargar certificados desde el almacén de certificados de Windows. Esto es habitual para las implementaciones locales o hospedadas en IIS.

Por huella digital

Use StoreWithThumbprint para identificar el certificado mediante su huella digital SHA-1:

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

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

Por nombre distinguido

Use StoreWithDistinguishedName para identificar el certificado por su nombre de firmante:

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

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

Ubicaciones del almacén de certificados

En la tabla siguiente se enumeran las rutas de acceso comunes del almacén de certificados y los permisos necesarios para acceder a ellas:

Desde la ruta de acceso del archivo

Puede cargar un certificado directamente desde un archivo .pfx (PKCS#12) en el disco.

Configuración

Agregue la ruta de acceso y la contraseña del archivo de certificado a 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"

Desde el valor codificado en Base64

Puede proporcionar el certificado como una cadena codificada en Base64. Este enfoque es útil al insertar certificados a través de variables de entorno, secretos de Kubernetes o variables de canalización de CI/CD.

Configuración

Agregue el valor del certificado codificado en Base64 a appsettings.json:

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

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

Generación del valor Base64

Convertir un .pfx archivo en una cadena 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

Uso con secretos de Kubernetes

Almacene el certificado codificado en Base64 en un secreto de Kubernetes y asígnelo a una variable de entorno:

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

Haga referencia al secreto en la implementación:

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

Uso en canalizaciones de CI/CD

En Azure DevOps o Acciones de GitHub, almacene el certificado codificado en Base64 como una variable secreta y, a continuación, establézcalo como una variable de entorno en tiempo de ejecución.

Acciones de GitHub ejemplo:

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

Azure DevOps ejemplo:

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

Configuración de certificados en código de C#

Además de la configuración de JSON, puede configurar las credenciales de certificado mediante programación mediante la clase CredentialDescription de Microsoft.Identity.Abstractions.

Métodos auxiliares

La CredentialDescription clase proporciona métodos auxiliares estáticos para cada tipo de origen de certificado:

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

Uso en ASP.NET Core

Pase las descripciones de credenciales directamente al configurar la autenticación:

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

Creación de un certificado autofirmado para el desarrollo

Para el desarrollo y las pruebas locales, puede crear un certificado autofirmado. No use certificados autofirmados en producción.

Uso de PowerShell (Windows)

Ejecute los siguientes comandos para crear un certificado autofirmado, exportarlo y mostrar la huella digital:

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

Uso de OpenSSL (multiplataforma)

Ejecute los siguientes comandos para generar un certificado, empaquetarlo como un .pfx archivo y mostrar la huella digital:

# 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

Uso de la CLI de .NET

Exporte un certificado HTTPS de desarrollo como un .pfx archivo:

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

Registro del certificado en Microsoft Entra ID

Después de crear o obtener un certificado, debe registrar su clave pública con el registro de la aplicación en Microsoft Entra ID.

Uso del portal de Azure

1. Vaya al portal Azure y vaya a Microsoft Entra ID>Registros de aplicaciones.
2. Seleccione la aplicación.
3. Seleccione Certificados y secretos>Cargar>certificado.
4. Cargue el archivo .cer o .pem que contiene solo la clave pública. No cargue el .pfx archivo, que contiene la clave privada.
5. Tenga en cuenta el valor de huella digital que se muestra después de la carga; es posible que lo necesite para la configuración.

Uso de CLI de Azure

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

La --append marca agrega el certificado sin quitar las credenciales existentes.

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

Rotación de certificados

La rotación de certificados reemplaza un certificado que expira por uno nuevo antes de que expire, lo que garantiza un servicio ininterrumpido.

Estrategia: Superposición de certificados

El enfoque recomendado usa períodos de validez superpuestos:

1. Genere un nuevo certificado antes de que expire el actual (por ejemplo, de 30 a 60 días de antelación).
2. Registra el nuevo certificado en el registro de la aplicación Microsoft Entra junto al existente. Microsoft Entra ID acepta tokens firmados por cualquier certificado registrado.
3. Implementar el nuevo certificado en el origen del certificado de la aplicación (Key Vault, almacén de certificados, etc.).
4. Actualice la configuración (si es necesario) para que apunte al nuevo certificado.
5. Quite el certificado anterior del registro de la aplicación después de confirmar que todas las instancias usan la nueva.

Varios certificados en la configuración

Microsoft. Identity.Web admite la especificación de varios certificados. La biblioteca los intenta en orden y usa el primer certificado válido:

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

Rotación automática con Azure Key Vault

Azure Key Vault admite la renovación automática de certificados. Al habilitar la rotación automática:

1. Key Vault genera una nueva versión de certificado antes de la expiración.
2. Microsoft. Identity.Web recoge automáticamente la versión más reciente (en la siguiente captura de certificado).
3. La versión del certificado anterior sigue siendo válida hasta que expire.

Para configurar la rotación automática en Key Vault:

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

Solución de errores de certificados

En esta sección se enumeran los mensajes de error comunes y sus soluciones.

Errores frecuentes

No se encontró el certificado

Mensaje de error:

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

Posibles causas y soluciones:

Acceso denegado a Key Vault

Mensaje de error:

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

Soluciones:

• Compruebe que las directivas de acceso conceden get permiso para los certificados y secretos.
• Si usa Azure RBAC, asegúrese de que la identidad tiene el rol Key Vault Usuario de certificado.
• En Identidad administrada, confirme que la identidad está habilitada y que el identificador de objeto correcto se usa en la directiva.

No se puede acceder a la clave privada del certificado

Mensaje de error:

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

Soluciones:

• En Windows/IIS, asegúrese de que la identidad del grupo de aplicaciones tenga read acceso a la clave privada. Utilice el complemento MMC de certificados para conceder acceso a través de la función Administrar claves privadas.
• En Linux, compruebe que el .pfx archivo tiene los permisos de archivo adecuados (chmod 600).
• Asegúrese de que el certificado se exportó con la clave privada (Export-PfxCertificate o openssl pkcs12 -export).

El certificado ha expirado

Mensaje de error:

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

Soluciones:

• Compruebe el período de validez del certificado: openssl x509 -in cert.pem -noout -dates.
• Genere un nuevo certificado y actualice tanto el registro de aplicaciones como la configuración de la aplicación.
• Implemente la rotación de certificados para evitar problemas de expiración futuros. Consulte Rotación de certificados.

Contraseña de certificado incorrecta

Mensaje de error:

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

Soluciones:

• Compruebe CertificatePassword que coincide con la contraseña usada al exportar el .pfx archivo.
• Si usa variables de entorno, verifique si hay problemas de codificación (nuevas líneas al final, caracteres especiales).
• Vuelva a exportar el certificado con una contraseña conocida.

Lista de comprobación de diagnóstico

Use esta lista de comprobación cuando la autenticación de certificados no funcione:

• [ ] Validez del certificado: ¿el certificado está dentro de su período de validez? Comprueba las fechas de NotBefore y NotAfter.
• [ ] Registro de aplicaciones: ¿se carga la clave pública del certificado en el registro de aplicación correcto?
• [ ] Coincidencia de huella digital — ¿la huella digital de la configuración coincide con el certificado en el registro de la aplicación?
• [ ] Acceso a clave privada : ¿el proceso de aplicación puede leer la clave privada del certificado?
• [ ] Permisos de Key Vault — Para fuentes de Key Vault, ¿la identidad tiene permisos certificates/get y secrets/get?
• [ ] Sección de configuración : ¿Está la configuración del certificado en la sección correcta (AzureAd o AzureAdB2C)?
• [ ] PaquetesNuGet — ¿Está Microsoft.Identity.Web actualizado? Es posible que las versiones anteriores no sean compatibles con determinados tipos de origen de certificado.

Habilitar registro

Para obtener información detallada de diagnóstico, habilite el registro de MSAL:

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

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

Revise los registros de los mensajes sobre la carga de certificados, la creación de aserciones de cliente y la adquisición de tokens.

Contenido relacionado

• Introducción a las credenciales
• Autenticación sin certificados : identidad administrada e federación de identidades de carga de trabajo
• Secretos de cliente : tipo de credencial alternativo para aplicaciones confidenciales
• Descifrado de tokens — uso de certificados para el descifrado de tokens
• Registro y diagnóstico