Referencia de notificaciones de token de acceso

  • Artículo

Los tokens de acceso son tokens web JSON (JWT). Los tokens JWT contienen las siguientes partes:

  • Encabezado: proporciona información sobre cómo validar el token, incluida la información sobre el tipo de token y su método de firmado.
  • Carga: contiene todos los datos importantes sobre el usuario o la aplicación que está intentando llamar al servicio.
  • Firma: es la materia prima utilizada para validar el token.

Cada fragmento se separa por un punto (.) y se codifica por separado en Base64.

Las notificaciones están presentes solo si existe un valor que las rellene. La aplicación no debería depender de la presencia de una notificación. Los ejemplos incluyen pwd_exp (no todos los inquilinos requieren que las contraseñas expiren) o family_name (los flujos de credenciales de cliente representan a las aplicaciones que no tienen nombres). El token de acceso siempre contendrá notificaciones suficientes para la evaluación de acceso.

La Plataforma de identidad de Microsoft utiliza algunas notificaciones para proteger tokens para volver a utilizarlos. La descripción de Opaque marca estas notificaciones como no admisibles para el consumo público. Estas notificaciones pueden o no aparecer en un token, y pueden agregarse otras nuevas sin previo aviso.

Notificaciones de encabezado

Notificación Formato Descripción
typ Cadena: siempre JWT Indica que el token es un token JWT.
alg String Indica el algoritmo utilizado para firmar el token, por ejemplo, RS256.
kid String Especifica la huella digital de la clave pública utilizada para validar la firma de este token. Se emite en ambos tokens de acceso de las versiones 1.0 y 2.0.
x5t String Funciona igual (en uso y valor) que kid. x5t es una notificación heredada emitida solo en los tokens de acceso de la versión 1.0 para fines de compatibilidad.

Notificaciones de carga

Notificación Formato Descripción Consideraciones sobre la autorización
acrs Matriz JSON de cadenas Indica los identificadores de contexto de autenticación de las operaciones que el portador puede realizar. Los id. de contexto de autenticación se pueden usar para desencadenar una demanda de autenticación paso a paso desde la aplicación y los servicios. A menudo se usa junto con la notificación xms_cc.
aud Cadena, un URI de identificador de aplicación o GUID Identifica la audiencia prevista del token. En los tokens v2.0, este valor siempre es el identificador de cliente de la API. En los tokens v1.0, puede ser el ID del cliente o el URI del recurso utilizado en la solicitud. El valor puede depender de cómo el cliente solicitó el token. Este valor debe validarse, rechazar el token si el valor no coincide con los destinatarios.
iss Cadena, una URI de servicio de token de seguridad (STS) Identifica el servicio de token de seguridad que construye y devuelve el token, así como el inquilino de Microsoft Entra del usuario autenticado. Si el token emitido es un token v2.0 (consulte la notificación ver), el URI finaliza en /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 puede 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 corresponde.
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, como por ejemplo, los invitados. Use el valor de iss si la notificación no está presente. Para las cuentas personales que se usan en un contexto de la organización (por ejemplo, una cuenta personal invitada a un inquilino de Microsoft Entra), 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.
iat entero, una marca de tiempo de Unix Indica cuándo se produjo la autenticación de este token.
nbf entero, una marca de tiempo de Unix Especifica la hora después de la cual se puede procesar el JWT.
exp entero, una marca de tiempo de Unix Especifica la hora de expiración antes del cual el token JWT puede ser aceptado para su procesamiento. Un recurso también puede rechazar el token antes de esta hora. El rechazo puede producirse para un cambio necesario en la autenticación o cuando se revoca un token.
aio Cadena opaca Una notificación interna usada por Microsoft Entra ID para registrar los datos para la reutilización de tokens. Los recursos no deben usar esta notificación.
acr Cadena, un 0 o 1, solo presente en tokens v1.0 Un valor de 0 para la notificación "Clase de contexto de autenticación" indica que la autenticación del usuario final no cumplió con los requisitos de ISO/IEC 29115.
amr Matriz JSON de cadenas, solo presente en tokens v1.0 Identifica el método de autenticación del asunto del token.
appid Cadena, un GUID, solo presente en tokens v1.0 El identificador de aplicación del cliente mediante el token. La aplicación puede actuar por sí misma o en nombre de un usuario. Normalmente, el id. de aplicación representa un objeto de aplicación, pero también puede representar un objeto de entidad de servicio en Microsoft Entra ID. appid se puede usar en decisiones de autorización.
azp Cadena, un GUID, solo presente en tokens v2.0 Un reemplazo para appid. El identificador de aplicación del cliente mediante el token. La aplicación puede actuar por sí misma o en nombre de un usuario. Normalmente, el id. de aplicación representa un objeto de aplicación, pero también puede representar un objeto de entidad de servicio en Microsoft Entra ID. azp se puede usar en decisiones de autorización.
appidacr Cadena, un 0, 1 o 2 solo presente en tokens v1.0 Indica el método de autenticación del cliente. Para un cliente público, el valor es 0. Cuando se usa el id. de cliente y el secreto de cliente, el valor es 1. Cuando se usa un certificado de cliente para la autenticación, el valor es 2.
azpacr Cadena, un 0, 1 o 2, solo presente en tokens v2.0 Un reemplazo para appidacr. Indica el método de autenticación del cliente. Para un cliente público, el valor es 0. Cuando se usa el id. de cliente y el secreto de cliente, el valor es 1. Cuando se usa un certificado de cliente para la autenticación, el valor es 2.
preferred_username Cadena solo presente en los tokens de la versión 2.0. El nombre de usuario principal que representa al usuario. El valor 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. Use el valor para las sugerencias de nombre de usuario y en la interfaz de usuario legible como nombre de usuario. Para recibir esta notificación, use el ámbito de profile. Puesto que este valor es mutable, no lo use para tomar decisiones de autorización.
name String Proporciona un valor en lenguaje natural que identifica al firmante del token. El valor puede variar, es mutable y solo tiene fines de visualización. Para recibir esta notificación, use el ámbito de profile. No use este valor para tomar decisiones de autorización.
scp Cadena, una lista de ámbitos separada por espacios. El conjunto de ámbitos expuestos por la aplicación para los cuales la aplicación cliente ha solicitado (y recibido) consentimiento. Solo se incluye para los tokens de usuario. Su aplicación debe comprobar que estos ámbitos son válidos y están expuestos por la aplicación, y tomar decisiones de autorización basadas en el valor de estos ámbitos.
roles Matriz de cadenas, una lista de permisos El conjunto de permisos expuestos por la aplicación para la que la aplicación o el usuario solicitante ha recibido permiso para llamar. El flujo de credenciales de cliente usa este conjunto de permisos en lugar de ámbitos de usuario para tokens de aplicación. Para los tokens de usuario, este conjunto de valores incluye los roles asignados del usuario en la aplicación de destino. Estos valores se pueden usar para administrar el acceso, como exigir la autorización para tener acceso a un recurso.
wids Matriz de GUID RoleTemplateID Indica los roles de todos los inquilinos asignados a este usuario, de la sección de roles presentes en Roles integrados de Microsoft Entra. La propiedad groupMembershipClaims del manifiesto de aplicación configura esta notificación por aplicación. Establezca la notificación en All o DirectoryRole. Es posible que no esté presente en los tokens obtenidos a través del flujo implícito por motivos de longitud del token. Estos valores se pueden usar para administrar el acceso, como exigir la autorización para tener acceso a un recurso.
groups Matriz JSON de identificadores GUID Proporciona identificadores de objeto que representan la pertenencia al grupo del firmante. La propiedad groupMembershipClaims del manifiesto de aplicación configura la notificación de grupos por aplicación. Un valor null excluirá todos los grupos, un valor de SecurityGroup incluirá únicamente la pertenencia a grupos de seguridad de Active Directory y un valor de All incluirá grupos de seguridad y listas de distribución de Microsoft 365.

Consulte la notificación hasgroups para más información sobre el uso de la notificación groups con la concesión implícita. Para otros flujos, si el número de grupos en los que está el usuario supera los 150 para SAML y 200 para JWT, Microsoft Entra ID agrega una notificación de uso por encima del límite a los orígenes de notificaciones. Los orígenes de la notificación apuntan al punto de conexión de Microsoft Graph que contiene la lista de grupos para el usuario.		 Estos valores se pueden usar para administrar el acceso, como exigir la autorización para tener acceso a un recurso.
hasgroups Boolean Si existe, siempre es true, lo cual indica si el usuario está en al menos un grupo. Se usa en lugar de la notificación groups para métodos JWT en flujos de concesión implícita si las notificaciones completas de los grupos amplían el fragmento URI por encima de los límites de longitud de la URL (actualmente seis o más grupos). 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 Incluye un vínculo a la lista de grupos completos para el usuario cuando las solicitudes de token son demasiado grandes para el token. 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" }
sub String La entidad de seguridad asociada al token. Por ejemplo, el usuario de una aplicación. Este valor es inmutable, no lo vuelva a asignar ni reutilizar. El firmante es un identificador en pares único para un identificador de aplicación determinado. 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. El uso de los dos valores diferentes depende de los requisitos de arquitectura y privacidad. Vea también la notificación oid (que sigue siendo la misma en las todas aplicaciones en un inquilino). Este valor se puede usar para realizar comprobaciones de autorización, por ejemplo, cuando el token se usa para acceder a un recurso, y se puede usar como clave en tablas de base de datos.
oid Cadena, un identificador GUID Identificador inmutable del solicitante, que es la identidad comprobada del usuario o la entidad de servicio. Este identificador identifica de forma única el solicitante en todas las aplicaciones. Dos aplicaciones diferentes que inician sesión con el mismo usuario recibirán el mismo valor en la notificación oid. oid puede usarse al realizar consultas en Microsoft Online Services, como Microsoft Graph. 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 las entidades de seguridad, use el ámbito profile para recibir esta notificación para los usuarios. Si existe un único usuario en varios arrendatarios, el usuario contiene un identificador de objeto diferente en cada arrendatario. Aunque el usuario inicie sesión en cada cuenta con las mismas credenciales, las cuentas son diferentes. Este valor se puede usar para realizar comprobaciones de autorización, por ejemplo, cuando el token se usa para acceder a un recurso, y se puede usar como clave en tablas de base de datos.
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. Para recibir esta notificación, la aplicación debe solicitar el ámbito profile. Este valor debe considerarse en combinación con otras notificaciones en las decisiones de autorización.
unique_name Cadena, solo presente en los tokens de la versión 1.0 Proporciona un valor en lenguaje natural que identifica al firmante del token. Este valor puede ser diferente en un inquilino y usarlo 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.
rh Cadena opaca Una notificación interna que Azure usa para volver a validar los tokens. Los recursos no deben usar esta notificación.
ver Cadena, 1.0 o 2.0 Indica la versión del token de acceso.
xms_cc Matriz JSON de cadenas Indica si la aplicación cliente que adquirió el token es capaz de controlar los desafíos de las notificaciones. A menudo se usa junto con la notificación acrs. Esta notificación se usa normalmente en escenarios de Acceso condicional y Evaluación continua de acceso. El servidor de recursos o la aplicación de servicio para la que se emite el token controla la presencia de esta notificación en un token. Un valor de cp1 en el token de acceso es la manera autoritativa de identificar que una aplicación cliente es capaz de controlar un desafío de notificaciones. Para más información, consulte Desafíos de notificaciones, solicitudes de notificaciones y funcionalidades de cliente.

Notificación de grupos por encima del límite

Microsoft Entra ID limita el número de identificadores de objeto que incluye en la notificación de grupos para permanecer dentro del límite de tamaño del encabezado HTTP. 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 y solo 6 si se emiten a través del flujo implícito), Microsoft Entra ID no emite la notificaciones de grupos 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]"
        }   
    }
    ...
}

Use BulkCreateGroups.ps1, que se proporciona en la carpeta scripts de creación de aplicaciones, para ayudar a probar los escenarios de uso por encima del límite.

Nota:

La dirección URL devuelta será una dirección URL de Azure AD Graph (es decir, graph.windows.net). En lugar de confiar en esta dirección URL, los servicios deben usar en su lugar la notificación opcional idtyp (que identifica si el token es una aplicación o un token de aplicación y usuario) para construir una dirección URL de Microsoft Graph para consultar la lista completa de grupos.

Notificaciones básicas de la versión 1.0

Los tokens de la v1.0 incluyen las siguientes notificaciones si procede, pero no los tokens de la v2.0 de manera predeterminada. Para usar estas notificaciones para la versión 2.0, la aplicación los solicita mediante notificaciones opcionales.

Notificación Formato Descripción
ipaddr String La dirección IP desde la que el usuario se autenticó.
onprem_sid Cadena, en formato de GUID En los casos en los que el usuario tiene una autenticación local, esta notificación proporciona el SID. Utilice esta notificación para la autorización en aplicaciones heredadas.
pwd_exp entero, una marca de tiempo de Unix Indica cuándo expira la contraseña del usuario.
pwd_url String Una dirección URL donde los usuarios pueden restablecer la contraseña.
in_corp boolean Indica si el cliente ha iniciado sesión desde la red corporativa.
nickname String Otro nombre para el usuario, aparte del nombre y del apellido.
family_name String Proporciona el apellido del usuario según está definido en el objeto de usuario.
given_name String Proporciona el nombre de pila o "dado" del usuario, tal como se establece en el objeto de usuario.
upn String Nombre de usuario del usuario. Puede ser un número de teléfono, una dirección de correo electrónico o una cadena sin formato. Solo use para fines de visualización y para proporcionar sugerencias de nombre de usuario en escenarios de reautenticación.

notificación amr

Las identidades pueden autenticarse de diversas maneras, que pueden ser pertinentes para la aplicación. La notificación amr es una matriz que puede contener varios elementos, como ["mfa", "rsa", "pwd"], para una autenticación que utiliza tanto una contraseña como la aplicación Autenticator.

Value Descripción
pwd Autenticación de contraseña, ya sea la contraseña de un usuario de Microsoft o el secreto de cliente de una aplicación.
rsa La autenticación se basaba en la prueba de una clave RSA, por ejemplo con la aplicación Microsoft Authenticator. Este valor también indica el uso de un JWT autofirmado con un certificado X509 propiedad del servicio en la autenticación.
otp Código de acceso de un solo uso que utiliza un correo electrónico o un mensaje de texto.
fed Indica el uso de una instrucción de aserción de autenticación federada (como JWT o SAML).
wia Autenticación integrada de Windows
mfa Indica el uso de la autenticación multifactor. Incluye los otros métodos de autenticación cuando esta notificación está presente.
ngcmfa Equivalente a mfa, que se utiliza para el aprovisionamiento de ciertos tipos de credenciales avanzadas.
wiaormfa El usuario utiliza una credencial MFA o Windows para autenticar.
none Indica que no se ha completado la autenticación.

Pasos siguientes