Compartir a través de

Referencia de notificaciones opcionales

  • Artículo

Puede usar notificaciones opcionales para:

  • Seleccione notificaciones para incluir en tokens para la aplicación.
  • Cambie el comportamiento de determinadas notificaciones que devuelve la plataforma de identidad de Microsoft en tokens.
  • Agregue y acceda a notificaciones personalizadas para la aplicación.

Aunque las notificaciones opcionales se admiten en tokens de formato v1.0 y v2.0 y tokens SAML, proporcionan la mayor parte de su valor al pasar de v1.0 a v2.0. En la plataforma de identidad de Microsoft, los tamaños de token más pequeños se usan para garantizar un rendimiento óptimo por parte de los clientes. Como resultado, varias notificaciones incluidas anteriormente en los tokens de acceso e identificador ya no están presentes en los tokens v2.0 y se deben solicitar específicamente por aplicación.

Tipo de cuenta Tokens v1.0 Tokens v2.0
Cuenta Microsoft personal N/A Soportado
Cuenta de Microsoft Entra Soportado Soportado

Conjunto de notificaciones opcionales v1.0 y v2.0

El conjunto de notificaciones opcionales disponibles de forma predeterminada para que las aplicaciones que se usen se muestran 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. Al agregar notificaciones al token de acceso, las notificaciones se aplican a los tokens de acceso solicitados para la aplicación (una API web), no 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 se pueden incluir en JWT para tokens v1.0 y v2.0, pero no en 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 enumeradas no se aplican a los usuarios consumidores (no tienen ningún 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 usuarios en el inquilino JWT, SAML Si el usuario es miembro del inquilino, el valor es 0. Si son invitados, el valor es 1.
acrs Identificadores 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 identificadores 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 Hora en que el usuario se autentique por última vez. JWT
ctry País o región del usuario JWT Esta notificación se devuelve si está presente y el valor del campo es un código estándar de país o región de dos letras, como FR, JP, SZ, etc.
email Dirección de correo electrónico notificada para este usuario JWT, SAML MSA, Identificador de Entra de Microsoft Este valor se incluye de forma predeterminada si el usuario es invitado en el inquilino. Para los usuarios administrados (los usuarios dentro del inquilino), se debe solicitar a través de esta notificación opcional o, solo en la versión 2.0, con el ámbito openID. No se garantiza que este valor sea correcto y que sea mutable a lo largo del tiempo; nunca lo use para la autorización ni para guardar datos para un usuario. Para obtener más información, consulte Validar que el usuario tiene permiso para acceder a estos datos. Si usa 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, usando esta notificación como sugerencia o rellenado previamente en la experiencia de usuario.
fwd Dirección IP JWT Agrega la dirección original del cliente solicitante (cuando se encuentra dentro de una red virtual).
groups Formato opcional para notificaciones de grupo JWT, SAML La notificación groups se usa con la configuración GroupMembershipClaims en el manifiesto de aplicación , que también se debe establecer.
idtyp Tipo de token Tokens de acceso JWT Especial: solo en tokens de acceso solo para aplicaciones El valor es app cuando el token es un token de solo aplicación. Esta notificación es la manera más precisa de que una API determine si un token es un token de aplicación o un token de aplicación+usuario.
login_hint Sugerencia de inicio de sesión JWT MSA, Identificador de Entra de Microsoft Una notificación de sugerencia de inicio de sesión confiable opaca que está codificada en base 64. No modifique este valor. Esta notificación es el mejor valor para usar para el parámetro login_hint OAuth en todos los flujos para obtener el inicio de sesión único. Se puede pasar entre aplicaciones para ayudarles a iniciar sesión único de forma silenciosa: la aplicación A puede iniciar sesión en un usuario, leer la notificación login_hint y, a continuación, enviar la notificación y el contexto de inquilino actual a la aplicación B en la cadena de consulta o fragmento cuando el usuario selecciona en un vínculo que los lleva a la aplicación B. Para evitar problemas de confiabilidad y condiciones de carrera, la notificación login_hintno incluye el inquilino actual para el usuario y el valor predeterminado es 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. Esta notificación está pensada para su uso con la funcionalidad de login_hint existente del SDK, sin embargo, que expone.
tenant_ctry País o región del inquilino de recursos JWT Igual que ctry excepto establecido en un nivel de inquilino por un administrador. También debe ser un valor estándar de dos letras.
tenant_region_scope Región del inquilino de recursos JWT
upn UserPrincipalName JWT, SAML 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 única la información del usuario (por ejemplo, como clave de base de datos). En su lugar, use el identificador de objeto de usuario (oid) como clave de base de datos. Para obtener más información, consulte Aplicaciones y API seguras mediante la validación de notificaciones. Los usuarios que inician sesión con un identificador 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 tokens v1 y preferred_username para tokens v2. Aunque esta notificación se incluye automáticamente, puede especificarla como una notificación opcional para adjuntar otras propiedades para modificar su comportamiento en el caso del usuario invitado. Debe usar la notificación de login_hint para login_hint usar: los identificadores legibles como UPN no son confiables.
verified_primary_email Origen de PrimaryAuthoritativeEmail del usuario JWT
verified_secondary_email Origen de SecondaryAuthoritativeEmail del usuario JWT
vnet Información del especificador de red virtual. JWT
xms_cc Funcionalidades de cliente JWT Microsoft Entra ID Indica si la aplicación cliente que adquirió el token es capaz de controlar los desafíos de 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 que el token se emite para controlar 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 obtener 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 de correo electrónico del usuario. JWT Se considera que un correo electrónico es un dominio comprobado 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 se usa para la autenticación mediante el flujo de código de acceso único (OTP). Las cuentas de Facebook y SAML/WS-Fed no han comprobado dominios. Para que esta notificación se devuelva en el token, se requiere la presencia de la notificación email.
xms_pdl Ubicación de datos preferida JWT En el caso de 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 obtener más información, consulte la documentación de Microsoft Entra Connect sobre la ubicación de datos preferida.
xms_pl Idioma preferido por el usuario JWT Idioma preferido del usuario, si se establece. Origen de su inquilino principal, en escenarios de acceso de invitado. LL-CC con formato ("en-us").
xms_tpl Idioma preferido del inquilino JWT Idioma preferido del inquilino de recursos, si se establece. LL con formato ("en").
ztdid Id. de implementación sin interacción JWT La identidad del dispositivo usada para Windows AutoPilot.

Advertencia

Nunca use email o upn valores de notificación 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, por lo que son inseguros y no confiables para la autorización.

Conjunto de notificaciones opcionales específico de v2.0

Estas notificaciones siempre se incluyen en tokens v1.0, pero no se incluyen en los tokens v2.0 a menos que se soliciten. Estas notificaciones solo son aplicables a los JWT (tokens de identificador y tokens de acceso).

Notificación JWT Nombre Descripción Notas
ipaddr Dirección IP Dirección IP desde la que el cliente inició sesión.
onprem_sid Identificador de seguridad local
pwd_exp Hora de expiración de contraseña Número de segundos después del tiempo en la notificación iat en la que expira la contraseña. Esta notificación solo se incluye cuando la contraseña expira pronto (según lo definido por "días de notificación" en la directiva de contraseñas).
pwd_url Cambiar la dirección URL de contraseña Dirección URL que el usuario puede visitar para cambiar su contraseña. Esta notificación solo se incluye cuando la contraseña expira pronto (según lo definido por "días de notificación" en la directiva de contraseñas).
in_corp Dentro de la red corporativa Indica si el cliente inicia sesión desde la red corporativa. Si no lo son, la notificación no se incluye. En función de la configuración de ip de confianza en MFA.
family_name Apellido Proporciona el apellido, apellido o nombre de familia del usuario tal como se define en el objeto user. Por ejemplo, "family_name":"Miller". Se admite en MSA y microsoft Entra ID. Requiere el ámbito de profile.
given_name Nombre Proporciona el nombre primero 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 de profile.
upn Nombre principal de usuario 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 única la información del usuario (por ejemplo, como clave de base de datos). Para obtener más información, consulte Aplicaciones y API seguras mediante la validación de notificaciones. En su lugar, use el identificador de objeto de usuario (oid) como clave de base de datos. Los usuarios que inician sesión con un identificador de inicio de sesión alternativo no deben mostrar su nombre principal de usuario (UPN). En su lugar, use la siguiente notificación de preferred_username para mostrar el estado de inicio de sesión al usuario. Requiere el ámbito de profile.

Conjunto de notificaciones opcionales específico de v1.0

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

Notificación JWT Nombre Descripción Notas
aud Audiencia Siempre 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, y el identificador de cliente del recurso. Esta selección aleatoria puede ser difícil de codificar al realizar la validación de tokens. Use additionalProperties para esta notificación para asegurarse de que siempre está establecido en el identificador de cliente del recurso en los tokens de acceso v1. Tokens de acceso JWT v1 solo
preferred_username Nombre de usuario preferido Proporciona la notificación de nombre de usuario preferida dentro de los tokens v1. Esta notificación facilita que las aplicaciones proporcionen sugerencias de nombre de usuario y muestren nombres para mostrar legibles humanos, independientemente de su tipo de token. Se recomienda usar esta notificación opcional en lugar de usar, upn o unique_name. Tokens de identificador de v1 y tokens de acceso

additionalProperties de notificaciones opcionales

Algunas notificaciones opcionales se pueden configurar para cambiar la forma en que se devuelve la notificación. Estos additionalProperties se usan principalmente para ayudar a la migración de aplicaciones locales con diferentes expectativas de datos. Por ejemplo, include_externally_authenticated_upn_without_hash ayuda con los clientes que no pueden controlar marcas hash (#) en el UPN.

Nombre de propiedad nombre de additionalProperty Descripción
upn Se puede usar para las respuestas SAML y JWT y para los tokens v1.0 y v2.0.
include_externally_authenticated_upn Incluye el UPN invitado como almacenado en el inquilino de recursos. Por ejemplo, foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Igual que en la lista anterior, excepto que las marcas hash (#) se reemplazan por caracteres de subrayado (_), por ejemplo, foo_hometenant.com_EXT_@resourcetenant.com.
aud En los tokens de acceso v1, esta notificación se usa para cambiar el formato de la notificación de aud. Esta notificación no tiene ningún efecto en los tokens v2 o en los tokens de identificador de la versión, donde la notificación de aud siempre es el identificador de cliente. Use esta configuración para asegurarse de que la API pueda realizar más fácilmente la validación de audiencias. 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 la notificación aud siempre en lugar de depender del entorno de ejecución. Por ejemplo, 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 de 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 y el identificador de cliente del recurso.
idtyp Esta notificación se usa para obtener el tipo de token (aplicación, usuario, dispositivo). De forma predeterminada, solo 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 optionalClaims hace que el token de identificador devuelto al cliente incluya una notificación de upn con el otro inquilino principal y la información del inquilino de recursos. La notificación upn solo se cambia en el token si el usuario es invitado en el inquilino (que usa un IDP diferente para la autenticación).

Consulte también

  • de token de acceso de
  • de token de identificador de

Pasos siguientes