Procedimientos: Proporcionar notificaciones opcionales a la aplicación de Azure ADHow to: Provide optional claims to your Azure AD app

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.Application developers can use optional claims in their Azure AD applications to specify which claims they want in tokens sent to their application.

Estas notificaciones opcionales sirven para:You can use optional claims to:

  • Seleccionar las notificaciones adicionales que se incluirán en los tokens para la aplicación.Select additional claims to include in tokens for your application.
  • Cambiar el comportamiento de ciertas notificaciones que Azure AD devuelve en tokens.Change the behavior of certain claims that Azure AD returns in tokens.
  • Agregar notificaciones personalizadas para la aplicación y acceder a ellas.Add and access custom claims for your application.

Para obtener las listas de notificaciones estándar, vea la documentación de notificaciones de token de acceso y de id_token.For the lists of standard claims, see the access token and id_token claims documentation.

Aunque las notificaciones opcionales se admiten en los tokens de formato de las versiones 1.0 y 2.0, así como en los tokens SAML, estos tokens proporcionan la mayoría de sus valores al pasar de la versión 1.0 a la 2.0.While optional claims are supported in both v1.0 and v2.0 format tokens, as well as SAML tokens, they provide most of their value when moving from v1.0 to v2.0. Uno de los objetivos del punto de conexión de la plataforma de identidad de Microsoft de la versión 2.0 es conseguir tamaños de token menores para garantizar el rendimiento óptimo de los clientes.One of the goals of the v2.0 Microsoft identity platform endpoint is smaller token sizes to ensure optimal performance by clients. 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.As a result, several claims formerly included in the access and ID tokens are no longer present in v2.0 tokens and must be asked for specifically on a per-application basis.

Tabla 1: AplicabilidadTable 1: Applicability

Tipo de cuentaAccount Type Tokens de la versión 1.0v1.0 tokens Tokens de la versión 2.0v2.0 tokens
Cuenta personal de MicrosoftPersonal Microsoft account N/DN/A CompatibleSupported
Cuenta de Azure ADAzure AD account CompatibleSupported CompatibleSupported

Conjunto de notificaciones opcionales de las versiones 1.0 y 2.0v1.0 and v2.0 optional claims set

El conjunto de notificaciones opcionales disponibles de forma predeterminada para que las usen las aplicaciones se enumeran a continuación.The set of optional claims available by default for applications to use are listed below. Para agregar notificaciones opcionales personalizadas para la aplicación, consulte las extensiones de directorio a continuación.To add custom optional claims for your application, see Directory Extensions, below. 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.When adding claims to the access token, the claims apply to access tokens requested for the application (a web API), not claims requested by the application. 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.No matter how the client accesses your API, the right data is present in the access token that is used to authenticate against your 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.The majority of these claims can be included in JWTs for v1.0 and v2.0 tokens, but not SAML tokens, except where noted in the Token Type column. Las cuentas de consumidor admiten un subconjunto de estas notificaciones, marcadas en la columna "Tipo de usuario".Consumer accounts support a subset of these claims, marked in the "User Type" column. 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).Many of the claims listed do not apply to consumer users (they have no tenant, so tenant_ctry has no value).

Tabla 2: Conjunto de notificaciones opcionales de las versiones 1.0 y 2.0Table 2: v1.0 and v2.0 optional claim set

NombreName DescripciónDescription Tipo de tokenToken Type Tipo de usuarioUser Type NotasNotes
auth_time Momento de la última autenticación del usuario.Time when the user last authenticated. Consulte las especificaciones de Open ID ConnectSee OpenID Connect spec. JWTJWT
tenant_region_scope Región del inquilino de los recursosRegion of the resource tenant JWTJWT
home_oid Para los usuarios invitados, identificador de objeto del usuario en el inquilino del usuario principal.For guest users, the object ID of the user in the user’s home tenant. JWTJWT
sid Identificador de sesión que se usa para el cierre de cada sesión de usuario.Session ID, used for per-session user sign-out. JWTJWT Cuentas personal y de Azure AD.Personal and Azure AD accounts.
platf Plataforma de dispositivoDevice platform JWTJWT Restringido a los dispositivos administrados que pueden verificar el tipo de dispositivoRestricted to managed devices that can verify device type.
verified_primary_email Procede del valor PrimaryAuthoritativeEmail del usuarioSourced from the user’s PrimaryAuthoritativeEmail JWTJWT
verified_secondary_email Procede del valor SecondaryAuthoritativeEmail del usuarioSourced from the user’s SecondaryAuthoritativeEmail JWTJWT
enfpolids Identificadores de las directivas en vigor.Enforced policy IDs. Lista de los identificadores de las directivas que se evaluaron para el usuario actualA list of the policy IDs that were evaluated for the current user. JWTJWT
vnet Información del especificador de la red virtualVNET specifier information. JWTJWT
fwd Dirección IP.IP address. JWTJWT Agrega la dirección IPv4 original del cliente solicitante (cuando se encuentra en una red virtual)Adds the original IPv4 address of the requesting client (when inside a VNET)
ctry País del usuarioUser’s country JWTJWT Azure AD devuelve la notificación opcional ctry si existe y el valor de la notificación es un código de país estándar de dos letras, como FR, JP, SZ, etc.Azure AD returns the ctry optional claim if it's present and the value of the claim is a standard two-letter country code, such as FR, JP, SZ, and so on.
tenant_ctry País del inquilino de los recursosResource tenant’s country JWTJWT
xms_pdl Ubicación de datos preferidaPreferred data location JWTJWT 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.For Multi-Geo tenants, the preferred data location is the three-letter code showing the geographic region the user is in. Para más información, vea la documentación de Azure AD Connect acerca de la ubicación de datos preferida.For more info, see the Azure AD Connect documentation about preferred data location.
Por ejemplo: APC para Asia Pacífico.For example: APC for Asia Pacific.
xms_pl Idioma preferido del usuarioUser preferred language JWTJWT El idioma preferido del usuario, si se establece.The user’s preferred language, if set. Se origina desde su inquilino principal, en escenarios de acceso de invitado.Sourced from their home tenant, in guest access scenarios. Con formato LL-CC ("en-us").Formatted LL-CC (“en-us”).
xms_tpl Idioma preferido del inquilinoTenant preferred language JWTJWT El idioma preferido del inquilino de recursos, si se establece.The resource tenant’s preferred language, if set. Con formato LL ("en").Formatted LL (“en”).
ztdid Identificador de implementación sin interacciónZero-touch Deployment ID JWTJWT La identidad del dispositivo usada en Windows AutoPilot.The device identity used for Windows AutoPilot
email Correo electrónico direccionable de este usuario, si tiene uno.The addressable email for this user, if the user has one. JWT, SAMLJWT, SAML MSA, Azure ADMSA, Azure AD Si el usuario es un invitado en el inquilino, este valor se incluye de forma predeterminada.This value is included by default if the user is a guest in the tenant. 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.For managed users (the users inside the tenant), it must be requested through this optional claim or, on v2.0 only, with the OpenID scope. Para los usuarios administrados, se debe establecer la dirección de correo electrónico en el portal de administración de Office.For managed users, the email address must be set in the Office admin portal.
groups Formato opcional de las notificaciones de grupoOptional formatting for group claims JWT, SAMLJWT, SAML Se usa junto con la configuración de GroupMembershipClaims en el manifiesto de la aplicación, que se debe establecer también.Used in conjunction with the GroupMembershipClaims setting in the application manifest, which must be set as well. Para más información, vea las notificaciones de grupo abajo.For details see Group claims below. Para más información sobre las notificaciones de grupo, vea Cómo configurar notificaciones de grupoFor more information about group claims, see How to configure group claims
acct Estado de la cuenta de los usuarios de un inquilino.Users account status in tenant. JWT, SAMLJWT, SAML Si el usuario es miembro del inquilino, el valor es 0.If the user is a member of the tenant, the value is 0. Si es un invitado, el valor es 1.If they are a guest, the value is 1.
upn Notificación UserPrincipalName.UserPrincipalName claim. JWT, SAMLJWT, SAML Aunque esta notificación se incluye automáticamente, puede especificarla como opcional para adjuntar propiedades adicionales y así modificarle el comportamiento para los usuarios invitadosAlthough this claim is automatically included, you can specify it as an optional claim to attach additional properties to modify its behavior in the guest user case.

Conjunto de notificaciones opcionales específicas de la versión 2.0v2.0-specific optional claims set

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.These claims are always included in v1.0 Azure AD tokens, but not included in v2.0 tokens unless requested. Estas notificaciones solo son válidas en los JWT (tokens de identificación y de acceso).These claims are only applicable for JWTs (ID tokens and Access Tokens).

Tabla 3: Notificaciones opcionales exclusivas de la versión 2.0Table 3: v2.0-only optional claims

Notificación de JWTJWT Claim NombreName DescripciónDescription NotasNotes
ipaddr Dirección IPIP Address Dirección IP del cliente desde el que se inició sesión.The IP address the client logged in from.
onprem_sid Identificador de seguridad localOn-Premises Security Identifier
pwd_exp Tiempo de expiración de la contraseñaPassword Expiration Time Fecha y hora a la que expira la contraseña.The datetime at which the password expires.
pwd_url Cambiar dirección URL de contraseñaChange Password URL Dirección URL que el usuario puede visitar para cambiar la contraseña.A URL that the user can visit to change their password.
in_corp Dentro de red corporativaInside Corporate Network Indica si el cliente ha iniciado sesión desde la red corporativa.Signals if the client is logging in from the corporate network. En caso contrario, la notificación no se incluye.If they're not, the claim isn't included. En función de la configuración de las IP de confianza de MFA.Based off of the trusted IPs settings in MFA.
nickname AliasNickname Nombre adicional para el usuario.An additional name for the user. El alias es independiente del nombre o el apellido.The nickname is separate from first or last name.
family_name ApellidoLast Name Proporciona el apellido del usuario según está definido en el objeto de usuario.Provides the last name, surname, or family name of the user as defined in the user object.
"family_name": "Miller""family_name":"Miller"
Se admite en MSA y Azure AD.Supported in MSA and Azure AD
given_name NombreFirst name Proporciona el nombre de pila o "dado" del usuario, tal como se establece en el objeto de usuario.Provides the first or "given" name of the user, as set on the user object.
"given_name": "Frank""given_name": "Frank"
Se admite en MSA y Azure AD.Supported in MSA and Azure AD
upn Nombre principal del usuarioUser Principal Name Un identificador del usuario que se puede usar con el parámetro username_hint.An identifer for the user that can be used with the username_hint parameter. No es un identificador duradero para el usuario y no debe usarse con datos de clave.Not a durable identifier for the user and should not be used to key data. Consulte a continuación las propiedades adicionales de la configuración de la notificación.See additional properties below for configuration of the claim.

Propiedades adicionales de las notificaciones opcionalesAdditional properties of optional claims

Algunas notificaciones opcionales se pueden configurar para cambiar la manera de devolver la notificación.Some optional claims can be configured to change the way the claim is returned. Estas propiedades adicionales se usan principalmente para ayudarle a migrar aplicaciones locales con diferentes expectativas de datos (por ejemplo, include_externally_authenticated_upn_without_hash le ayudará con los clientes que no pueden admitir almohadillas [#] en el UPN).These additional properties are mostly used to help migration of on-premises applications with different data expectations (for example, include_externally_authenticated_upn_without_hash helps with clients that cannot handle hash marks (#) in the UPN)

Tabla 4: Valores para configurar las notificaciones opcionalesTable 4: Values for configuring optional claims

Nombre de propiedadProperty name Nombre de la propiedad adicionalAdditional Property name DescripciónDescription
upn Puede usarse en respuestas SAML y JWT y para los token v1.0 y v2.0.Can be used for both SAML and JWT responses, and for v1.0 and v2.0 tokens.
include_externally_authenticated_upn Incluye el nombre principal de usuario invitado tal como se almacenó en el inquilino de recursos.Includes the guest UPN as stored in the resource tenant. Por ejemplo: foo_hometenant.com#EXT#@resourcetenant.comFor example, 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.comSame as above, except that the hash marks (#) are replaced with underscores (_), for example foo_hometenant.com_EXT_@resourcetenant.com

Ejemplo de propiedades adicionalesAdditional properties example

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

Este objeto OptionalClaims hace que el token de identificador devuelto al cliente incluya otro UPN con el inquilino de inicio adicional y la información de recursos de inquilino.This OptionalClaims object causes the ID token returned to the client to include another upn with the additional home tenant and resource tenant information. 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).The upn claim is only changed in the token if the user is a guest in the tenant (that uses a different IDP for authentication).

Configuración de notificaciones opcionalesConfiguring optional claims

Importante

Los tokens de acceso siempre se generan mediante el manifiesto del recurso, no del cliente,Access tokens are always generated using the manifest of the resource, not the client. con lo cual en la solicitud ...scope=https://graph.microsoft.com/user.read..., el recurso es Graph.So in the request ...scope=https://graph.microsoft.com/user.read... the resource is Graph. Por lo tanto, el token de acceso se crea usando el manifiesto de Graph, no el manifiesto del cliente.Thus, the access token is created using the Graph manifest, not the client's manifest. Cambiar el manifiesto de la aplicación nunca hará que los tokens de Graph tengan un aspecto diferente.Changing the manifest for your application will never cause tokens for Graph to look different. Para confirmar que los cambios realizados en accessToken han surtido efecto, solicite un token para la aplicación, no otra aplicación.In order to validate that your accessToken changes are in effect, request a token for your application, not another app.

Puede configurar notificaciones opcionales para la aplicación mediante la interfaz de usuario o el manifiesto.You can configure optional claims for your application through the UI or application manifest.

  1. Vaya a Azure Portal.Go to the Azure portal. Busque y seleccione Azure Active Directory.Search for and select Azure Active Directory.
  2. En la sección Administrar, seleccione Registros de aplicaciones.From the Manage section, select App registrations.
  3. Seleccione en la lista la aplicación para la que desea configurar notificaciones opcionales.Select the application you want to configure optional claims for in the list.

Configuración de notificaciones opcionales mediante la interfaz de usuario:Configuring optional claims through the UI:

Muestra cómo configurar notificaciones opcionales mediante la interfaz de usuario.Shows how to configure optional claims using the UI

  1. En la sección Administrar, seleccione Configuración del token (versión preliminar) .From the Manage section, select Token configuration (preview).
  2. Seleccione Agregar notificación opcional.Select Add optional claim.
  3. Seleccione el tipo de token que desea configurar.Select the token type you want to configure.
  4. Seleccione las notificaciones opcionales que va a agregar.Select the optional claims to add.
  5. Haga clic en Agregar.Click Add.

Configuración de notificaciones opcionales mediante el manifiesto de aplicación:Configuring optional claims through the application manifest:

Muestra cómo configurar notificaciones opcionales mediante el manifiesto de aplicación.Shows how to configure optional claims using the app manifest

  1. En la sección Administrar, seleccione Manifiesto.From the Manage section, select Manifest. Se abrirá un editor de manifiestos basado en web que le permitirá editar el manifiesto.A web-based manifest editor opens, allowing you to edit the manifest. 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.Optionally, you can select Download and edit the manifest locally, and then use Upload to reapply it to your application. 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.For more information on the application manifest, see the Understanding the Azure AD application manifest article.

    La siguiente entrada del manifiesto de aplicación agrega las notificaciones opcionales auth_time, ipaddr y upn a los tokens de identificador, acceso y SAML.The following application manifest entry adds the auth_time, ipaddr, and upn optional claims to ID, access, and SAML tokens.

        "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
                       }
               ]
           }
    
  2. Cuando termine, haga clic en Guardar.When finished, click Save. Ahora, las notificaciones opcionales especificadas se incluirán en los tokens de la aplicación.Now the specified optional claims will be included in the tokens for your application.

Tipo OptionalClaimsOptionalClaims type

Indica las notificaciones opcionales solicitadas por una aplicación.Declares the optional claims requested by an application. 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.An application can configure optional claims to be returned in each of three types of tokens (ID token, access token, SAML 2 token) it can receive from the security token service. La aplicación puede configurar un conjunto diferente de notificaciones opcionales que se devuelva en cada tipo de token.The application can configure a different set of optional claims to be returned in each token type. La propiedad OptionalClaims de la entidad de la aplicación es un objeto OptionalClaims.The OptionalClaims property of the Application entity is an OptionalClaims object.

Tabla 5: Propiedades del tipo OptionalClaimsTable 5: OptionalClaims type properties

NombreName TipoType DescripciónDescription
idToken Colección (OptionalClaim)Collection (OptionalClaim) Notificaciones opcionales que se devuelven en el token de identificación de JWT.The optional claims returned in the JWT ID token.
accessToken Colección (OptionalClaim)Collection (OptionalClaim) Notificaciones opcionales que se devuelven en el token de acceso de JWT.The optional claims returned in the JWT access token.
saml2Token Colección (OptionalClaim)Collection (OptionalClaim) Notificaciones opcionales que se devuelven en el token SAML de JWT.The optional claims returned in the SAML token.

Tipo OptionalClaimOptionalClaim type

Contiene una notificación opcional asociada a una aplicación o una entidad de servicio.Contains an optional claim associated with an application or a service principal. Las propiedades idToken, accessToken y saml2Token del tipo OptionalClaims son una colección de OptionalClaim.The idToken, accessToken, and saml2Token properties of the OptionalClaims type is a collection of OptionalClaim. Si lo admite una notificación concreta, también puede modificar el comportamiento de OptionalClaim con el campo AdditionalProperties.If supported by a specific claim, you can also modify the behavior of the OptionalClaim using the AdditionalProperties field.

Tabla 6: Propiedades del tipo OptionalClaimTable 6: OptionalClaim type properties

NombreName TipoType DescripciónDescription
name Edm.StringEdm.String Nombre de la notificación opcional.The name of the optional claim.
source Edm.StringEdm.String Origen (objeto de directorio) de la notificación.The source (directory object) of the claim. Hay unas notificaciones predefinidas y otras definidas por el usuario desde las propiedades de extensión.There are predefined claims and user-defined claims from extension properties. Si el valor de origen es null, es una notificación opcional predefinida.If the source value is null, the claim is a predefined optional claim. Si el valor de origen es user, el valor de la propiedad name es la propiedad de extensión del objeto de usuario.If the source value is user, the value in the name property is the extension property from the user object.
essential Edm.BooleanEdm.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.If the value is true, the claim specified by the client is necessary to ensure a smooth authorization experience for the specific task requested by the end user. El valor predeterminado es false.The default value is false.
additionalProperties Colección (Edm.String)Collection (Edm.String) Propiedades adicionales de la notificación.Additional properties of the claim. Si existe una propiedad en esta colección, modifica el comportamiento de la notificación opcional especificada en la propiedad name.If a property exists in this collection, it modifies the behavior of the optional claim specified in the name property.

Configuración de notificaciones opcionales de extensión de directorioConfiguring directory extension optional claims

Además del conjunto de notificaciones opcionales estándar, también se pueden configurar tokens para incluir las extensiones.In addition to the standard optional claims set, you can also configure tokens to include extensions. Para obtener más información, vea Agregar datos personalizados a los recursos mediante extensiones.For more info, see Add custom data to resources using extensions. 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.This feature is useful for attaching additional user information that your app can use – for example, an additional identifier or important configuration option that the user has set. Vea la parte inferior de esta página para obtener un ejemplo.See the bottom of this page for an example.

Nota

  • Las extensiones de esquema de directorio son una característica exclusiva de Azure AD, por lo que 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.Directory schema extensions are an Azure AD-only feature, so if your application manifest requests a custom extension and an MSA user logs into your app, these extensions will not be returned.

Formato de extensión de directorioDirectory extension formatting

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>).When configuring directory extension optional claims using the application manifest, use the full name of the extension (in the format: extension_<appid>_<attributename>). <appid> debe coincidir con el identificador de la aplicación que solicita la notificación.The <appid> must match the ID of the application requesting the claim.

En el JWT, estas notificaciones se emitirán con el siguiente formato de nombre: extn.<attributename>.Within the JWT, these claims will be emitted with the following name format: 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>.Within the SAML tokens, these claims will be emitted with the following URI format: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Configuración de notificaciones opcionales de grupoConfiguring groups optional claims

Nota

La capacidad para emitir nombres de grupo para usuarios y grupos sincronizados de forma local se encuentra en fase de versión preliminar pública.The ability to emit group names for users and groups synced from on-premises is Public Preview.

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.This section covers the configuration options under optional claims for changing the group attributes used in group claims from the default group objectID to attributes synced from on-premises Windows Active Directory. Puede configurar notificaciones opcionales de grupo para la aplicación mediante la interfaz de usuario o el manifiesto.You can configure groups optional claims for your application through the UI or application manifest.

Importante

Vea Configurar notificaciones de grupo de aplicaciones con Azure AD para obtener más detalles, incluidas algunas salvedades importantes sobre la versión preliminar pública de las notificaciones de grupo de atributos locales.For more details including important caveats for the public preview of group claims from on-premises attributes, see Configure group claims for applications with Azure AD.

Configuración de notificaciones opcionales de grupo mediante la interfaz de usuario:Configuring groups optional claims through the UI:

  1. Inicie sesión en el Portal de AzureSign in to the Azure portal
  2. Después de haberse autenticado, elija el inquilino de Azure AD; para ello, selecciónelo en la esquina superior derecha de la páginaAfter you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page
  3. Seleccione Azure Active Directory en el menú de la izquierdaSelect Azure Active Directory from the left-hand menu
  4. En la sección Administrar, seleccione Registros de aplicacionesUnder the Manage section, select App registrations
  5. Seleccione en la lista la aplicación para la que desea configurar notificaciones opcionalesSelect the application you want to configure optional claims for in the list
  6. En la sección Administrar, seleccione Configuración del token (versión preliminar)Under the Manage section, select Token configuration (preview)
  7. Seleccione Agregar notificación de grupoSelect Add groups claim
  8. Seleccione los tipos de grupo que se van a devolver (Todos los grupos, SecurityGroup o DirectoryRole).Select the group types to return (All Groups, SecurityGroup, or DirectoryRole). La opción Todos los grupos incluye SecurityGroup, DirectoryRole y DistributionListThe All Groups option includes SecurityGroup, DirectoryRole, and DistributionList
  9. Opcional: haga clic en 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 rolOptional: click on the specific token type properties to modify the groups claim value to contain on premises group attributes or to change the claim type to a role
  10. Haga clic en GuardarClick Save

Configuración de notificaciones opcionales de grupo mediante el manifiesto de aplicación:Configuring groups optional claims through the application manifest:

  1. Inicie sesión en el Portal de AzureSign in to the Azure portal

  2. Después de haberse autenticado, elija el inquilino de Azure AD; para ello, selecciónelo en la esquina superior derecha de la páginaAfter you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page

  3. Seleccione Azure Active Directory en el menú de la izquierdaSelect Azure Active Directory from the left-hand menu

  4. Seleccione en la lista la aplicación para la que desea configurar notificaciones opcionalesSelect the application you want to configure optional claims for in the list

  5. En la sección Administrar, seleccione ManifiestoUnder the Manage section, select Manifest

  6. Agregue la siguiente entrada mediante el editor de manifiestos:Add the following entry using the manifest editor:

    Los valores válidos son:The valid values are:

    • "Todos" (esta opción incluye SecurityGroup, DirectoryRole y DistributionList)"All" (this option includes SecurityGroup, DirectoryRole, and DistributionList)
    • "SecurityGroup""SecurityGroup"
    • "DirectoryRole""DirectoryRole"

    Por ejemplo:For example:

        "groupMembershipClaims": "SecurityGroup"
    

    De forma predeterminada, los valores de ObjectID de grupo se emitirán en el valor de la notificación de grupo.By default Group ObjectIDs will be emitted in the group claim value. 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:To modify the claim value to contain on premises group attributes, or to change the claim type to role, use OptionalClaims configuration as follows:

  7. Establezca las notificaciones opcionales para la configuración de nombre de grupo.Set group name configuration optional claims.

    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.If you want to groups in the token to contain the on premises AD group attributes in the optional claims section specify which token type optional claim should be applied to, the name of optional claim requested and any additional properties desired. Pueden aparecer varios tipos de token:Multiple token types can be listed:

    • idToken para el token de OIDC IDidToken for the OIDC ID token
    • accessToken para el token de acceso OAuth/OIDCaccessToken for the OAuth/OIDC access token
    • Saml2Token para los token de SAML.Saml2Token for SAML tokens.

    Nota

    El tipo Saml2Token se aplica a los token con formato SAML 1.1 y SAML 2.0The Saml2Token type applies to both SAML1.1 and SAML2.0 format tokens

    Para cada tipo de token relevante, modifique las notificaciones de grupos para usar la sección OptionalClaims en el manifiesto.For each relevant token type, modify the groups claim to use the OptionalClaims section in the manifest. El esquema de OptionalClaims es el siguiente:The OptionalClaims schema is as follows:

       {
       "name": "groups",
       "source": null,
       "essential": false,
       "additionalProperties": []
       }
    
    Esquema de notificaciones opcionalesOptional claims schema ValueValue
    name:name: Debe ser "grupos"Must be "groups"
    source:source: No se usa.Not used. Omitir o especificar nullOmit or specify null
    essential:essential: No se usa.Not used. Omitir o especificar falsoOmit or specify false
    additionalProperties:additionalProperties: Lista de propiedades adicionales.List of additional properties. Las opciones válidas son "sam_account_name", “dns_domain_and_sam_account_name”, “netbios_domain_and_sam_account_name”, "emit_as_roles"Valid options are "sam_account_name", “dns_domain_and_sam_account_name”, “netbios_domain_and_sam_account_name”, "emit_as_roles"

    En additionalProperties solo se necesita un valor de "sam_account_name", “dns_domain_and_sam_account_name”, “netbios_domain_and_sam_account_name”.In additionalProperties only one of "sam_account_name", “dns_domain_and_sam_account_name”, “netbios_domain_and_sam_account_name” are required. Si hay más de uno, se usa el primero y omiten los demás.If more than one is present, the first is used and any others ignored.

    Algunas aplicaciones requieren información de grupo sobre el usuario en la notificación de rol.Some applications require group information about the user in the role claim. Para cambiar el tipo de notificación de una notificación de grupo a una notificación de rol, agregue "emit_as_roles" a propiedades adicionales.To change the claim type to from a group claim to a role claim, add “emit_as_roles” to additional properties. Los valores de grupo se emitirán en la notificación de rol.The group values will be emitted in the role claim.

    Nota

    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.If "emit_as_roles" is used any Application Roles configured that the user is assigned will not appear in the role claim

Ejemplos:Examples:

  1. Emita grupos como nombres de grupo en tokens de acceso OAuth con el formato dnsDomainName\sAMAccountName.Emit groups as group names in OAuth access tokens in dnsDomainName\sAMAccountName format

    Configuración en la interfaz de usuario:UI configuration:

    Muestra cómo configurar notificaciones opcionales mediante la interfaz de usuario.Shows how to configure optional claims using the UI

    Entrada en el manifiesto de aplicación:Application manifest entry:

        "optionalClaims": {
            "accessToken": [{
            "name": "groups",
            "additionalProperties": ["dns_domain_and_sam_account_name"]
            }]
        }
    
  2. 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.Emit group names to be returned in netbiosDomain\sAMAccountName format as the roles claim in SAML and OIDC ID Tokens

    Configuración en la interfaz de usuario:UI configuration:

    Muestra cómo configurar notificaciones opcionales mediante la interfaz de usuario.Shows how to configure optional claims using the UI

    Entrada en el manifiesto de aplicación:Application manifest entry:

        "optionalClaims": {
        "saml2Token": [{
            "name": "groups",
            "additionalProperties": ["netbios_name_and_sam_account_name", "emit_as_roles"]
        }],
        "idToken": [{
            "name": "groups",
            "additionalProperties": ["netbios_name_and_sam_account_name", "emit_as_roles"]
        }]
    

Ejemplo de notificaciones opcionalesOptional claims example

En esta sección, conocerá un escenario para ver cómo puede usar la característica de notificaciones opcionales para su aplicación.In this section, you can walk through a scenario to see how you can use the optional claims feature for your application. Hay varias opciones disponibles para actualizar las propiedades de configuración de identidad de la aplicación y así habilitar y configurar las notificaciones opcionales:There are multiple options available for updating the properties on an application’s identity configuration to enable and configure optional claims:

  • Puede usar la interfaz de usuario de Configuración del token (versión preliminar) (consulte el ejemplo a continuación).You can use the Token configuration (preview) UI (see example below)
  • Puede usar el Manifiesto (consulte el ejemplo a continuación).You can use the Manifest (see example below). Lea primero el documento Manifiesto de aplicación de Azure Active Directory para una introducción al manifiesto.Read the Understanding the Azure AD application manifest document first for an introduction to the manifest.
  • También es posible escribir una aplicación que use Graph API para actualizarla.It's also possible to write an application that uses the Graph API to update your application. El tipo OptionalClaims de la guía de referencia de Graph API puede ayudarle con la configuración de las notificaciones opcionales.The OptionalClaims type in the Graph API reference guide can help you with configuring the optional claims.

Ejemplo: en el siguiente ejemplo usará la interfaz de usuario de Configuración del token (versión preliminar) y el Manifiesto para agregar notificaciones opcionales a los tokens de acceso, identificador y SAML previstos para la aplicación.Example: In the example below, you will use the Token configuration (preview) UI and Manifest to add optional claims to the access, ID, and SAML tokens intended for your application. Se agregarán distintas notificaciones opcionales para cada tipo de token que la aplicación puede recibir:Different optional claims will be added to each type of token that the application can receive:

  • Los tokens de identificación contendrán el nombre principal de usuario de los usuarios federados en la forma completa (<upn>_<homedomain>#EXT#@<resourcedomain>).The ID tokens will now contain the UPN for federated users in the full form (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • Los tokens de acceso que soliciten otros clientes para esta aplicación incluirán la notificación auth_time.The access tokens that other clients request for this application will now include the auth_time claim
  • 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).The SAML tokens will now contain the skypeId directory schema extension (in this example, the app ID for this app is ab603c56068041afb2f6832e2a17e237). Los tokens SAML expondrán el identificador de Skype como extension_skypeId.The SAML tokens will expose the Skype ID as extension_skypeId.

Configuración en la interfaz de usuario:UI configuration:

  1. Inicie sesión en el Portal de AzureSign in to the Azure portal

  2. Después de haberse autenticado, elija el inquilino de Azure AD; para ello, selecciónelo en la esquina superior derecha de la página.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. Seleccione Azure Active Directory en el menú de la izquierda.Select Azure Active Directory from the left-hand menu.

  4. En la sección Administrar, seleccione Registros de aplicaciones.Under the Manage section, select App registrations.

  5. Busque la aplicación para la que desea configurar notificaciones opcionales en la lista y haga clic en ella.Find the application you want to configure optional claims for in the list and click on it.

  6. En la sección Administrar, haga clic en Configuración del token (versión preliminar) .Under the Manage section, click Token configuration (preview).

  7. Seleccione Agregar notificación opcional, elija el tipo de token de identificador, seleccione upn en la lista de notificaciones y haga clic en Agregar.Select Add optional claim, select the ID token type, select upn from the list of claims, and then click Add.

  8. Seleccione Agregar notificación opcional, elija el tipo de token de acceso, seleccione auth_time en la lista de notificaciones y haga clic en Agregar.Select Add optional claim, select the Access token type, select auth_time from the list of claims, then click Add.

  9. En la pantalla de información general de Configuración del token, haga clic en el icono de lápiz situado junto a upn, haga clic en el control de alternancia Autenticado externamente y, por último, haga clic en Guardar.From the Token Configuration overview screen, click on the pencil icon next to upn, click the Externally authenticated toggle, and then click Save.

  10. 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 haga clic en Agregar.Select Add optional claim, select the SAML token type, select extn.skypeID from the list of claims (only applicable if you've created an Azure AD user object called skypeID), and then click Add.

    Muestra cómo configurar notificaciones opcionales mediante la interfaz de usuario.Shows how to configure optional claims using the UI

Configuración en el manifiesto:Manifest configuration:

  1. Inicie sesión en Azure Portal.Sign in to the Azure portal.

  2. Después de haberse autenticado, elija el inquilino de Azure AD; para ello, selecciónelo en la esquina superior derecha de la página.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. Seleccione Azure Active Directory en el menú de la izquierda.Select Azure Active Directory from the left-hand menu.

  4. Busque la aplicación para la que desea configurar notificaciones opcionales en la lista y haga clic en ella.Find the application you want to configure optional claims for in the list and click on it.

  5. En la sección Administrar, haga clic en Manifiesto para abrir el editor de manifiestos insertado.Under the Manage section, click Manifest to open the inline manifest editor.

  6. Puede editar directamente el manifiesto mediante este editor.You can directly edit the manifest using this editor. El manifiesto sigue el esquema de la Entidad de la aplicación y da formato al manifiesto automáticamente al guardarlo.The manifest follows the schema for the Application entity, and automatically formats the manifest once saved. Se agregarán los elementos nuevos a la propiedad OptionalClaims.New elements will be added to the OptionalClaims property.

            "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
                  }
                 ]
        ``` 
    
    
    
  7. When you're finished updating the manifest, click Save to save the manifest.

Next steps

Learn more about the standard claims provided by Azure AD.