Proporcionar notificaciones opcionales a la aplicación
Los desarrolladores de aplicaciones pueden usar notificaciones opcionales en sus aplicaciones de Azure AD para especificar qué notificaciones desean incluir en los tokens que se envían a las aplicaciones.
Estas notificaciones opcionales sirven para:
- Seleccionar las notificaciones adicionales 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.
Para obtener las listas de notificaciones estándar, vea la documentación de notificaciones de token de acceso y de id_token.
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. Uno de los objetivos de la Plataforma de identidad de Microsoft es conseguir tamaños de token menores 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.
Tabla 1: Aplicabilidad
| 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 Azure AD | Compatible | Compatible |
Conjunto de notificaciones opcionales de las versiones 1.0 y 2.0
El conjunto de notificaciones opcionales disponibles de forma predeterminada para que las usen las aplicaciones se enumeran a continuación. Puede usar datos personalizados en atributos de extensión y extensiones de directorio para agregar notificaciones opcionales para la aplicación. Para usar extensiones de directorio, consulte Extensiones de directorio, a continuación. Al agregar 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).
Tabla 2: Conjunto de notificaciones opcionales de las versiones 1.0 y 2.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. |
|
auth_time |
Momento de la última autenticación del usuario. Consulte las especificaciones de Open ID Connect | JWT | ||
ctry |
País o región del usuario | JWT | Azure AD devuelve la notificación opcional ctry 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, Azure AD | 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 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 rellene previamente la experiencia de usuario. |
fwd |
Dirección IP. | JWT | Agrega la dirección IPv4 original del cliente solicitante (cuando se encuentra en una red virtual) | |
groups |
Formato opcional de las notificaciones de grupo | JWT, SAML | Para más información, vea las notificaciones de grupo abajo. Para más información sobre las notificaciones de grupo, vea Cómo configurar notificaciones de grupo. 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, Azure AD | Notificación de sugerencia de inicio de sesión confiable opaca codificada en base64. 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. Si trabaja en un escenario de invitado, en el que el usuario es de otro inquilino, debe proporcionar un identificador de inquilino en la solicitud de inicio de sesión y pasar lo mismo a las aplicaciones con las que esté asociado. 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 personal y de Azure AD. | |
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, consulte Validación de que el usuario tenga permiso para acceder a estos 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 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 propiedades adicionales y así modificarle el 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_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 Azure AD Connect acerca de la ubicación de datos preferida. Por ejemplo: APC para Asia Pacífico. |
|
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 | La identidad del dispositivo usada en Windows AutoPilot. |
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 de Azure AD, pero no en los 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).
Tabla 3: Notificaciones opcionales exclusivas de la versión 2.0
| 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. "family_name": "Miller" |
Se admite en MSA y Azure AD. 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. "given_name": "Frank" |
Se admite en MSA y Azure AD. 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, consulte Validación de que el usuario tenga permiso para acceder a estos datos. 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. |
Consulte a continuación las propiedades adicionales de la configuración de la notificación. 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 no surtirán efecto en los tokens de identificador solicitados desde el punto de conexión de la versión 2 ni en los tokens de acceso para las API que usan el formato de token de la versión 2. Estas mejoras solo se aplican a los token de JWT, no a los de SAML.
Tabla 4: Notificaciones opcionales exclusivas de la versión 1.0
| 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 las propiedades adicionales 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 de la versión 1. | 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, por ejemplo. |
Tokens de identificador y tokens de acceso de la versión 1 |
Propiedades adicionales de las notificaciones opcionales
Algunas notificaciones opcionales se pueden configurar para cambiar la manera de devolver la notificación. Estas propiedades adicionales 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.
Tabla 4: Valores para configurar las notificaciones opcionales
| Nombre de propiedad | Nombre de la propiedad adicional | 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 antes, excepto que las marcas hash (#) se reemplazan con 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 bb0a297b-6a42-4a55-ac40-09a501456577, cualquier aplicación que solicite un token de acceso para ese recurso recibirá un token de acceso con aud : bb0a297b-6a42-4a55-ac40-09a501456577. 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. |
Ejemplo de propiedades adicionales
"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 upn con el inquilino de inicio adicional 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).
Configuración de notificaciones opcionales
Importante
Los tokens de acceso siempre se generan mediante el manifiesto del recurso, no del cliente, con lo cual en la solicitud ...scope=https://graph.microsoft.com/user.read..., el recurso es Microsoft Graph API. Por lo tanto, el token de acceso se crea usando el manifiesto de Microsoft Graph API, no el manifiesto del cliente. Cambiar el manifiesto de la aplicación nunca hará que los tokens de Microsoft Graph API tengan un aspecto diferente. Para confirmar que los cambios realizados en accessToken han surtido efecto, solicite un token para la aplicación, no otra aplicación.
Puede configurar notificaciones opcionales para la aplicación mediante la interfaz de usuario o el manifiesto.
- Vaya a Azure Portal.
- Busque y seleccione Azure Active Directory.
- En Administrar, seleccione Registros de aplicaciones.
- Seleccione en la lista la aplicación para la que desea configurar notificaciones opcionales.
Configuración de notificaciones opcionales mediante la interfaz de usuario:
En Administrar, seleccione Configuración del token.
- La hoja Configuración del token de la opción de la interfaz de usuario no está disponible para las aplicaciones registradas en un inquilino de Azure AD B2C que se puede configurar mediante la modificación del manifiesto de aplicación. Para más información, consulte Adición de notificaciones y personalización de la entrada del usuario mediante directivas personalizadas en Azure Active Directory B2C.
Seleccione Agregar notificación opcional.
Seleccione el tipo de token que desea configurar.
Seleccione las notificaciones opcionales que va a agregar.
Seleccione Agregar.
Configuración de notificaciones opcionales mediante el manifiesto de aplicación:
En Administrar, seleccione Manifiesto. Se abrirá un editor de manifiestos basado en web que le permitirá editar el manifiesto. Si lo desea, puede seleccionar Descargar, editar el manifiesto de forma local y, a continuación, usar Cargar para volver a aplicarlo a la aplicación. Para más información sobre el manifiesto de aplicación, consulte el artículo Descripción del manifiesto de aplicación de Azure AD.
La entrada siguiente del manifiesto de aplicación agrega las notificaciones opcionales
auth_time,ipaddryupna los tokens de identificador, acceso y SAML."optionalClaims": { "idToken": [ { "name": "auth_time", "essential": false } ], "accessToken": [ { "name": "ipaddr", "essential": false } ], "saml2Token": [ { "name": "upn", "essential": false }, { "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId", "source": "user", "essential": false } ] }Cuando termine, seleccione Guardar. Ahora, las notificaciones opcionales especificadas se incluirán en los tokens de la aplicación.
Tipo OptionalClaims
Indica las notificaciones opcionales solicitadas por una aplicación. Una aplicación puede configurar que las notificaciones opcionales se devuelvan en los tres tipos de tokens (de identificación, de acceso y SAML 2) que reciba desde el servicio de token de seguridad. La aplicación puede configurar un conjunto diferente de notificaciones opcionales que se devuelva en cada tipo de token. La propiedad OptionalClaims de la entidad de la aplicación es un objeto OptionalClaims.
Tabla 5: Propiedades del tipo OptionalClaims
| Nombre | Tipo | Descripción |
|---|---|---|
idToken |
Colección (OptionalClaim) | Notificaciones opcionales que se devuelven en el token de identificación de JWT. |
accessToken |
Colección (OptionalClaim) | Notificaciones opcionales que se devuelven en el token de acceso de JWT. |
saml2Token |
Colección (OptionalClaim) | Notificaciones opcionales que se devuelven en el token SAML de JWT. |
Tipo OptionalClaim
Contiene una notificación opcional asociada a una aplicación o una entidad de servicio. Las propiedades idToken, accessToken y saml2Token del tipo OptionalClaims son una colección de OptionalClaim. Si lo admite una notificación concreta, también puede modificar el comportamiento de OptionalClaim con el campo AdditionalProperties.
Tabla 6: Propiedades del tipo OptionalClaim
| Nombre | Tipo | Descripción |
|---|---|---|
name |
Edm.String | Nombre de la notificación opcional. |
source |
Edm.String | Origen (objeto de directorio) de la notificación. Hay unas notificaciones predefinidas y otras definidas por el usuario desde las propiedades de extensión. Si el valor de origen es null, es una notificación opcional predefinida. Si el valor de origen es user, el valor de la propiedad name es la propiedad de extensión del objeto de usuario. |
essential |
Edm.Boolean | Si el valor es true, la notificación especificada por el cliente es necesaria garantizar una experiencia de autorización sin problemas para la tarea concreta solicitada por el usuario final. El valor predeterminado es false. |
additionalProperties |
Colección (Edm.String) | Propiedades adicionales de la notificación. Si existe una propiedad en esta colección, modifica el comportamiento de la notificación opcional especificada en la propiedad name. |
Configuración de notificaciones opcionales de extensión de directorio
Además del conjunto de notificaciones opcionales estándar, también se pueden configurar tokens para incluir las extensiones de Microsoft Graph. Para obtener más información, vea Agregar datos personalizados a los recursos mediante extensiones.
Las notificaciones opcionales no admiten las extensiones abiertas y de esquema; solo los atributos de extensiones y las extensiones de directorio. Esta característica es útil para adjuntar información de usuario adicional que puede usar la aplicación, por ejemplo, un identificador adicional o la opción de configuración importante que el usuario haya establecido. Vea la parte inferior de esta página para obtener un ejemplo.
Las extensiones de directorio son una característica solo de Azure AD. Si el manifiesto de aplicación solicita una extensión personalizada y un usuario de MSA inicia sesión en la aplicación, estas extensiones no se devolverán.
Formato de extensión de directorio
Al configurar las notificaciones opcionales de la extensión de directorio mediante el manifiesto de aplicación, use el nombre completo de la extensión (en el formato: extension_<appid>_<attributename>). <appid> es la versión quitada del appId (o id. de cliente) de la aplicación que solicita la notificación.
En el JWT, estas notificaciones se emitirán con el siguiente formato de nombre: extn.<attributename>.
En los tokens SAML, estas notificaciones se emitirán con el siguiente formato de identificador uniforme de recursos: http://schemas.microsoft.com/identity/claims/extn.<attributename>.
Configuración de notificaciones opcionales de grupo
En esta sección se describen las opciones de configuración de notificaciones opcionales para cambiar los atributos de grupo usados en las notificaciones de grupo, desde el atributo objectID de grupo predeterminado a los atributos que se sincronizan desde una instalación local de Active Directory de Windows. Puede configurar notificaciones opcionales de grupo para la aplicación mediante la interfaz de usuario o el manifiesto.
Importante
Azure AD limita la cantidad de grupos emitidos en un token a 150 para las aserciones de SAML y 200 para JWT, incluidos los grupos anidados. Consulte Configurar notificaciones de grupo de aplicaciones con Azure AD para obtener más información acerca de los límites de grupo e importantes salvedades sobre las notificaciones de grupo de los atributos locales.
Configuración de notificaciones opcionales de grupo mediante la interfaz de usuario:
- Inicie sesión en Azure Portal.
- Después de haberse autenticado, elija el inquilino de Azure AD; para ello, selecciónelo en la esquina superior derecha de la página.
- Busque y seleccione Azure Active Directory.
- En Administrar, seleccione Registros de aplicaciones.
- Seleccione en la lista la aplicación para la que desea configurar notificaciones opcionales.
- En Administrar, seleccione Configuración del token.
- Seleccione Agregar notificación de grupos.
- Seleccione los tipos de grupo que se van a devolver (Grupos de seguridad, Roles de directorio, Todos los grupos o Grupos asignados a la aplicación):
- La opción Grupos asignados a la aplicación solo incluye esos grupos. Se recomienda la opción Grupos asignados a la aplicación para organizaciones de gran tamaño debido al límite de grupos en un token. Para cambiar los grupos asignados a la aplicación, seleccione la aplicación en la lista Aplicaciones empresariales. Seleccione Usuarios y grupos y, luego, Agregar usuario/grupo. Seleccione los grupos que quiere agregar a la aplicación desde Usuarios y grupos.
- La opción Todos los grupos incluye SecurityGroup, DirectoryRole y DistributionList, pero no Grupos asignados a la aplicación.
- Opcional: seleccione las propiedades de tipo de token específico para modificar el valor de notificaciones de grupos para que contenga los atributos de grupo locales o para cambiar el tipo de notificaciones a un rol.
- Seleccione Guardar.
Configuración de notificaciones opcionales de grupo mediante el manifiesto de aplicación:
Inicie sesión en Azure Portal.
Después de haberse autenticado, elija el inquilino de Azure AD; para ello, selecciónelo en la esquina superior derecha de la página.
Busque y seleccione Azure Active Directory.
Seleccione en la lista la aplicación para la que desea configurar notificaciones opcionales.
En Administrar, seleccione Manifiesto.
Agregue la siguiente entrada mediante el editor de manifiestos:
Los valores válidos son:
- "Todos" (esta opción incluye SecurityGroup, DirectoryRole y DistributionList)
- "SecurityGroup"
- "DirectoryRole"
- "ApplicationGroup" (esta opción solo incluye los grupos asignados a la aplicación)
Por ejemplo:
"groupMembershipClaims": "SecurityGroup"De forma predeterminada, los valores de ObjectID de grupo se emitirán en el valor de la notificación de grupo. Para modificar el valor de la notificación para que contenga los atributos del grupo local, o para cambiar el tipo de notificación a rol, use la configuración de notificaciones opcionales de la siguiente manera:
Establezca las notificaciones opcionales para la configuración de nombre de grupo.
Si quiere que los grupos del token contengan los atributos de grupo locales de AD en la sección de notificaciones opcionales, especifique a qué tipo de token se debe aplicar la notificación, el nombre de la notificación opcional solicitada y las propiedades adicionales que quiera usar. Pueden aparecer varios tipos de token:
- idToken para el token de OIDC ID
- accessToken para el token de acceso OAuth
- Saml2Token para los token de SAML.
El tipo Saml2Token se aplica a los token con formato SAML 1.1 y SAML 2.0.
Para cada tipo de token relevante, modifique las notificaciones de grupos para usar la sección OptionalClaims en el manifiesto. El esquema de OptionalClaims es el siguiente:
{ "name": "groups", "source": null, "essential": false, "additionalProperties": [] }Esquema de notificaciones opcionales Value name: Debe ser "grupos" source: No se usa. Omitir o especificar null essential: No se usa. Omitir o especificar falso additionalProperties: Lista de propiedades adicionales. Las opciones válidas son "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "emit_as_roles" y "cloud_displayname". En additionalProperties solo se necesita un valor de "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name". Si hay más de uno, se usa el primero y omiten los demás. Además, puede agregar "cloud_displayname" para emitir el nombre para mostrar del grupo en la nube. Tenga en cuenta que esta opción solo funciona cuando
“groupMembershipClaims”se establece en“ApplicationGroup”.Algunas aplicaciones requieren información de grupo sobre el usuario en la notificación de rol. Para cambiar el tipo de notificación de una notificación de grupo a una notificación de rol, agregue "emit_as_roles" a las propiedades adicionales. Los valores de grupo se emitirán en la notificación de rol.
Si se usa "emit_as_roles", cualquier rol de aplicación configurado que se asigne al usuario no aparecerá en la notificación de rol.
Ejemplos:
Emita grupos como nombres de grupo en tokens de acceso OAuth con el formato dnsDomainName\sAMAccountName.
Configuración en la interfaz de usuario:
Entrada en el manifiesto de aplicación:
"optionalClaims": { "accessToken": [ { "name": "groups", "additionalProperties": [ "dns_domain_and_sam_account_name" ] } ] }Emita los nombres de grupo que se devolverán en el formato NetBIOSDomain\sAMAccountName como la notificación de roles de los token de SAML y OIDC ID.
Configuración en la interfaz de usuario:
Entrada en el manifiesto de aplicación:
"optionalClaims": { "saml2Token": [ { "name": "groups", "additionalProperties": [ "netbios_domain_and_sam_account_name", "emit_as_roles" ] } ], "idToken": [ { "name": "groups", "additionalProperties": [ "netbios_domain_and_sam_account_name", "emit_as_roles" ] } ] }Emita nombres de grupo con el formato samAccountName para grupos sincronizados locales y el nombre para mostrar de los grupos en la nube en tokens de identificador de OIDC y SAML para los grupos asignados a la aplicación:
Entrada en el manifiesto de aplicación:
"groupMembershipClaims": "ApplicationGroup", "optionalClaims": { "saml2Token": [ { "name": "groups", "additionalProperties": [ "sam_account_name", "cloud_displayname" ] } ], "idToken": [ { "name": "groups", "additionalProperties": [ "sam_account_name", "cloud_displayname" ] } ] }
Ejemplo de notificaciones opcionales
En esta sección, conocerá un escenario para ver cómo puede usar la característica de notificaciones opcionales para su aplicación. Hay varias opciones disponibles para actualizar las propiedades de una configuración de identidad de la aplicación y así habilitar y configurar las notificaciones opcionales:
- Puede usar la interfaz de usuario de Configuración del token (consulte el ejemplo siguiente).
- Puede usar el Manifiesto (consulte el ejemplo a continuación). Lea primero el documento Manifiesto de aplicación de Azure Active Directory para una introducción al manifiesto.
- También es posible escribir una aplicación que use Microsoft Graph API para actualizarla. El tipo OptionalClaims de la guía de referencia de Microsoft Graph API puede ayudarle con la configuración de las notificaciones opcionales.
Ejemplo:
En el siguiente ejemplo usará la interfaz de usuario de Configuración del token y el Manifiesto para agregar notificaciones opcionales a los tokens de acceso, identificador y SAML previstos para la aplicación. Se agregarán distintas notificaciones opcionales para cada tipo de token que la aplicación puede recibir:
- Los tokens de identificación contendrán el nombre principal de usuario de los usuarios federados en la forma completa (
<upn>_<homedomain>#EXT#@<resourcedomain>). - Ahora, los tokens de acceso que soliciten otros clientes para esta aplicación incluirán la notificación auth_time.
- Los tokens SAML contendrán ahora la extensión del esquema de directorio skypeId (en este ejemplo, el identificador de esta aplicación es ab603c56068041afb2f6832e2a17e237). Los tokens SAML expondrán el identificador de Skype como
extension_ab603c56068041afb2f6832e2a17e237_skypeId.
Configuración en la interfaz de usuario:
Inicie sesión en Azure Portal.
Después de haberse autenticado, elija el inquilino de Azure AD; para ello, selecciónelo en la esquina superior derecha de la página.
Busque y seleccione Azure Active Directory.
En Administrar, seleccione Registros de aplicaciones.
Busque la aplicación para la que quiera configurar notificaciones opcionales en la lista y selecciónela.
En Administrar, seleccione Configuración del token.
Seleccione Agregar notificación opcional, elija el tipo de token de Id. , seleccione upn en la lista de notificaciones y, finalmente, Agregar.
Seleccione Agregar notificación opcional, elija el tipo de token de Acceso, seleccione auth_time en la lista de notificaciones y, finalmente, Agregar.
En la pantalla de información general de Configuración del token, seleccione el icono de lápiz situado junto a upn, seleccione el control de alternancia Autenticado externamente y, por último, Guardar.
Seleccione Agregar notificación opcional, elija el tipo de token SAML, seleccione extn.skypeID en la lista de notificaciones (solo es aplicable si ha creado un objeto de usuario de Azure AD denominado skypeID) y, finalmente, Agregar.
Configuración en el manifiesto:
Inicie sesión en Azure Portal.
Después de haberse autenticado, elija el inquilino de Azure AD; para ello, selecciónelo en la esquina superior derecha de la página.
Busque y seleccione Azure Active Directory.
Busque la aplicación para la que quiera configurar notificaciones opcionales en la lista y selecciónela.
En Administrar, seleccione Manifiesto para abrir el editor de manifiestos en línea.
Puede editar directamente el manifiesto mediante este editor. El manifiesto sigue el esquema de la Entidad de la aplicación y da formato al manifiesto automáticamente al guardarlo. Se agregarán los elementos nuevos a la propiedad
OptionalClaims."optionalClaims": { "idToken": [ { "name": "upn", "essential": false, "additionalProperties": [ "include_externally_authenticated_upn" ] } ], "accessToken": [ { "name": "auth_time", "essential": false } ], "saml2Token": [ { "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId", "source": "user", "essential": true } ] }Cuando haya terminado de actualizar el manifiesto, seleccione Guardar para guardarlo.
Pasos siguientes
Más información sobre las notificaciones estándares que proporciona Azure AD.