Referencia de notificaciones opcionales

  • Artículo

Estas notificaciones opcionales sirven para:

  • Seleccionar las notificaciones que se incluirán en los tokens para la aplicación.
  • Cambiar el comportamiento de determinadas notificaciones que la Plataforma de identidad de Microsoft devuelve en tokens.
  • Agregar notificaciones personalizadas para la aplicación y acceder a ellas.

Aunque las notificaciones opcionales se admiten en los tokens de formato de las versiones 1.0 y 2.0 y en los tokens SAML, proporcionan la mayoría de sus valores al pasar de la versión 1.0 a la 2.0. En la Plataforma de identidad de Microsoft, los tamaños de token menores se usan para garantizar el rendimiento óptimo de los clientes. Como resultado, varias notificaciones que antes se incluían en los tokens de identificación y acceso ya no aparecen en los de la versión 2.0 y deben solicitarse específicamente para cada aplicación.

Tipo de cuenta Tokens de la versión 1.0 Tokens de la versión 2.0
Cuenta personal de Microsoft N/D Compatible
Cuenta de Microsoft Entra Compatible Compatible

Conjunto de notificaciones opcionales de las versiones 1.0 y 2.0

El conjunto de notificaciones opcionales disponibles de manera predeterminada para que las usen las aplicaciones se enumera en la tabla siguiente. Puede usar datos personalizados en atributos de extensión y extensiones de directorio para agregar notificaciones opcionales para la aplicación. Cuando agrega notificaciones al token de acceso, estas se aplicarán a los tokens de acceso solicitados para la aplicación (una API web), no a las notificaciones solicitadas por la aplicación. Independientemente de cómo el cliente acceda a la API, los datos correctos están presentes en el token de acceso que se usa para autenticarse en la API.

Nota

La mayoría de estas notificaciones puede incluirse en los JWT para los tokens v1.0 y v2.0, pero no en los tokens SAML, excepto donde se indique en la columna Tipo de token. Las cuentas de consumidor admiten un subconjunto de estas notificaciones, marcadas en la columna Tipo de usuario. Muchas de las notificaciones aquí incluidas no se aplican a los usuarios consumidores (no tienen inquilino, por lo que tenant_ctry no tiene ningún valor).

En la tabla siguiente se enumeran los conjuntos de notificaciones opcionales v1.0 y v2.0.

Nombre Descripción Tipo de token Tipo de usuario Notas
acct Estado de la cuenta de los usuarios de un inquilino JWT, SAML Si el usuario es miembro del inquilino, el valor es 0. Si es un invitado, el valor es 1.
acrs Id. de contexto de autenticación JWT Microsoft Entra ID 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.
auth_time Momento de la última autenticación del usuario. JWT
ctry País o región del usuario JWT Esta notificación se devuelve si existe, y el valor del campo es un código de país o región estándar de dos letras, como FR, JP, SZ, etc.
email La dirección de correo electrónico notificada para este usuario JWT, SAML MSA, Microsoft Entra ID Si el usuario es un invitado en el inquilino, este valor se incluye de forma predeterminada. Para los usuarios administrados (aquellos dentro del inquilino), se debe solicitar a través de esta notificación opcional o, únicamente en la versión 2.0, con el ámbito OpenID. No se garantiza que este valor sea correcto y sea mutable con el tiempo: nunca lo use para la autorización o para guardar los datos de un usuario. Para obtener más información, consulte Validación de que el usuario tenga permiso para acceder a estos datos. Si está usando la notificación de correo electrónico para la autorización, se recomienda realizar una migración para pasar a una notificación más segura. 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.
fwd Dirección IP JWT Agrega la dirección original del cliente solicitante (cuando se encuentra en una red virtual).
groups Formato opcional de las notificaciones de grupo JWT, SAML La notificación groups se usa con la opción de configuración GroupMembershipClaims en el manifiesto de la aplicación, que se debe establecer también.
idtyp Tipo de token Tokens de acceso de JWT Especial: únicamente en tokens de acceso de solo aplicación El valor es app cuando el token es un token de solo aplicación. Esta notificación es la forma más precisa para que una API determine si un token es un token de aplicación o un token de usuario + aplicación.
login_hint Sugerencia de inicio de sesión JWT MSA, Microsoft Entra ID Notificación de sugerencia de inicio de sesión confiable opaca codificada en base 64. No modifique este valor. Esta notificación es el mejor valor que se puede usar para el parámetro login_hint de OAuth en todos los flujos para el inicio de sesión único. También se puede pasar entre aplicaciones para ayudar en el inicio de sesión único en modo silencioso: la aplicación A puede iniciar la sesión de un usuario, leer la notificación login_hint y, a continuación, enviar la notificación y el contexto del inquilino actual a la aplicación B en la cadena o fragmento de la cadena de consulta cuando el usuario selecciona un vínculo que le lleva a la aplicación B. Para evitar problemas de confiabilidad y condiciones de carrera, la notificación login_hintno incluye el inquilino actual del usuario y tiene como valor predeterminado el inquilino principal del usuario cuando se usa. En un escenario de invitado en el que el usuario procede de otro inquilino, se debe proporcionar un identificador de inquilino en la solicitud de inicio de sesión. y pasan lo mismo a las aplicaciones con las que se asocia. Sin embargo, esta notificación está pensada para su uso con la funcionalidad login_hint existente del SDK, como se ha expuesto.
sid Identificador de sesión que se usa para el cierre de cada sesión de usuario JWT Cuentas personales y de Microsoft Entra.
tenant_ctry País o región del inquilino de recursos JWT Igual que ctry, salvo que un administrador lo establezca en un nivel de inquilino. También debe ser un valor estándar de dos letras.
tenant_region_scope Región del inquilino de los recursos JWT
upn UserPrincipalName JWT, SAML Un identificador del usuario que se puede usar con el parámetro username_hint. No es un identificador duradero para el usuario y no debe usarse para la autorización ni para identificar de forma exclusiva la información del usuario (por ejemplo, como una clave de base de datos). En su lugar, use el id. de objeto de usuario (oid) como clave de base de datos. Para obtener más información, vea Protección de aplicaciones y API mediante la validación de notificaciones. Los usuarios que inician sesión con un id. de inicio de sesión alternativo no deben mostrar su nombre principal de usuario (UPN). En su lugar, use las siguientes notificaciones de token de identificador para mostrar el estado de inicio de sesión al usuario: preferred_username o unique_name para los tokens v1 y preferred_username para los tokens v2. Aunque esta notificación se incluye automáticamente, puede especificarla como opcional para adjuntar otras propiedades y así modificar su comportamiento para los usuarios invitados. Debe usar la notificación login_hint para el uso de login_hint: los identificadores legibles como el UPN no son de confianza.
verified_primary_email Procede del valor PrimaryAuthoritativeEmail del usuario. JWT
verified_secondary_email Procede del valor SecondaryAuthoritativeEmail del usuario. JWT
vnet Información del especificador de la red virtual JWT
xms_cc Funcionalidades del cliente JWT Microsoft Entra ID 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.
xms_edov Valor booleano que indica si se ha comprobado el propietario del dominio del correo electrónico del usuario. JWT Se considera que un correo electrónico cuenta con un dominio verificado si pertenece al inquilino donde reside la cuenta de usuario y el administrador del inquilino ha realizado la comprobación del dominio. Además, el correo electrónico debe ser de una cuenta de Microsoft (MSA), una cuenta de Google o usarse para la autenticación mediante el flujo de código de acceso de un solo uso (OTP). Las cuentas de Facebook y SAML/WS-Fed no tienen dominios comprobados. Para que esta reclamación sea devuelta en el token, es necesaria la presencia de la reclamaciónemail.
xms_pdl Ubicación de datos preferida JWT En los inquilinos multigeográficos, la ubicación de datos preferida es el código de tres letras que muestra la región geográfica en la que se encuentra el usuario. Para más información, vea la Documentación de Microsoft Entra Connect acerca de la ubicación de datos preferida.
xms_pl Idioma preferido del usuario JWT Idioma preferido del usuario, si se establece. Se origina desde su inquilino principal, en escenarios de acceso de invitado. Con formato LL-CC ("en-us").
xms_tpl Idioma preferido del inquilino JWT Idioma preferido del inquilino de recursos, si se establece. Con formato LL ("en").
ztdid Identificador de implementación sin interacción JWT Identidad del dispositivo usada para Windows AutoPilot.

Advertencia

No use nunca valores de notificación email y upn para almacenar o determinar si el usuario de un 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.

Conjunto de notificaciones opcionales específicas de la versión 2.0

Estas notificaciones siempre se incluyen en los tokens de la versión 1.0, pero no en los tokens de la versión 2.0, a menos que se solicite. Estas notificaciones solo son válidas en los JWT (tokens de identificación y de acceso).

Notificación de JWT Nombre Descripción Notas
ipaddr Dirección IP Dirección IP del cliente desde el que se inició sesión.
onprem_sid Identificador de seguridad local
pwd_exp Tiempo de expiración de la contraseña Número de segundos después del tiempo en la notificación de iat en los que expira la contraseña. Esta notificación solo se incluye cuando la contraseña expira pronto (según lo definido en "días de notificación" en la directiva de contraseñas).
pwd_url Cambiar dirección URL de contraseña Dirección URL que el usuario puede visitar para cambiar la contraseña. Esta notificación solo se incluye cuando la contraseña expira pronto (según lo definido en "días de notificación" en la directiva de contraseñas).
in_corp Dentro de red corporativa Indica si el cliente ha iniciado sesión desde la red corporativa. En caso contrario, la notificación no se incluye. En función de la configuración de las IP de confianza de MFA.
family_name Apellido Proporciona el apellido del usuario según está definido en el objeto de usuario. Por ejemplo, "family_name":"Miller". Se admite en MSA y Microsoft Entra ID. Requiere el ámbito profile.
given_name Nombre Proporciona el nombre de pila o "dado" del usuario, tal como se establece en el objeto de usuario. Por ejemplo, "given_name": "Frank". Se admite en MSA y Microsoft Entra ID. Requiere el ámbito profile.
upn Nombre principal del usuario Un identificador del usuario que se puede usar con el parámetro username_hint. No es un identificador duradero para el usuario y no debe usarse para la autorización ni para identificar de forma exclusiva la información del usuario (por ejemplo, como una clave de base de datos). Para obtener más información, vea Protección de aplicaciones y API mediante la validación de notificaciones. En su lugar, use el id. de objeto de usuario (oid) como clave de base de datos. Los usuarios que inician sesión con un id. de inicio de sesión alternativo no deben mostrar su nombre principal de usuario (UPN). En su lugar, use la notificación preferred_username para mostrar el estado de inicio de sesión al usuario. Requiere el ámbito profile.

Conjunto de notificaciones opcionales específicas de la versión 1.0

Algunas de las mejoras del formato de token de la versión 2 están disponibles para las aplicaciones que usan el formato de token de la 1, ya que ayudan a mejorar la seguridad y la confiabilidad. Estas mejoras solo se aplican a los token de JWT, no a los de SAML.

Notificación de JWT Nombre Descripción Notas
aud Público Siempre está presente en JWT, pero en los tokens de acceso v1 se puede emitir de varias maneras: cualquier URI de appID, con o sin una barra diagonal final, así como el identificador de cliente del recurso. Puede resultar difícil de codificar con esta aleatoriedad al realizar la validación de tokens. Use additionalProperties para esta notificación a fin de asegurarse de que siempre se establezca en el identificador del cliente del recurso en los tokens de acceso v1. Solo tokens de acceso JWT de la versión 1
preferred_username Nombre de usuario preferido Proporciona la notificación de nombre de usuario preferido en los tokens de la versión 1. Esta notificación facilita que las aplicaciones proporcionen sugerencias de nombre de usuario e indiquen nombres para mostrar legibles, independientemente de su tipo de token. Se recomienda usar esta notificación opcional en lugar de upn o unique_name. Tokens de identificador y tokens de acceso de la versión 1

additionalProperties de notificaciones opcionales

Algunas notificaciones opcionales se pueden configurar para cambiar la manera de devolver la notificación. Estas additionalProperties se utilizan principalmente para ayudar a la migración de aplicaciones locales con expectativas de datos diferentes. Por ejemplo, include_externally_authenticated_upn_without_hash ayuda con los clientes que no pueden admitir almohadillas (#) en el UPN.

Nombre de propiedad Nombre additionalProperty Descripción
upn Puede usarse en respuestas SAML y JWT y para los token v1.0 y v2.0.
include_externally_authenticated_upn Incluye el nombre principal de usuario invitado tal como se almacenó en el inquilino de recursos. Por ejemplo, foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Igual que se ha indicado antes, excepto que las marcas hash (#) se reemplazan por guiones bajos (_); por ejemplo, foo_hometenant.com_EXT_@resourcetenant.com.
aud En los tokens de acceso de la versión 1, esta notificación se usa para cambiar el formato de la notificación aud. Esta notificación no tiene ningún efecto en los tokens de la versión 2 ni en los tokens de identificador de ninguna versión, donde la notificación aud es siempre el identificador del cliente. Use esta configuración para asegurarse de que la API pueda realizar la validación de las audiencias más fácilmente. Al igual que todas las notificaciones opcionales que afectan al token de acceso, el recurso de la solicitud debe establecer esta notificación opcional, ya que los recursos poseen el token de acceso.
use_guid Emite el identificador de cliente del recurso (API) en formato GUID como notificación aud siempre en lugar de que sea dependiente del entorno de ejecución. Por tanto, si un recurso establece esta marca y su identificador de cliente es 00001111-aaaa-2222-bbbb-3333cccc4444, cualquier aplicación que solicite un token de acceso para ese recurso recibe un token de acceso con aud : 00001111-aaaa-2222-bbbb-3333cccc4444. Sin este conjunto de notificaciones, una API podría obtener tokens con una notificación aud de api://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField o cualquier otro valor establecido como un URI de identificador de aplicación para esa API, así como el identificador de cliente del recurso.
idtyp Esta notificación se usa para obtener el tipo de token (aplicación, usuario, dispositivo). De manera predeterminada, únicamente se emite para tokens de solo aplicación. Al igual que todas las notificaciones opcionales que afectan al token de acceso, el recurso de la solicitud debe establecer esta notificación opcional, ya que los recursos poseen el token de acceso.
include_user_token Emite la notificación idtyp para el token de usuarios. Sin esta propiedad adicional opcional para el conjunto de notificaciones idtyp, una API solo obtiene la notificación para los tokens de aplicación.

Ejemplo de additionalProperties

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Este objeto upn hace que el token de identificador devuelto al cliente incluya una notificación optionalClaims con el otro inquilino de inicio y la información de los recursos del inquilino. La notificación upn solo cambia en el token si el usuario es un invitado en el inquilino (que usa un IDP diferente para la autenticación).

Consulte también

Pasos siguientes