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

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 RS256
typ Debe ser JWT
x5t Huella digital SHA-1 codificada en base64url de la codificación DER del certificado X.509. Por ejemplo, para un hash de certificado X.509 con el valor 84E05C1D98BCE3A5421D225B140B36E86A3D5534 (hexadecimal), la notificación x5t sería hOBcHZi846VCHSJbFAs26Go9VTQ (Base64url).

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, el 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. En la actualidad, Id. de Microsoft Entra no impone restricciones en el tiempo de exp.
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 del identificador se debe asignar de forma que se garantice que hay una probabilidad insignificante de que el mismo valor se asigne por accidente a otro objeto de datos; si en la aplicación se usan varios emisores, también se DEBEN evitar las colisiones entre los valores generados por otros 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.

Ejemplo de una aserción de JWT descodificada

{
  "alg": "RS256",
  "typ": "JWT",
  "x5t": "gx8tGysyjcRqKjFPnd7RFwvwZI0"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "97e0a5b7-d745-40b6-94fe-5f77d35c6e05",
  "jti": "22b3bb26-e046-42df-9c96-65dbd72c1c81",
  "nbf": 1484592741,
  "sub": "97e0a5b7-d745-40b6-94fe-5f77d35c6e05"
}
.
"Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

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:

  1. Seleccione Certificados y secretos>Certificados.
  2. Haga clic en Cargar certificado y seleccione el archivo del certificado que va a cargar.
  3. Haga clic en 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:

  1. Seleccione Manifiesto para abrir el manifiesto de aplicación.

  2. 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"
        }
    ]
    
  3. 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 está usando 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.