Configure el descifrado de tokens en Microsoft. Identity.Web

En este artículo se explica cómo configurar certificados de descifrado de tokens en Microsoft. Identity.Web para que la aplicación pueda descifrar tokens cifrados de la Plataforma de identidad de Microsoft.

De forma predeterminada, el Plataforma de identidad de Microsoft emite tokens (tokens de identificador, tokens de SAML) como JWT firmados pero sin cifrar. Cualquier intermediario que intercepte un token puede leer las declaraciones. En el caso de las aplicaciones que controlan notificaciones confidenciales o funcionan en entornos de cumplimiento estrictos, el Plataforma de identidad de Microsoft admite el cifrado token. Cuando se habilita, la plataforma de identidad cifra la carga del token mediante una clave pública registrada con la aplicación. Solo la aplicación ,que contiene la clave privada correspondiente, puede descifrar y leer el token.

Funcionamiento del cifrado de tokens

1. Se genera un certificado con un par de claves pública o privada.
2. Sube la clave pública (el archivo .cer) en el registro de la aplicación en Microsoft Entra ID.
3. Cuando el Plataforma de identidad de Microsoft emite un token para la aplicación, cifra el token mediante la clave pública.
4. La aplicación usa la clave privada para descifrar el token antes de procesar las notificaciones.

El cifrado usa un esquema de dos capas: la carga del token se cifra con una clave de cifrado de contenido simétrica, que se encapsula (cifra) mediante la clave pública. Microsoft Entra admite algoritmos de ajuste de claves RSA-OAEP y RSA-OAEP-256.

Determinar cuándo configurar el descifrado de tokens

Configure el descifrado de tokens cuando la aplicación cumpla una de las condiciones siguientes:

• Recibe tokens SAML cifrados : aplicaciones empresariales que usan el inicio de sesión único basado en SAML y requieren aserciones de SAML cifradas por motivos normativos o de cumplimiento.
• Recibe tokens de ID cifrados — las aplicaciones web que optan por el cifrado de tokens de ID para proteger los reclamos sensibles (pertenencias a grupos, reclamos personalizados) de ser leídos en tránsito.
• Funciona en entornos de alta seguridad: aplicaciones en escenarios gubernamentales, financieros o sanitarios en los que la directiva exige la confidencialidad de los tokens.

Cumplir los requisitos previos

Antes de configurar el descifrado de tokens, compruebe los siguientes requisitos:

• Un certificado X.509 con una clave privada: necesita un certificado en formato .pfx (PKCS#12) o almacenado en una ubicación accesible para la aplicación (Azure Key Vault, almacén de certificados o sistema de archivos). La clave privada es necesaria para descifrar tokens.
• Registro de aplicaciones configurado para el cifrado de tokens: cargue la clave pública del certificado en el registro de la aplicación en Microsoft Entra ID. Consulte Registro del certificado de descifrado más adelante en este artículo.
• Microsoft.Identity.Web 2.1.0 o posterior: La propiedad de configuración TokenDecryptionCredentials está disponible en Microsoft.Identity.Web 2.1.0 y versiones posteriores.

Configuración del descifrado de tokens en appsettings.json

Microsoft.Identity.Web usa la matriz TokenDecryptionCredentials en la sección de configuración AzureAd. Esta matriz sigue el mismo formato de descripción de credenciales que ClientCredentials, por lo que puede cargar certificados de descifrado desde Azure Key Vault, el almacén de certificados, una ruta de acceso de archivo o una cadena codificada en Base64.

Configurar una configuración básica

En el ejemplo siguiente se muestra la configuración mínima para cargar un certificado de descifrado desde Azure Key Vault:

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

    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "MyCertificate"
      }
    ]
  }
}

No se requiere código adicional. Cuándo Microsoft. Identity.Web detecta la configuración de TokenDecryptionCredentials, carga automáticamente el certificado especificado y lo registra con el controlador de autenticación de OpenID Connect para el descifrado de tokens.

Elección de un origen de credenciales

La TokenDecryptionCredentials matriz admite los mismos tipos de origen que ClientCredentials. En la tabla siguiente se resume cada opción:

Key Vault (recomendado para producción)

La siguiente configuración carga un certificado de descifrado de Azure Key Vault:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert"
    }
  ]
}

La identidad administrada o la entidad de servicio de la aplicación deben tener permisos Get y List en los certificados de Key Vault.

Almacén de certificados (Windows)

La siguiente configuración carga un certificado desde el almacén de certificados de Windows mediante huella digital:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "StoreWithThumbprint",
      "CertificateStorePath": "CurrentUser/My",
      "CertificateThumbprint": "A1B2C3D4E5F6..."
    }
  ]
}

Ruta de acceso del archivo

La siguiente configuración carga un certificado de un archivo en el .pfx disco:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Path",
      "CertificateDiskPath": "/var/ssl/private/decrypt-cert.pfx",
      "CertificatePassword": "your-certificate-password"
    }
  ]
}

Codificado en Base64

La siguiente configuración carga un certificado de una cadena codificada en Base64:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Base64Encoded",
      "Base64EncodedValue": "MIIJ..."
    }
  ]
}

Esta opción es útil al insertar el certificado a través de una variable de entorno o un secreto de canalización de CI/CD.

Configuración de varios certificados de descifrado

Puede especificar varios certificados en la TokenDecryptionCredentials matriz. Microsoft. Identity.Web intenta cada certificado en orden hasta que uno descifra correctamente el token. Esta funcionalidad es esencial para la rotación de certificados (consulte Rotación de certificados).

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-New"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-Old"
    }
  ]
}

Registro del certificado de descifrado en Microsoft Entra ID

Para que el Plataforma de identidad de Microsoft cifre tokens para su aplicación, debe cargar la clave pública del certificado en el registro de la aplicación.

1. Inicie sesión en el Centro de administración Microsoft Entra.
2. Vaya a Identity>Applications>Registros de aplicaciones y seleccione la aplicación.
3. Seleccione Certificados y secretos>Cargar>certificado.
4. Cargue el .cer archivo (solo clave pública) del certificado de descifrado.
5. Después de cargar, anote el valor de huella digital ; debe coincidir con el certificado que usa la aplicación.

Habilitación del cifrado de tokens para la aplicación

Después de cargar el certificado, debe configurar la aplicación para recibir tokens cifrados. Esta configuración está disponible actualmente a través de Microsoft Graph API o PowerShell:

Uso Microsoft Graph PowerShell:

# Get the key credential ID of the uploaded certificate
$app = Get-MgApplication -Filter "appId eq 'your-client-id'"
$keyId = ($app.KeyCredentials | Where-Object { $_.DisplayName -eq "CN=TokenDecryptionCert" }).KeyId

# Set the token encryption key ID
Update-MgApplication -ApplicationId $app.Id -BodyParameter @{
    "tokenEncryptionKeyId" = $keyId
}

Rotación de certificados de descifrado

La rotación de certificados para el descifrado de tokens requiere un enfoque cuidadosa y por fases para evitar tiempo de inactividad:

Pasos de rotación

1. Generar un nuevo certificado : cree un nuevo certificado X.509 con una clave privada.
2. Agregue el nuevo certificado a la configuración de la aplicación: agregue el nuevo certificado a la TokenDecryptionCredentials matriz junto con el certificado existente. Coloque primero el nuevo certificado en la matriz.
3. Sube la nueva clave pública — Sube el archivo del nuevo .cer certificado a tu registro de aplicación en Microsoft Entra.
4. Implementar la aplicación: implemente la configuración actualizada para que la aplicación pueda descifrar tokens con cualquiera de los certificados.
5. Cambiar la clave de cifrado activa : actualice tokenEncryptionKeyId en el objeto de aplicación para que apunte al nuevo certificado keyId.
6. Comprobar : confirme que la aplicación descifra correctamente los tokens cifrados con el nuevo certificado.
7. Quitar el certificado antiguo : después de un período de gracia (al menos 24 horas para permitir que expiren los tokens almacenados en caché), quite el certificado antiguo del registro de la aplicación y de la configuración de la aplicación.

Configuración durante la rotación

Durante la ventana de rotación, TokenDecryptionCredentials debe contener ambos certificados:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2026"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2025"
    }
  ]
}

Resolución de problemas de descifrado de tokens

Use las instrucciones siguientes para diagnosticar y resolver problemas comunes de descifrado de tokens.

Errores de descifrado de tokens

Síntoma: La aplicación produce o SecurityTokenDecryptionFailedException devuelve un error 401/500 al procesar tokens.

Causas comunes:

Falta la clave privada

Síntoma:CryptographicException: The certificate key is not accessible o InvalidOperationException: Certificate does not have a private key.

Causas y soluciones:

• Certificado exportado sin clave privada : vuelva a exportar el certificado en .pfx formato y asegúrese de incluir la clave privada durante la exportación.
• Directiva de acceso de Key Vault: cuando use Azure Key Vault, asegúrese de que la identidad de la aplicación tenga el permiso Get en ambos Certificates y Secrets. La clave privada se almacena como un secreto en Key Vault.
• Certificate store permissions : en Windows, compruebe que la identidad del grupo de aplicaciones o la cuenta de servicio tenga acceso de lectura a la clave privada. Use la opción Administrar claves privadas en el complemento MMC del almacén de certificados.

Error de coincidencia de algoritmos

Síntoma:SecurityTokenDecryptionFailedException con un mensaje que indica un algoritmo no admitido.

Causas y soluciones:

• Tipo de clave no compatible: Microsoft Entra admite certificados RSA para el cifrado de tokens. Asegúrese de que el certificado usa un par de claves RSA (no EC/ECDSA).
• Tamaño de clave demasiado pequeño: use un tamaño de clave de al menos 2048 bits. Es posible que se rechacen las claves RSA menores que 2048 bits.
• Algoritmo no soportado: Microsoft Entra usa RSA-OAEP para el ajuste de claves. Asegúrese de que el certificado y la infraestructura de aplicaciones admiten este algoritmo.

Tokens cifrados que no están siendo emitidos

Síntoma: La aplicación recibe tokens sin cifrar aunque haya configurado el descifrado de tokens.

Causas y soluciones:

• tokenEncryptionKeyId no configurado : debe establecer explícitamente esta propiedad a través de Microsoft Graph. Cargar el certificado por sí solo no es suficiente.
• Certificado expirado en el registro de aplicaciones : compruebe que el certificado cargado en el registro de la aplicación no ha expirado. Cargue un nuevo certificado si es necesario.
• Los tokens de acceso no están cifrados : el cifrado de tokens solo se aplica a tokens de identificador y tokens SAML . Los tokens de acceso de Microsoft Entra no se cifran con el certificado.

Comparación del descifrado de tokens y las credenciales de cliente

Las credenciales de descifrado de tokens sirven para un propósito diferente de las credenciales de cliente. La aplicación puede usar el mismo certificado para ambos o usar certificados independientes.

En el ejemplo siguiente se muestra una configuración que usa el mismo certificado de Key Vault para la autenticación y el descifrado de tokens:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ],
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ]
  }
}

Seguimiento de los procedimientos recomendados

Aplique estas recomendaciones al implementar el descifrado de tokens.

Use Azure Key Vault: almacene certificados de descifrado en Key Vault para la administración centralizada, el control de acceso y el registro de auditoría.

Plan de rotación — siempre tenga una estrategia de rotación antes de implementar el cifrado de tokens. Incluya los certificados tanto nuevos como antiguos durante la ventana de rotación.

Use claves RSA de 2048 bits o más grandes: asegúrese de que los certificados usan claves RSA de al menos 2048 bits para una seguridad adecuada.

Monitor certificate expiration — Configure alertas en Azure Key Vault o el sistema de monitorización para notificarle antes de que los certificados expiren.

Prueba en un entorno de ensayo : compruebe el cifrado y el descifrado de tokens en un entorno que no sea de producción antes de habilitarlo en producción.

No almacenes claves privadas en el control de código fuente: usa Key Vault, variables de entorno o un administrador de secretos para almacenar los certificados.

No quite el certificado antiguo demasiado pronto durante la rotación : mantenga ambos certificados activos durante al menos 24 horas para permitir que los tokens almacenados en caché expiren.

No habilite el cifrado de tokens sin un certificado de descifrado configurado : la aplicación no podrá procesar tokens si no se pueden descifrar.

Contenido relacionado

• Introducción a las credenciales
• Introducción a la caché de tokens
• Autorización en API web
• Credenciales de certificado