Compartir a través de

Configuración de notificaciones opcionales

  • Artículo

Los tokens que devuelve Microsoft Entra se mantienen más pequeños para garantizar un rendimiento óptimo por parte de los clientes que los solicitan. Como resultado, varias notificaciones ya no están presentes en el token de manera predeterminada y deben solicitarse específicamente en cada solicitud.

Puedes configurar notificaciones opcionales para la aplicación a través de la interfaz de usuario o el manifiesto de aplicaciones del Centro de administración Microsoft Entra.

Requisitos previos

Configuración de notificaciones opcionales en la aplicación

  1. Inicie sesión en el Centro de administración de Microsoft Entra como Administrador de aplicaciones en la nube.
  2. Vaya a Identidad>Aplicaciones> Registro de aplicaciones.
  3. Elija la aplicación para la que desea configurar notificaciones opcionales en función del escenario y el resultado deseado.
  1. En Administrar, seleccione Configuración del token.
  2. Seleccione Agregar notificación opcional.
  3. Seleccione el tipo de token que desea configurar, como Acceso.
  4. Seleccione las notificaciones opcionales que va a agregar.
  5. Seleccione Agregar.

El objeto optionalClaims indica las notificaciones opcionales solicitadas por una aplicación. Una aplicación puede configurar notificaciones opcionales que se devuelven en tokens de identificador, tokens de acceso y tokens SAML 2. La aplicación puede configurar un conjunto diferente de notificaciones opcionales que se devuelva en cada tipo de token.

Nombre Escribir Descripción
idToken Colección Notificaciones opcionales que se devuelven en el token de identificación de JWT.
accessToken Colección Notificaciones opcionales que se devuelven en el token de acceso de JWT.
saml2Token Colección Notificaciones opcionales que se devuelven en el token SAML de JWT.

Si lo admite una notificación concreta, también puede modificar el comportamiento de la notificación opcional mediante el campo additionalProperties.

Nombre Escribir 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) Otras propiedades 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.

Importante

Los tokens de acceso siempre se generan mediante el manifiesto del recurso, no del cliente, En la solicitud ...scope=https://graph.microsoft.com/user.read..., el recurso es Microsoft Graph API. 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 hace 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.

Las notificaciones opcionales admiten atributos de extensión y extensiones de directorio. Esta característica es útil para incluir más información sobre el usuario que su aplicación puede usar. Por ejemplo, otros identificadores u opciones de configuración importantes que el usuario ha establecido. 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 devuelven.

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 emiten con el siguiente formato de nombre: extn.<attributename>. En los tokens SAML, estas notificaciones se emiten con el siguiente formato de URI: http://schemas.microsoft.com/identity/claims/extn.<attributename>.

Configuración de notificaciones opcionales de grupos

Sugerencia

Los pasos de este artículo pueden variar ligeramente en función del portal desde donde comienza.

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 las notificaciones opcionales de grupos para la aplicación a través del manifiesto de aplicación o Azure Portal. Las notificaciones opcionales de grupo solo se emiten en el JWT para las entidades de seguridad de usuario. Las entidades de servicio no se incluyen en las notificaciones opcionales de grupos emitidas en el JWT.

Importante

La cantidad de grupos emitidos en un token se limita a 150 para las aserciones de SAML y a 200 para JWT, incluidos los grupos anidados. Consulte Configurar notificaciones de grupo para aplicaciones 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.

Complete los pasos siguientes para configurar las notificaciones opcionales de grupos mediante Azure Portal:

  1. Seleccione la aplicación para la que desea configurar notificaciones opcionales.
  2. En Administrar, seleccione Configuración del token.
  3. Seleccione Agregar notificación de grupos.
  4. 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.
  5. 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.
  6. Seleccione Guardar.

Complete los pasos siguientes para configurar las notificaciones opcionales de grupos mediante el manifiesto de aplicación:

  1. Seleccione la aplicación para la que desea configurar notificaciones opcionales.

  2. En Administrar, seleccione Manifiesto.

  3. 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 identificadores de objeto de grupo se emiten 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 optionalClaims de la siguiente manera:

  4. 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 en la sección de notificaciones opcionales, especifique a qué tipo de token se debe aplicar la notificación opcional. También especifique el nombre de la notificación opcional solicitada y cualquier otra propiedad deseada.

    Pueden aparecer varios tipos de token:

    • idToken para el token de identificador de OIDC
    • accessToken para el token de acceso OAuth
    • Saml2Token para tokens SAML

    El tipo Saml2Token se aplica a los tokens tanto en formato SAML1.1 como SAML2.0.

    Para cada tipo de token pertinente, modifique la notificación de grupos para usar la sección optionalClaims en el manifiesto. El esquema optionalClaims es el siguiente:

    {
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}
    Esquema de notificaciones opcionales Value
    name Debe ser groups
    source No se usa. Omitir o especificar null.
    essential No se usa. Omitir o especificar false.
    additionalProperties Lista de otras propiedades. 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 uno las propiedades sam_account_name, dns_domain_and_sam_account_name, netbios_domain_and_sam_account_name es obligatorio. Si hay más de uno, se usa el primero y omiten los demás. También puede agregar cloud_displayname para emitir el nombre para mostrar del grupo de nube. Esta opción solo funciona cuando groupMembershipClaims está establecido 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 additionalProperties. Los valores de grupo se emiten en la notificación de rol.

    Si se utiliza emit_as_roles, cualquier rol de aplicación configurado que el usuario (o una aplicación de recursos) tenga asignado no estará en la notificación de rol.

En los ejemplos siguientes se muestra la configuración del manifiesto para las notificaciones de grupo:

Emita los grupos como nombres de grupos en tokens de acceso de OAuth con formato dnsDomainName\sAMAccountName.

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Emita los nombres de grupos que se devolverán con formato netbiosDomain\sAMAccountName como la notificación de roles en tokens de identificador de OIDC y SAML.

"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 sam_account_name para grupos sincronizados locales y el nombre cloud_display de los grupos en la nube en los tokens de identificador de OIDC y SAML para los grupos asignados a la 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

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 Azure Portal
  • Puede usar el 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.

En el ejemplo siguiente, Azure Portal y el manifiesto se usan para agregar notificaciones opcionales a los tokens de acceso, de identificador y de SAML destinados a la aplicación. Se agregan distintas notificaciones opcionales para cada tipo de token que la aplicación puede recibir:

  • Los tokens de identificación contienen el nombre principal de usuario de los usuarios federados en la forma completa (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • Los tokens de acceso que soliciten otros clientes para esta aplicación incluyen la notificación auth_time.
  • Los tokens SAML contienen la extensión del esquema de directorio skypeId (en este ejemplo, el id. de la aplicación para esta aplicación es ab603c56068041afb2f6832e2a17e237). Los tokens SAML exponen el identificador de Skype como extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Configure las notificaciones en Azure Portal:

  1. Seleccione la aplicación para la que desea configurar notificaciones opcionales.
  2. En Administrar, seleccione Configuración del token.
  3. Seleccione Agregar notificación opcional, elija el tipo de token de Id. , seleccione upn en la lista de notificaciones y, finalmente, Agregar.
  4. Seleccione Agregar notificación opcional, elija el tipo de token de Acceso, seleccione auth_time en la lista de notificaciones y, finalmente, Agregar.
  5. 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.
  6. 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 Microsoft Entra denominado skypeID) y, finalmente, Agregar.

Configure las notificaciones en el manifiesto:

  1. Seleccione la aplicación para la que desea configurar notificaciones opcionales.

  2. En Administrar, seleccione Manifiesto para abrir el editor de manifiestos en línea.

  3. 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 agregan 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
        }
    ]
}

  4. Cuando haya terminado de actualizar el manifiesto, seleccione Guardar para guardarlo.

Limitación

Una aplicación puede emitir un número máximo de 10 atributos de extensión como notificaciones opcionales.

Contenido relacionado