Referencia de notificaciones de tokens de identificador

Artículo
10/25/2023

Los tokens de identificador son tokens web JSON (JWT). Los token de identificador v1.0 y v2.0 presentan diferencias en la información que contienen. La versión se basa en el punto de conexión desde donde se solicitó. Aunque es probable que las aplicaciones existentes utilicen el punto de conexión de Azure AD v1.0, las nuevas aplicaciones deben usar el punto de conexión v2.0.

v1.0: https://login.microsoftonline.com/common/oauth2/authorize
v2.0: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Todas las notificaciones JWT que se enumeran en las siguientes secciones aparecen en los tokens v1.0 y v2.0, a menos que se indique lo contrario. Los tokens de identificador constan de un encabezado, una carga útil y una firma. Puede usar el encabezado y la firma para comprobar la autenticidad del token, mientras que la carga útil contiene la información sobre el usuario solicitado por el cliente.

Notificaciones de encabezado

En la tabla siguiente se muestran las notificaciones de encabezado presentes en los tokens de identificador.

Notificación	Formato	Descripción
`typ`	Cadena: siempre "JWT"	Indica que se trata de un token JWT.
`alg`	String	Indica el algoritmo que se usó para firmar el token. Por ejemplo: "RS256"
`kid`	String	Especifica la huella digital de la clave pública que se puede usar para validar la firma de este token. Se emite en los tokens de identificador de las versiones 1.0 y 2.0.
`x5t`	String	Funciona igual (en uso y valor) que `kid`. `x5t` es una notificación heredada que se emite solo en los tokens de identificador de la versión 1.0 con fines de compatibilidad.

Notificaciones de carga

En la tabla siguiente se muestran las notificaciones que se encuentran en la mayoría de los tokens de identificador de forma predeterminada (excepto que se indique de otro modo). Sin embargo, su aplicación puede usar notificaciones opcionales para solicitar notificaciones adicionales en el token de identificador. Las notificaciones opcionales pueden ir desde la notificación groups hasta información sobre el nombre del usuario.

Notificación	Formato	Descripción
`aud`	Cadena, GUID de identificador de aplicación	Identifica al destinatario previsto del token. En los `id_tokens`, la audiencia es el identificador de aplicación de la aplicación, asignado a la aplicación en Azure Portal. Este valor debe validarse. El token debe rechazarse si no coincide con el identificador de la aplicación.
`iss`	Cadena, URI de emisor	Identifica al emisor o "servidor de autorización" que construye y devuelve el token. También identifica al inquilino para el que se autenticó el usuario. Si el token fue emitido por el punto de conexión de la versión 2.0, el identificador URI finaliza con `/v2.0`. El GUID que indica que el usuario es un usuario consumidor desde una cuenta de Microsoft es `9188040d-6c67-4c5b-b112-36a304b66dad`. La aplicación debe usar la parte del GUID de la notificación para restringir el conjunto de inquilinos que pueden iniciar sesión en la aplicación, si procede.
`iat`	entero, una marca de tiempo de UNIX	Indica cuándo se produjo la autenticación del token.
`idp`	Cadena, normalmente un identificador URI de STS	Registra el proveedor de identidades que autenticó al firmante del token. Este valor es idéntico al valor de la notificación del emisor, a menos que la cuenta de usuario no esté en el mismo inquilino que el emisor: los invitados, por ejemplo. Si la notificación no está presente, significa que el valor de `iss` se puede usar en su lugar. Para las cuentas personales que se usan en un contexto de la organización (por ejemplo, una cuenta personal invitada a un inquilino), la notificación `idp` puede ser "live.com" o un identificador URI de STS que contenga al inquilino de la cuenta Microsoft `9188040d-6c67-4c5b-b112-36a304b66dad`.
`nbf`	entero, una marca de tiempo de Unix	Identifica la hora antes de la cual no puede ser aceptado el token JWT para su procesamiento.
`exp`	entero, una marca de tiempo de Unix	Identifica la hora de expiración en la que o después de la que el token JWT no puede ser aceptado para su procesamiento. En determinadas circunstancias, un recurso puede rechazar el token antes de este tiempo. Por ejemplo, si se requiere un cambio en la autenticación o se detecta una revocación de tokens.
`c_hash`	String	El hash de código se incluye en los tokens de identificador solo cuando se emite el token de identificador con un código de autorización de OAuth 2.0. Se puede usar para validar la autenticidad de un código de autorización. Para comprender cómo realizar esta validación, consulte la especificación OpenID Connect. Esta notificación no se devuelve en tokens de identificador desde el punto de conexión de token.
`at_hash`	String	El hash de token de acceso se incluye en los tokens de identificador solo cuando el token de identificador se emite desde el punto de conexión `/authorize` con un token de acceso de OAuth 2.0. Se puede usar para validar la autenticidad de un token de acceso. Para comprender cómo realizar esta validación, consulte la especificación OpenID Connect. Esta notificación no se devuelve en tokens de identificador desde el punto de conexión de `/token`.
`aio`	Cadena opaca	Una notificación interna que se usa para registrar los datos para la reutilización de tokens. Se debe omitir.
`preferred_username`	String	El nombre de usuario principal que representa al usuario. Puede ser una dirección de correo electrónico, un número de teléfono o un nombre de usuario genérico sin un formato especificado. Su valor es mutable y podría cambiar en el tiempo. Puesto que es mutable, este valor no puede usarse para tomar decisiones de autorización. Se puede usar para las sugerencias de nombre de usuario y en la interfaz de usuario legible como nombre de usuario. El ámbito `profile` es necesario para recibir esta notificación. Presente solo en los tokens v2.0.
`email`	String	Está presente de manera predeterminada para las cuentas de invitado que tengan una dirección de correo electrónico. La aplicación puede solicitar la notificación de correo electrónico para los usuarios administrados (del mismo inquilino que el recurso) mediante la notificación opcional `email`. No se garantiza que este valor sea correcto y es mutable a lo largo del tiempo. Nunca lo use para la autorización o para guardar datos para un usuario. Si necesita una dirección de correo electrónico direccionable en la aplicación, solicite estos datos directamente al usuario, mediante esta notificación como sugerencia o rellene previamente la experiencia de usuario. En el punto de conexión v2.0, la aplicación también puede solicitar el ámbito `email` de OpenID Connect. No es necesario que solicite ambos, la notificación opcional y el ámbito para obtener la notificación.
`name`	String	La notificación `name` proporciona un valor en lenguaje natural que identifica al firmante del token. No se garantiza que el valor sea único, se puede modificar y solo debe usarse con fines de visualización. El ámbito `profile` es necesario para recibir esta notificación.
`nonce`	String	El valor nonce coincide con el parámetro incluido en la solicitud authorize original al IDP. Si no coincide, la aplicación debe rechazar el token.
`oid`	Cadena, un identificador GUID	El identificador inmutable de un objeto, en este caso, una cuenta de usuario. Este identificador identifica de forma única el usuario entre aplicaciones: dos aplicaciones diferentes que inician sesión con el mismo usuario reciben el mismo valor en la notificación `oid`. Microsoft Graph devuelve este identificador como la propiedad `id` de una cuenta de usuario determinada. Dado que la notificación `oid` permite que varias aplicaciones pongan en correlación a los usuarios, se requiere el ámbito `profile` para recibir esta notificación. Si un usuario existe en varios inquilinos, el usuario contiene un identificador de objeto distinto en cada inquilino: se consideran cuentas diferentes, incluso si el usuario inicia sesión en todas las cuentas con las mismas credenciales. La notificación `oid` es un GUID y no se puede volver a usar.
`roles`	Matriz de cadenas	El conjunto de roles que se asignaron al usuario que ha iniciado sesión.
`rh`	Cadena opaca	Una notificación interna que se usa para volver a validar los tokens. Se debe omitir.
`sub`	String	Asunto de la información en el token. Por ejemplo, el usuario de una aplicación. Este valor es inmutable y no se puede reasignar ni volver a usar. El firmante es un identificador en pares y es único para un identificador de aplicación. Si un usuario inicia sesión en dos aplicaciones diferentes con dos identificadores de cliente diferentes, esas aplicaciones reciben dos valores diferentes para la notificación de firmante. Es posible que desee o no dos valores en función de los requisitos de arquitectura y privacidad.
`tid`	Cadena, un identificador GUID	Representa el inquilino en el que el usuario inicia sesión. En el caso de las cuentas profesionales y educativas, el GUID es el identificador de inquilino inmutable de la organización en la que el usuario inicia sesión. Para los inicios de sesión en el inquilino de la cuenta Microsoft personal (servicios como Xbox, Outlook o Teams for Life), el valor es `9188040d-6c67-4c5b-b112-36a304b66dad`.
`unique_name`	String	Solo está presente en los tokens de la versión 1.0. Proporciona un valor en lenguaje natural que identifica al firmante del token. No se asegura que este valor sea único en un inquilino y se debe usar solo con fines de visualización.
`uti`	String	Notificación de identificador de token, equivalente a `jti` en la especificación JWT. Identificador único por token que distingue mayúsculas de minúsculas.
`ver`	Cadena, 1.0 o 2.0	Indica la versión del token de identificador.
`hasgroups`	Boolean	Si existe, siempre es true, lo cual indica que el usuario está en al menos un grupo. Indica que el cliente debe utilizar Microsoft Graph API para determinar los grupos del usuario (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`).
`groups:src1`	Objeto JSON	Para las solicitudes de tokens que no tengan la longitud limitada (consulte `hasgroups`), pero que todavía sean demasiado grandes para el token, se incluye un vínculo a la lista completa de grupos del usuario. Para métodos JWT como una notificación distribuida, para SAML como una nueva notificación en lugar de la notificación `groups`. Valor de JWT de ejemplo: `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` Para más información, consulte Notificación de grupos por encima del límite.

Usar notificaciones para identificar de forma fiable a un usuario

A la hora de identificar a un usuario, es fundamental utilizar información que permanezca constante y única a lo largo del tiempo. Las aplicaciones heredadas a veces usan campos, como la dirección de correo electrónico, un número de teléfono o el UPN. Todos estos campos pueden cambiar con el tiempo y también se pueden reutilizar. Por ejemplo, si un empleado cambia de nombre, o a un empleado se le asigna una dirección de correo electrónico que coincide con la de un empleado anterior que ya no está presente. La aplicación no debe usar datos legibles para identificar a un usuario; legible normalmente significa que alguien puede leerlo y querer cambiarlo. En su lugar, use las notificaciones proporcionadas por el estándar OIDC o las notificaciones de extensión proporcionadas por Microsoft: las notificaciones sub y oid.

Para almacenar correctamente la información por usuario, use sub o oid solo (que son únicos, como los GUID), y use tid para el enrutamiento o el particionamiento si es necesario. Si necesita compartir datos entre servicios, oid y tid es lo mejor cuando todas las aplicaciones obtienen las mismas notificaciones oid y tid para un usuario que actúa en un inquilino. La notificación sub es un valor de pares único. El valor se basa en una combinación del destinatario del token, el inquilino y el usuario. Dos aplicaciones que solicitan tokens de identificador para un usuario recibirán diferentes notificaciones sub, pero las mismas notificaciones oid para ese usuario.

Nota

No utilice la notificación idp para almacenar información sobre un usuario en un intento de correlacionar a los usuarios entre inquilinos. No funcionará, ya que las notificaciones oid y sub para un usuario cambian entre los inquilinos, por diseño, para asegurarse de que las aplicaciones no puedan realizar el seguimiento de los usuarios entre inquilinos.

Los escenarios de invitado, en los que un usuario se hospeda en un inquilino y se autentica en otro, deben tratar al usuario como si fuera un usuario completamente nuevo en el servicio. Los documentos y privilegios de un inquilino no deben aplicarse en otro inquilino. Esta restricción es importante para impedir la pérdida accidental de datos entre inquilinos y para el cumplimiento de los ciclos de vida de los datos. Si se expulsa a un invitado de un inquilino, también se debe eliminar su acceso a los datos que creó en dicho inquilino.

Notificación de grupos por encima del límite

Para garantizar que el tamaño del token no supera los límites de tamaño del encabezado HTTP, el número de identificadores de objeto que se incluyen en la notificación groups está limitado. Si un usuario es miembro de más grupos que el límite de uso por encima del límite (150 para los tokens SAML, 200 para los tokens JWT), la notificación de grupos no se incluye en el token. En su lugar, incluye una demanda de uso por encima del límite en el token que indica a la aplicación que consulte la Microsoft Graph API para recuperar la pertenencia a grupos del usuario.

{
  ...
  "_claim_names": {
   "groups": "src1"
    },
    {
  "_claim_sources": {
    "src1": {
        "endpoint":"[Url to get this user's group membership from]"
        }
       }
     }
  ...
}

Pasos siguientes

Más información sobre los tokens de ID usados en Microsoft Entra ID.

Compartir vía