Tokens de acceso de la Plataforma de identidad de Microsoft

  • Artículo

Los tokens de acceso permiten a los clientes llamar de forma segura a las API web protegidas. Las API web usan tokens de acceso para hacer la autenticación y autorización.

Según la especificación de OAuth, los tokens de acceso son cadenas opacas sin un formato establecido. Algunos proveedores de identidades (IDP) utilizan GUID y otros usan blobs cifrados. El formato del token de acceso puede depender de la configuración de la API que lo acepta.

Las API personalizadas registradas por desarrolladores en la Plataforma de identidad de Microsoft pueden elegir entre dos formatos distintos de JSON Web Token (JWT), denominados v1.0 y v2.0. Las API desarrolladas por Microsoft, como Microsoft Graph o las API de Azure, tienen otros formatos de token propietarios. Estos formatos propietarios que no se pueden validar pueden ser tokens cifrados, JWT o JWT especiales.

El contenido del token solo está pensado para la API, lo que significa que los tokens de acceso deben tratarse como cadenas opacas. Para fines únicamente de validación y depuración, los desarrolladores pueden decodificar los token JWT mediante un sitio como jwt.ms. Los tokens que recibe una API de Microsoft podría no siempre ser un JWT que se puede decodificar.

Los clientes deben usar los datos de respuesta del token que se devuelven con el token de acceso para obtener más información sobre lo que contiene. Cuando el cliente solicita un token de acceso, la Plataforma de identidad de Microsoft también devuelve algunos metadatos sobre el token de acceso para el consumo de la aplicación. Esta información incluye la hora de expiración del token de acceso y los ámbitos para los que es válido. Estos datos permiten a la aplicación realizar un almacenamiento inteligente en caché de los tokens de acceso sin tener que analizar el mismo token de acceso.

Consulte las secciones siguientes para saber cómo una API puede validar y utilizar las notificaciones dentro de un token de acceso.

Nota

Toda la documentación de esta página, excepto donde se indique lo contrario, se aplica solo a los tokens emitidos para las API que ha registrado. No se aplica a los tokens emitidos para las API de Microsoft ni esos tokens se pueden usar para validar el modo en que la Plataforma de identidad de Microsoft emite tokens para una API registrada.

Formatos de tokens

Hay dos versiones de tokens de acceso disponibles en la Plataforma de identidad de Microsoft: v1.0 y v2.0. Estas versiones determinan las notificaciones que están en el token y asegúrese de que una API web puede controlar el contenido del token.

Las API web tienen una de las siguientes versiones seleccionadas como predeterminadas durante el registro:

  • v1.0 para aplicaciones exclysivas de Microsoft Entra. En el ejemplo siguiente se muestra un token v1.0 (las claves se cambian y se quita la información personal, lo que impide la validación de los tokens):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

  • v2.0 para aplicaciones que admiten cuentas de consumidor. En el ejemplo siguiente se muestra un token v2.0 (las claves se cambian y se quita la información personal, lo que impide la validación de los tokens):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Para establecer la versión de las aplicaciones, indique el valor adecuado a la configuración de accessTokenAcceptedVersion en el manifiesto de la aplicación. Los valores de null y 1 dan como resultado tokens v1.0 y el valor de 2 da como resultado tokens v2.0.

Propiedad de tokens

En una solicitud de token de acceso participan dos partes: el cliente, que es quien solicita el token, y el recurso (la API web) que acepta el token. El recurso para el que está pensado el token (su audiencia) se define en la notificación aud en un token. Los clientes usan el token, pero no deben entenderlo ni intentar analizarlo. Los recursos aceptan el token.

La Plataforma de identidad de Microsoft admite la emisión de cualquier versión de token desde cualquier punto de conexión de la versión. Por ejemplo, cuando el valor de accessTokenAcceptedVersion es 2, un cliente, que llama al punto de conexión v1.0 para obtener un token para ese recurso, recibe un token de acceso v2.0.

Los recursos siempre poseen sus tokens mediante la notificación aud y son las únicas aplicaciones que pueden modificar los detalles del token.

Duración del token

La duración predeterminada de un token de acceso es variable. Cuando se emite, el Plataforma de identidad de Microsoft asigna un valor aleatorio comprendido entre 60 y 90 minutos (75 minutos en promedio) como la duración predeterminada de un token de acceso. La variación mejora la resistencia del servicio al distribuir la demanda de tokens de acceso a lo largo del tiempo, lo que evita picos por hora en el tráfico a Microsoft Entra ID.

Los inquilinos que no usan el acceso condicional tienen una vigencia predeterminada de token de acceso de dos horas para clientes como Microsoft Teams y Microsoft 365.

Ajuste la vigencia de un token de acceso para controlar la frecuencia con la que la aplicación cliente expira la sesión de la aplicación y requerirá que el usuario se vuelva a autenticar (de manera silenciosa o interactiva). Para reemplazar la variación de vigencia del token de acceso predeterminada, utilice Vigencia de token configurable (CTL).

Aplique la variación predeterminada de la vigencia del token a las organizaciones que tienen habilitada la Evaluación continua de acceso (CAE). Aplique la variación de vigencia predeterminada del token incluso si las organizaciones usan directivas de CTL. La vigencia predeterminada del token en la vigencia de tokens de larga duración oscila entre 20 y 28 horas. Cuando el token de acceso expira, el cliente debe usar el token de actualización para adquirir un nuevo token de actualización en modo silencioso y un token de acceso.

Las organizaciones que usan la frecuencia de inicio de sesión de acceso condicional (SIF) para exigir la frecuencia con la que se producen los inicios de sesión no pueden reemplazar la variación predeterminada de la vigencia del token de acceso. Cuando las organizaciones usan SIF, el tiempo entre las solicitudes de credenciales de un cliente es la vigencia del token (de 60 a 90 minutos) más el intervalo de frecuencia de inicio de sesión.

Este es un ejemplo de cómo funciona la variación predeterminada de la vigencia del token con la frecuencia de inicio de sesión. Supongamos que una organización establece la frecuencia de inicio de sesión para que se produzca cada hora. Cuando el token tiene una vigencia de entre 60 y 90 minutos debido a la variación de vigencia del token, el intervalo de inicio de sesión real se produce entre 1 hora y 2,5 horas.

Si un usuario con un token con una vigencia de una hora hace un inicio de sesión interactivo a los 59 minutos, no habrá ningún mensaje de solicitud de credenciales porque el inicio de sesión está por debajo del umbral de SIF. Si un nuevo token tiene una vigencia de 90 minutos, el usuario no vería un mensaje de solicitud de credenciales hasta dentro de una hora y media más. Durante un intento de renovación silenciosa, Microsoft Entra ID requiere una solicitud de credenciales porque la longitud total de la sesión ha superado el valor de la frecuencia de inicio de sesión de 1 hora. En este ejemplo, la diferencia de tiempo entre los mensajes de solicitud de credenciales debido al intervalo de SIF y la variación de la vigencia del token sería de 2,5 horas.

Validar tokens

No todas las aplicaciones deben validar los tokens. Las aplicaciones deben validar un token solo en escenarios específicos:

  • Las API web deben validar los tokens de acceso que les envía un cliente. Solo deben aceptar tokens que contengan uno de sus URI de AppId comoaud notificación.
  • Las aplicaciones web deben validar los tokens de identificación que se les envían utilizando el navegador del usuario en el flujo híbrido, antes de permitir el acceso a los datos de un usuario o establecer una sesión.

Si no se aplica ninguno de los escenarios descritos anteriormente, no es necesario validar el token. Los clientes públicos, como las aplicaciones nativas, de escritorio o de una sola página, no se benefician de la validación de los tokens de identificación porque la aplicación se comunica directamente con el IDP, donde la protección SSL garantiza que los tokens de identificación son válidos. No deberían validar los tokens de acceso, ya que son para que los valide la API web, no el cliente.

Las API y aplicaciones web solo deben validar los tokens que tengan una notificación aud que coincida con su aplicación. Otros recursos pueden tener reglas de validación de tokens personalizados. Por ejemplo, no se pueden validar los tokens para Microsoft Graph según estas reglas debido a su formato propietario. La validación y aceptación de tokens destinados a otro recurso es un ejemplo del problema de intermediario confundido.

Si la aplicación necesita validar un token de identificador o un token de acceso, primero debe validar la firma y el emisor del token con respecto a los valores del documento de detección de OpenID.

El middleware de Microsoft Entra tiene funciones integradas para validar los tokens de acceso, consulte ejemplos para buscar uno en el idioma adecuado. Existen varias bibliotecas de código abierto de terceros que también están disponibles para validación de JWT. Para más información sobre los ejemplos de código y las bibliotecas de autenticación, consulte las bibliotecas de autenticación. Si su aplicación web o API web está en ASP.NET o ASP.NET Core, utilice Microsoft.Identity.Web, que se encarga de la validación por usted.

Tokens de las versiones 1.0 y 2.0

  • Cuando la aplicación web o la API validan un token v1.0 (ver notificación ="1.0"), debe leer el documento de metadatos de OpenID Connect del punto de conexión v1.0 (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configuration), incluso si la autoridad configurada para la API web es una entidad v2.0.
  • Cuando la aplicación web o la API validan un token v2.0 (ver notificación ="2.0"), debe leer el documento de metadatos de OpenID Connect del punto de conexión v2.0 (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration), incluso si la autoridad configurada para la API web es una entidad v1.0.

En los siguientes ejemplos supone que la aplicación valida un token de acceso v2.0 (y, por tanto, haga referencia a las versiones v2.0 de los documentos y claves de metadatos de OIDC). Solo tiene que quitar "/v2.0" en la dirección URL si valida los tokens v1.0.

Validar el emisor

OpenID Connect Core dice "El identificador del emisor [...] DEBE coincidir exactamente con el valor de la notificación del emisor". En el caso de las aplicaciones que usan un punto de conexión de metadatos específico del inquilino (como https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configuration o https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration), esto es todo lo que se necesita.

Microsoft Entra ID tiene una versión independiente del inquilino del documento disponible en https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Este punto de conexión devuelve un valor de emisor https://login.microsoftonline.com/{tenantid}/v2.0. Las aplicaciones pueden usar este punto de conexión independiente del inquilino para validar tokens de cada inquilino con las siguientes modificaciones:

  1. En lugar de esperar que la notificación del emisor del token coincida exactamente con el valor del emisor de los metadatos, la aplicación debe reemplazar el valor {tenantid} de los metadatos del emisor por el identificador de inquilino que es el destino de la solicitud actual y, a continuación, comprobar la coincidencia exacta.

  2. La aplicación debe usar la propiedad issuer devuelta desde el punto de conexión de claves para restringir el ámbito de las claves.

    • Las claves que tienen un valor de emisor como https://login.microsoftonline.com/{tenantid}/v2.0 se pueden usar con cualquier emisor de token coincidente.
    • Las claves que tienen un valor de emisor como https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 solo se deben usar con coincidencia exacta.

    El punto de conexión de clave independiente del inquilino de Microsoft Entra (https://login.microsoftonline.com/common/discovery/v2.0/keys) devuelve un documento como el siguiente:

    {
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

  3. Las aplicaciones que usan la notificación de identificador de inquilino (tid) de Microsoft Entra como límite de confianza en lugar de la notificación del emisor estándar deben asegurarse de que la notificación tenant-id es un guid y que el emisor y el identificador de inquilino coinciden.

El uso de metadatos independientes del inquilino es más eficaz para las aplicaciones que aceptan tokens de muchos inquilinos.

Nota:

Con los metadatos independientes del inquilino de Microsoft Entra, las notificaciones se deben interpretar dentro del inquilino, al igual que en OpenID Connect estándar, las notificaciones se interpretan dentro del emisor. Es decir, {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"} y {"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"} describen distintos usuarios, aunque sub sea el mismo, porque las notificaciones como sub se interpretan en el contexto del emisor o inquilino.

validar la firma

Un JWT contiene tres segmentos, separados por el carácter .. El primer segmento es el encabezado, el segundo el cuerpo y el tercero la firma. Use el segmento de firma para evaluar la autenticidad del token.

Microsoft Entra ID emite tokens firmados con algoritmos de cifrado asimétrico estándar del sector, como RS256. El encabezado de JWT contiene información acerca de clave y el método de cifrado utilizados para firmar el token:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

La notificación alg indica el algoritmo que se usó para firmar el token, mientras que la notificación kid indica la clave pública concreta que se usó para validar el token.

En cualquier momento, Microsoft Entra ID puede firmar un id. de token mediante cualquiera de un determinado conjunto de pares de claves pública y privada. Microsoft Entra ID rota los posibles conjuntos de claves de manera periódica, por tanto, escriba la aplicación para manejar esos cambios de clave automáticamente. Una frecuencia razonable para comprobar las actualizaciones de las claves públicas usadas por Microsoft Entra ID es cada 24 horas.

Adquiera los datos de las claves de firmas necesarios para validar la firma utilizando el documento de metadatos de OpenID Connect, ubicado en:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Sugerencia

Pruebe esto en un explorador: DIRECCIÓN URL

La siguiente información describe el documento de metadatos:

  • Es un objeto JSON que contiene varios fragmentos de información útiles, como la ubicación de los diferentes puntos de conexión necesarios para realizar la autenticación de OpenID Connect.
  • Incluye un jwks_uri, que ofrece la ubicación del conjunto de claves públicas que corresponden a las claves privadas que se utilizan para firmar los tokens. La clave web JSON (JWK)que se encuentra en jwks_uri contiene toda la información de clave pública en uso en ese momento determinado. RFC 7517 describe el formato JWK. La aplicación puede usar la notificación kid en el encabezado de JWT para seleccionar la clave pública, desde este documento, que corresponde a la clave privada que se ha usado para firmar un token determinado. Después, puede realizar la validación de la firma mediante la clave pública correcta y el algoritmo indicado.

Nota:

Use la notificación kid para validar el token. Aunque los tokens v1.0 contienen las notificaciones x5t y kid, los tokens v2.0 solo contienen la notificación kid.

Cómo se realiza la validación de la firma queda fuera del ámbito de este documento. Hay muchas bibliotecas de código abierto disponibles para ayudar con la validación de firmas si es necesario. Sin embargo, la Plataforma de identidad de Microsoft tiene una extensión de firma de tokens para los estándares, que son las claves de firma personalizadas.

Si la aplicación tiene claves de firma personalizadas como resultado del uso de la característica Asignación de notificaciones, anexe un parámetro de consulta appid que contenga el id. de aplicación. Para la validación, utilice jwks_uri que apunta a la información de clave de firma de la aplicación. Por ejemplo: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444 contiene el elemento jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444.

Validar el emisor

Las aplicaciones web que validan tokens de identificación y las API web que validan tokens de acceso deben validar el emisor del token (issnotificación) con:

  1. el emisor disponible en el documento de metadatos de Conexión de OpenID asociado a la configuración de la aplicación (autoridad). El documento de metadatos con el que se va a realizar la comprobación depende de:
    • la versión del token
    • las cuentas admitidas por la aplicación.
  2. el identificador de inquilino (tid notificación) del token,
  3. el emisor de la clave de firma.

Aplicaciones de inquilino único

OpenID Connect Core dice "El identificador del emisor [...] DEBE coincidir exactamente con el valor de laiss notificación (emisor)". En el caso de las aplicaciones que usan un punto de conexión de metadatos específico del inquilino (como https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration o https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration ), esto es todo lo que se necesita.

Las aplicaciones de inquilino único son aplicaciones que admiten:

  • Cuentas en un directorio organizativo (solo example-tenant-id ): https://login.microsoftonline.com/{example-tenant-id}
  • Solo cuentas personales de Microsoft: https://login.microsoftonline.com/consumers (los consumidores son un alias para el inquilino 9188040d-6c67-4c5b-b112-36a304b66dad)

Aplicaciones multiinquilino

Microsoft Entra ID también admite aplicaciones multi-inquilino. Estas aplicaciones admiten:

  • Cuentas en cualquier directorio organizativo (cualquier directorio Microsoft Entra): https://login.microsoftonline.com/organizations
  • Cuentas en cualquier directorio organizativo (cualquier directorio Microsoft Entra) y cuentas personales de Microsoft (por ejemplo, Skype, XBox): https://login.microsoftonline.com/common

Para estas aplicaciones, Microsoft Entra ID expone versiones independientes del inquilino del documento OIDC en https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration y https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration respectivamente. Estos puntos de conexión devuelven un valor de emisor, que es una plantilla parametrizada por tenantid: https://login.microsoftonline.com/{tenantid}/v2.0. Las aplicaciones pueden usar estos puntos de conexión independientes del inquilino para validar tokens de cada inquilino con las siguientes estipulaciones:

  • Validación del emisor de la clave de firma
  • En lugar de esperar que la notificación del emisor en el token coincida exactamente con el valor del emisor de los metadatos, la aplicación debe sustituir el {tenantid}valor de los metadatos del emisor por el ID del inquilino que es el objetivo de la solicitud actual y después comprobar la coincidencia exacta (tidnotificación del token).
  • Valide que la notificación tid es un GUID y la notificación iss es de la forma https://login.microsoftonline.com/{tid}/v2.0, donde {tid} es la notificación exacta tid. Esta validación vincula el inquilino al emisor y al ámbito de la clave de firma que crea una cadena de confianza.
  • Las aplicaciones multi-inquilino deben usar tid la notificación cuando localizan los datos asociados al sujeto de la notificación. Es decir, la tid notificación debe formar parte de la clave utilizada para acceder a los datos del usuario.

Validación del emisor de la clave de firma

Las aplicaciones que usan los metadatos independientes del inquilino v2.0 necesitan validar el emisor de la clave de firma.

Emisor de claves de firma y documento de claves

Como se explicó, en el documento OpenID Connect, la aplicación accede a las claves usadas para firmar los tokens. Obtiene el documento de claves correspondiente accediendo a la dirección URL expuesta en la propiedad jwks_uri del documento OpenIdConnect.

 "jwks_uri": "https://login.microsoftonline.com/{example-tenant-id}/discovery/v2.0/keys",

El valor {example-tenant-id} puede sustituirse por un GUID, un nombre de dominio o un nombre común, organizaciones y consumidores.

Los documentos de keys expuestos por Azure AD v2.0 contienen, para cada clave, el emisor que usa esta clave de firma. Por ejemplo, el punto final de clave "común" independiente del inquilino https://login.microsoftonline.com/common/discovery/v2.0/keys devuelve un documento como:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Validación del emisor de la clave de firma

La aplicación debe usar la issuer propiedad del documento de claves, asociada a la clave utilizada para firmar el token, con el fin de restringir el ámbito de las claves:

  • Las claves que tienen un valor de emisor con un GUID como https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 solo se deben usar cuando la iss notificación del token coincide exactamente con el valor.
  • Las claves que tienen un valor de emisor con plantilla como https://login.microsoftonline.com/{tenantid}/v2.0 solo se deben usar cuando la iss notificación del token coincide con este valor después de sustituir la tid notificación en el token para el {tenantid} marcador de posición.

El uso de metadatos independientes del inquilino es más eficaz para las aplicaciones que aceptan tokens de muchos inquilinos.

Nota:

Con los metadatos independientes del inquilino de Microsoft Entra, las notificaciones se deben interpretar dentro del inquilino, al igual que en OpenID Connect estándar, las notificaciones se interpretan dentro del emisor. Es decir, {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} y {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} describen distintos usuarios, aunque sub sea el mismo, porque las notificaciones como sub se interpretan en el contexto del emisor o inquilino.

Resumen

He aquí un pseudocódigo que recapitula cómo validar el emisor y el emisor de la clave de firma:

  1. Captura de claves de la dirección URL de metadatos configurada
  2. Compruebe si el token está firmado con una de las claves publicadas, produce un error si no es así
  3. Identificar la clave en los metadatos basándose en la cabecera kid. Compruebe la propiedad "issuer" asociada a la clave en el documento de metadatos: 
    var issuer = metadata["kid"].issuer;
if (issuer.contains("{tenantId}", CaseInvariant)) issuer = issuer.Replace("{tenantid}", token["tid"], CaseInvariant);
if (issuer != token["iss"]) throw validationException;
if (configuration.allowedIssuer != "*" && configuration.allowedIssuer != issuer) throw validationException;
var issUri = new Uri(token["iss"]);
if (issUri.Segments.Count < 1) throw validationException;
if (issUri.Segments[1] != token["tid"]) throw validationException;

Consulte también

Pasos siguientes