Tokens de acceso de la Plataforma de identidad de Microsoft

Los tokens de acceso permiten a los clientes llamar de forma segura a las API web protegidas. Los tokens de acceso los usan las API web para llevar a cabo la autenticación y la 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 cómo se configura la API que acepta el token.

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 pueden ser tokens cifrados, JWT o tokens especiales tipo JWT que no se validarán.

Los clientes deben tratar los tokens de acceso como cadenas opacas, ya que el contenido del token está destinado únicamente a la API. Para fines únicamente de validación y depuración, los desarrolladores pueden decodificar los token JWT mediante un sitio como jwt.ms. Es posible que los tokens recibidos para una API de Microsoft no siempre sean JWT y que no siempre se puedan descodificar.

Para detalles sobre lo que hay dentro del token de acceso, los clientes deben usar los datos de respuesta del token que se devuelven con el token de acceso al cliente. 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 que solo usan Azure AD. En el ejemplo siguiente se muestra un token v1.0 (este ejemplo de token no se validará porque las claves han girado antes de la publicación y se ha eliminado la información personal):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd
    
  • v2.0 para aplicaciones que admiten cuentas de consumidor. En el ejemplo siguiente se muestra un token v1.0 (este ejemplo de token no se validará porque las claves han girado antes de la publicación y se ha eliminado la información personal):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
    

La versión se puede establecer para las aplicaciones proporcionando el valor adecuado a la configuración 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

Hay dos partes que participan en una solicitud de token de acceso: el cliente, que es quien solicita el token, y el recurso (la API web) que acepta el token. La notificación aud de un token indica el recurso al que está dirigido el token (su público). 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 (no están relacionados). Cuando accessTokenAcceptedVersion se establece en 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.

Notificaciones de tokens de acceso

Los tokens JWT se dividen en tres partes:

  • Encabezado: proporciona información sobre cómo validar el token incluida la información sobre el tipo de token y cómo fue 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). Las notificaciones utilizadas para la validación de los token de acceso siempre están presentes.

Algunas notificaciones se usan para ayudar a la Plataforma de identidad de Microsoft a reutilizar los tokens seguros. En la descripción se indica que estas notificaciones no están destinadas al consumo público, marcadas como Opaque. 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 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 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
aud Cadena, un URI de identificador de aplicación o GUID Identifica la audiencia prevista del token. La API debe validar este valor y rechazar el token si el valor no coincide. 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.
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 Azure AD en el que se autenticó al usuario. 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. Si la notificación no está presente, 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 de Azure AD), 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 La notificación "nbf" (no antes de) identifica la hora antes de la cual no debe 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 debe ser aceptado para su procesamiento. Un recurso también puede rechazar el token antes de esta hora. El rechazo puede producirse cuando se requiere un cambio en la autenticación o se detecta una revocación de tokens.
aio Cadena opaca Una notificación interna usada por Azure AD 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 cómo se autenticó el firmante 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 Azure AD.
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 Azure AD.
appidacr Cadena, un 0, 1 o 2 solo presente en tokens v1.0 Indica cómo se autenticó el cliente. Para un cliente público, el valor es 0. Si se usan el identificador y el secreto de cliente, el valor es 1. Si 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 cómo se autenticó el cliente. Para un cliente público, el valor es 0. Si se usan el identificador y el secreto de cliente, el valor es 1. Si 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. El valor es mutable y podría cambiar en el tiempo. Puesto que es mutable, este valor no debe usarse para tomar decisiones de autorización. Sin embargo, este valor 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.
name String Proporciona un valor en lenguaje natural que identifica al firmante del token. No se garantiza que el valor sea único, es mutable y se usa solo con fines de visualización. El ámbito profile es necesario para recibir esta notificació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. 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. Solo se incluye para los tokens de usuario.
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. Para los tokens de aplicaciones, este conjunto de permisos se usa durante el flujo de credenciales de cliente (v1.0 y v2.0) en lugar de los ámbitos de usuario. Para los tokens de usuario, este conjunto de valores se rellena con los roles a los que se ha asignado el usuario en la aplicación de destino.
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 Azure AD. Esta notificación se configura por aplicación, a través de la propiedad groupMembershipClaims del manifiesto de aplicación. Es necesario establecerlo 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.
groups Matriz JSON de identificadores GUID Proporciona identificadores de objeto que representan la pertenencia al grupo del firmante. Estos valores son únicos y se pueden usar para administrar el acceso, como exigir la autorización para tener acceso a un recurso. Los grupos incluidos en la notificación de grupos se configuran por aplicación mediante la propiedad groupMembershipClaims del manifiesto de 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, Azure AD 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.
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 Para las solicitudes de tokens que no tengan limitación de longitud (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" }
sub String Entidad de seguridad sobre la que el token declara información como, por ejemplo, el usuario de una aplicación. Este valor es inmutable y no se puede reasignar ni volver a usar. Se puede usar para realizar comprobaciones de autorización de forma segura, por ejemplo, cuando el token se usa para acceder a un recurso, y se puede usar como clave en tablas de base de datos. Dado que el firmante siempre está presente en los tokens que emite Azure AD, use este valor en un sistema de autorización de propósito general. El asunto es, sin embargo, un identificador en pares que es ú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. Dos valores distintos pueden ser o no deseables dependiendo 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).
oid Cadena, un identificador GUID El identificador inmutable del solicitante, que es el usuario o la entidad de seguridad de servicio cuya identidad se ha comprobado. También se puede usar para realizar comprobaciones de autorización de forma segura y como clave en tablas de base de datos. 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, se requiere el ámbito profile para recibir esta notificación para usuarios. Si existe un único usuario en varios arrendatarios, el usuario contiene un identificador de objeto diferente en cada arrendatario. Las cuentas se consideran diferentes, aunque el usuario inicie sesión en cada cuenta con las mismas credenciales.
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.
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. 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.
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.

Notificación de grupos por encima del límite

Azure AD 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), Azure AD 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.

Notificaciones básicas de la versión 1.0

Las siguientes notificaciones se incluyen en los tokens de la versión 1.0 si corresponde, pero no se incluyen en los tokens de la versión 2.0 de forma 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 a donde se envían los usuarios para restablecer la contraseña.
in_corp boolean Indica si el cliente ha iniciado sesión desde la red corporativa. En caso contrario, la notificación no se incluye.
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 debe utilizarse 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 si la autenticación la ha realizado un token JWT autofirmado con un certificado X509 de propiedad del servicio.
otp Código de acceso de un solo uso que utiliza un correo electrónico o un mensaje de texto.
fed Se ha utilizado una aserción de autenticación federada (por ejemplo, JWT o SAML).
wia Autenticación integrada de Windows
mfa Se utilizó la autenticación multifactor. Cuando esta notificación esté presente, se incluirán los otros métodos de autenticación.
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 No se realizó ninguna autenticación.

Vigencia del token de acceso

La duración predeterminada de un token de acceso es variable. Cuando se emite, a la duración predeterminada de un token de acceso se le asigna un valor aleatorio que oscila entre 60 y 90 minutos (75 minutos de media). 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 Azure AD.

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.

Puede ajustar 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 forma silenciosa o interactiva). Para reemplazar la variación predeterminada de la vigencia del token de acceso pueden establecer una vigencia de token de acceso predeterminada estática mediante Vigencia de token configurable (CTL).

La variación predeterminada de la vigencia del token se aplica a las organizaciones que tienen la Evaluación continua de acceso (CAE) habilitada. Se aplica la variación de duración 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. El intervalo de inicio de sesión real se produce en algún punto entre 1 hora y 2,5 horas, ya que el token se emite con una vigencia que oscila entre 60 y 90 minutos (debido a la variación de la vigencia del token).

Si un usuario con un token con una vigencia de una hora realiza un inicio de sesión interactivo a los 59 minutos (justo antes de que se supere la frecuencia de inicio de sesión), no habrá ningún mensaje de solicitud de credenciales porque el inicio de sesión está por debajo del umbral de SIF. Si se emite un nuevo token con 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. Cuando se intenta realizar una renovación silenciosa de la vigencia del token de 90 minutos, Azure AD requiere una solicitud de credenciales porque la longitud total de la sesión ha superado el valor de 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 su notificación aud.
  • Las aplicaciones web confidenciales como ASP.NET Core deben validar los tokens de identificador que se les envían a través del explorador del usuario en el flujo híbrido, antes de permitir el acceso a los datos de un usuario o de establecer una sesión.

Si no se aplica ninguno de los escenarios anteriores, la aplicación no se beneficiará de la validación del token y puede suponer un riesgo de seguridad y confiabilidad si se toman decisiones en función de la validez del token. Los clientes públicos como aplicaciones nativas o de página única no se benefician de la validación de los tokens porque la aplicación se comunica directamente con el IDP, donde la protección SSL garantiza que los tokens son válidos.

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, los tokens para Microsoft Graph no se validarán 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. Por ejemplo, la versión independiente del inquilino del documento se encuentra en https://login.microsoftonline.com/common/.well-known/openid-configuration.

El middleware de Azure AD 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 de Azure AD, consulte las bibliotecas de autenticación.

Validación de la firma

Un JWT contiene tres segmentos, que están separados por el carácter . . El primer segmento se conoce como el encabezado, el segundo como el cuerpo y el tercero como la firma. El segmento de firma se puede utilizar para validar la autenticidad del token con el fin de que la aplicación pueda confiar en él.

Los tokens emitidos por Azure AD se firman 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, Azure AD puede firmar un token de identificador mediante cualquiera de un determinado conjunto de pares de claves pública y privada. Azure AD rota los posibles conjuntos de claves de forma periódica, por lo que su aplicación debería estar escrita para manejar esos cambios de clave automáticamente. Una frecuencia razonable para comprobar las actualizaciones de las claves públicas usadas por Azure AD 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. El formato JWK se describe en RFC 7517. 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 de usar la característica de asignación de notificaciones, anexe un parámetro de consulta appid que contenga el identificador de la aplicación con el fin de obtener un elemento jwks_uri que apunte a la información de la clave de firma de la aplicación, que debe usarse la para la validación. Por ejemplo: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contiene el elemento jwks_uri de https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Autorización basada en notificaciones

La lógica de negocios de la aplicación dicta la autorización basada en notificaciones. A continuación se indican algunos métodos de autorización.

Validar el token

Utilice la notificación aud para asegurarse de que el usuario designado llame a la aplicación. Si el identificador del recurso no está en la notificación aud, recházelo.

Validación del permiso de usuario

Utilice las notificaciones roles y wids para validar que el usuario tiene autorización para llamar a la API. Por ejemplo, es posible que un administrador tenga permiso para escribir en la API, pero no un usuario normal. Compruebe que el objeto tid de dentro del token coincide con el identificador de inquilino usado para almacenar los datos en la API.

Cuando un usuario almacena datos en la API desde un inquilino, debe iniciar sesión de nuevo en ese inquilino para acceder a los datos. Nunca permita que se acceda a los datos de un inquilino desde otro inquilino.

Utilice la notificación amr para comprobar que el usuario ha realizado la autenticación multifactor. La aplicación de MFA se realiza mediante el acceso condicional. Si se ha solicitado las notificaciones roles o groups en el token de acceso, compruebe que el usuario está en el grupo al que se permite realizar esta acción.

Para los tokens recuperados utilizando el flujo implícito, consulte Microsoft Graph para estos datos, ya que a menudo son demasiado grandes para adaptarse al token.

No use valores de notificación email o upn para determinar si el usuario de token de acceso debe tener acceso a los datos. Los valores de notificación mutables como estos pueden cambiar con el tiempo, lo que los hace inseguros y poco fiables para la autorización.

Use los valores de notificación inmutables tid y sub o oid como una clave combinada para identificar de forma inequívoca los datos de la API y para determinar si a un usuario debe concedérsele acceso a esos datos.

  • Bien: tid + sub
  • Mejor: tid + oid - el oid es coherente entre las aplicaciones, por lo que un ecosistema de aplicaciones puede auditar el acceso de los usuarios a los datos.

No use identificadores mutables y leíbles por humanos como email o upn para identificar datos de forma inequívoca.

Validación de información de inicio de sesión de aplicación

  • Utilice la notificación scp para validar que se concedió al usuario permiso a la aplicación que realiza la llamada para llamar a la API.
  • Asegúrese de que el cliente que realiza la llamada puede llamar a la API mediante la notificación appid (para tokens v1.0) o la notificación azp (para tokens v2.0).
    • Solo tiene que validar estas notificaciones (appid, azp) si desea restringir la llamada a la API web solo mediante aplicaciones predeterminadas (por ejemplo, aplicaciones de línea de negocio o API web a las que llaman front-end conocidos). Las API diseñadas para permitir el acceso desde cualquier aplicación de llamada no necesitan validar estas notificaciones.

Tokens de usuario y de aplicación

Una aplicación puede recibir tokens para usuario o directamente desde una aplicación mediante el flujo de credenciales de cliente. Estos tokens de solo aplicación indican que esta llamada proviene de una aplicación y no tiene un usuario que la respalde. Estos tokens se usan en gran medida de la misma manera:

  • Use roles para ver los permisos que se concedieron al firmante del token.
  • Utilice oid o sub para validar que la entidad de servicio que realiza la llamada es la que se espera.

Si la aplicación necesita distinguir entre tokens de acceso de solo aplicación y tokens de acceso para los usuarios, use la notificación opcionalidtyp. Para detectar tokens de acceso de solo aplicación, agregue la notificación idtyp al campo accessToken y verifique el valor app. Los tokens de identificador y los tokens de acceso para los usuarios no tendrán incluida la notificación idtyp.

Revocación de tokens

Los tokens de actualización se pueden invalidar o revocar en cualquier momento por varios motivos. Las razones se dividen en las categorías de tiempos de espera y revocación.

Tiempos de espera de token

Cuando una empresa usa configuración de vigencia de los tokens, se puede modificar la duración de los tokens de actualización. Se espera que algunos tokens puedan quedar sin uso. Por ejemplo, el usuario no abre la aplicación durante tres meses y, a continuación, expira el token. Las aplicaciones se pueden encontrar escenarios en los que el servidor de inicio de sesión rechaza un token de actualización debido a su antigüedad.

  • MaxInactiveTime: si el token de actualización no se ha utilizado en el tiempo determinado por MaxInactiveTime, el token de actualización ya no es válido.
  • MaxSessionAge: si MaxAgeSessionMultiFactor o MaxAgeSessionSingleFactor se han establecido en un valor distinto de su valor predeterminado (Hasta que se revoca), la reautenticación es obligatoria después de que transcurra el tiempo establecido en el MaxAgeSession*. Ejemplos:
    • El inquilino tiene un valor MaxInactiveTime de cinco días y el usuario se fue de vacaciones durante una semana, por lo que Azure AD no ha visto ninguna nueva solicitud de token de usuario en siete días. La próxima vez que el usuario solicite un nuevo token, encontrará que su token de actualización se ha revocado, así que tendrá que escribir sus credenciales de nuevo.
    • Una aplicación sensible tiene un valor MaxAgeSessionSingleFactor de un día. Si un usuario inicia sesión el lunes y el martes (una vez que hayan transcurrido 25 horas), se le pedirá que se autentique de nuevo.

Revocación de tokens

El servidor puede revocar los tokens de actualización debido a un cambio en las credenciales o a una acción de administración o uso. Los tokens de actualización se encuentran en las clases de clientes confidenciales y clientes públicos.

Change Cookie basada en contraseñas Token basado en contraseñas Cookie no basada en contraseñas Token no basado en contraseñas Token de cliente confidencial
La contraseña expira Permanece activa Permanece activa Permanece activa Permanece activa Permanece activa
Contraseña cambiada por el usuario Revocada Revocada Permanece activa Permanece activa Permanece activa
Usuario realiza SSPR Revocada Revocada Permanece activa Permanece activa Permanece activa
Administrador restablece la contraseña Revocada Revocada Permanece activa Permanece activa Permanece activa
Usuario revoca sus tokens de actualización a través de PowerShell Revocada Revocada Revocada Revocada Revocada
El administrador revoca todos los tokens de actualización de un usuario a través de PowerShell Revocada Revocada Revocada Revocada Revocada
Cierre de sesión único (v 1.0 y v 2.0) en la web Revocada Permanece activa Revocada Permanece activa Permanece activa

No basado en contraseña

Un inicio de sesión no basado en contraseña es aquel en el que el usuario no escribe una contraseña para llevarlo a cabo. Entre los ejemplos de inicio de sesión no basado en contraseña están:

  • Uso del reconocimiento facial en Windows Hello
  • Clave FIDO2
  • SMS
  • Voz
  • PIN

Consulte Tokens de actualización principales para obtener más detalles sobre estos tokens.

Pasos siguientes