Credenciales de certificado para la autenticación de aplicaciones en la plataforma de identidad de Microsoft

Artículo
04/10/2024

La Plataforma de identidad de Microsoft permite que una aplicación use sus propias credenciales para la autenticación en cualquier parte en la que podría usarse un secreto de cliente; por ejemplo, en el flujo de concesión de credenciales de cliente de OAuth 2.0 y el flujo con derechos delegados (OBO).

Un formato de credencial que una aplicación puede utilizar para la autenticación es una aserción de JSON Web Token (JWT) firmada con un certificado que la aplicación posea. Esto se describe en la especificación de Conectar OpenID para la opción de autenticación de cliente private_key_jwt.

Si está interesado en usar un JWT emitido por otro proveedor de identidades como credencial para la aplicación, consulte federación de identidades de carga de trabajo para obtener información sobre cómo configurar una directiva de federación.

Formato de aserción

Para calcular la aserción, puede usar una de las muchas bibliotecas de JWT en el lenguaje que prefiera. MSAL admite esto mediante .WithCertificate(). La información la lleva el token en el encabezado, las notificaciones y la firma.

Parámetro	Comentario
`alg`	Debe ser PS256
`typ`	Debe ser JWT
`x5t#s256`	Huella digital SHA-256 codificada en Base64url de la codificación DER del certificado X.509.

Notificaciones (carga útil)

Tipo de notificación	Value	Descripción
`aud`	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`	La notificación "aud" (audiencia) identifica los destinatarios para los que está previsto el JWT (en este caso Id. de Microsoft Entra). Vea RFC 7519, sección 4.1.3. En este caso, ese destinatario es el servidor de inicio de sesión (`login.microsoftonline.com`).
`exp`	1601519414	La notificación "exp" (fecha de expiración) identifica la hora de expiración en la que o después de la que el token JWT no debe ser aceptado para su procesamiento. Vea RFC 7519, Sección 4.1.4. Esto permite que la aserción se use hasta entonces, por lo que debe mantenerse a menos de 5-10 minutos después de `nbf` como máximo. Microsoft Entra ID no aplica restricciones en el tiempo de `exp` actualmente.
`iss`	{ClientID}	La notificación "iss" (emisor) identifica la entidad de seguridad que ha emitido el JWT; en este caso, la aplicación cliente. Use el identificador de aplicación GUID.
`jti`	(un GUID)	La notificación "jti" (Id. de JWT) proporciona un identificador único para el JWT. El valor de identificador debe asignarse de una manera que garantice que haya una probabilidad insignificante de que el mismo valor se asigne accidentalmente a un objeto de datos diferente; Si la aplicación usa varios emisores, también se deben evitar colisiones entre los valores generados por diferentes emisores. El valor "jti" es una cadena que distingue mayúsculas de minúsculas. RFC 7519, Sección 4.1.7.
`nbf`	1601519114	La notificación "nbf" (no antes de) identifica la hora antes de la cual no debe ser aceptado el token JWT para su procesamiento. RFC 7519, Sección 4.1.5. El uso de la hora actual es adecuado.
`sub`	{ClientID}	La notificación "sub" (asunto) identifica el asunto del JWT; en este caso, también su aplicación. Use el mismo valor que `iss`.
`iat`	1601519114	esta notificación señala en qué momento se emitió el JWT. Se puede usar para determinar la antigüedad del JWT. RFC 7519, Sección 4.1.5.

Firma

La firma se calcula mediante la aplicación del certificado, como se describe en Especificación RFC7519 de JSON Web Token. Use relleno PSS.

Ejemplo de una aserción de JWT descodificada

{
  "alg": "PS256",
  "typ": "JWT",
  "x5t#sha256": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "jti": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "nbf": 1484592741,
  "sub": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
}
.
"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u..."

Ejemplo de una aserción de JWT codificada

La cadena siguiente es un ejemplo de aserción codificada. Si observa detenidamente, verá tres secciones separadas por puntos (.):

La primera sección codifica el encabezado.
La segunda sección codifica las notificaciones (carga útil).
La última sección es la firma calculada con los certificados a partir del contenido de las dos primeras secciones.

"eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbVwvam1wcmlldXJob3RtYWlsLm9ubWljcm9zb2Z0LmNvbVwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQ4NDU5MzM0MSwiaXNzIjoiOTdlMGE1YjctZDc0NS00MGI2LTk0ZmUtNWY3N2QzNWM2ZTA1IiwianRpIjoiMjJiM2JiMjYtZTA0Ni00MmRmLTljOTYtNjVkYmQ3MmMxYzgxIiwibmJmIjoxNDg0NTkyNzQxLCJzdWIiOiI5N2UwYTViNy1kNzQ1LTQwYjYtOTRmZS01Zjc3ZDM1YzZlMDUifQ.
Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

Registro del certificado con la plataforma de identidad de Microsoft

Puede asociar la credencial de certificado con la aplicación cliente en la plataforma de identidad de Microsoft mediante el Centro de administración de Microsoft Entra con cualquiera de los métodos siguientes:

Cargar el archivo de certificado

En la pestaña Registros de aplicaciones de la aplicación cliente:

Seleccione Certificados y secretos>Certificados.
Seleccione Cargar certificado y seleccione el archivo de certificado que se va a cargar.
Seleccione Agregar. Una vez que se carga el certificado, se muestra la huella digital, la fecha de inicio y los valores de expiración.

Actualizar el manifiesto de aplicación

Después de adquirir un certificado, calcule estos valores:

$base64Thumbprint: valor codificado en Base 64 del hash del certificado
$base64Value: valor codificado en Base 64 de los datos sin procesar del certificado

Proporcione un GUID para identificar la clave en el manifiesto de la aplicación ($keyId).

En el registro de aplicación de Azure para la aplicación cliente:

Seleccione Manifiesto para abrir el manifiesto de aplicación.

Reemplace la propiedad keyCredentials por la información del nuevo certificado con el siguiente esquema.

"keyCredentials": [
    {
        "customKeyIdentifier": "$base64Thumbprint",
        "keyId": "$keyid",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value":  "$base64Value"
    }
]

Guarde las modificaciones en el manifiesto de aplicación y cárguelo en la plataforma de identidad de Microsoft.

La propiedad keyCredentials es multivalor, por lo que puede cargar varios certificados para una administración de claves más eficaz.

Uso de una aserción de cliente

Las aserciones de cliente se pueden usar en cualquier lugar en el que se use un secreto de cliente. Por ejemplo, en el flujo de código de autorización, puede pasar un objeto client_secret para demostrar que la solicitud procede de la aplicación. Puede reemplazarlo por parámetros client_assertion y client_assertion_type.

Parámetro	Valor	Descripción
`client_assertion_type`	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`	Se trata de un valor fijo que indica que usa una credencial de certificado.
`client_assertion`	`JWT`	Este es el JWT creado anteriormente.

Pasos siguientes

La biblioteca MSAL.NET controla este escenario en una sola línea de código.

En el ejemplo de código Aplicación de consola de demonio de .NET Core con la Plataforma de identidad de Microsoft de GitHub se muestra cómo utiliza una aplicación sus propias credenciales para la autenticación. También se muestra cómo se puede crear un certificado autofirmado mediante el cmdlet de PowerShell New-SelfSignedCertificate. También puede usar los scripts de creación de aplicaciones del repositorio de ejemplos para crear los certificados, calcular la huella digital, etc.

Compartir a través de