Como: fornecer declarações opcionais para seu aplicativo do Azure ADHow to: Provide optional claims to your Azure AD app

Os desenvolvedores de aplicativos podem usar declarações opcionais em seus aplicativos do Azure AD para especificar quais declarações eles desejam em tokens enviados para seu aplicativo.Application developers can use optional claims in their Azure AD applications to specify which claims they want in tokens sent to their application.

Você pode usar declarações opcionais para:You can use optional claims to:

  • Selecione declarações adicionais para incluir nos tokens para o aplicativo.Select additional claims to include in tokens for your application.
  • Altere o comportamento de determinadas declarações que o Azure AD retorna em tokens.Change the behavior of certain claims that Azure AD returns in tokens.
  • Adicione e acesse as declarações personalizadas para o aplicativo.Add and access custom claims for your application.

Para obter as listas de declarações padrão, consulte o token de acesso e a documentação de declarações de id_token .For the lists of standard claims, see the access token and id_token claims documentation.

Embora as declarações opcionais tenham suporte nos tokens de formato v 1.0 e v 2.0, bem como nos tokens SAML, elas fornecem a maior parte de seu valor ao mudar de v 1.0 para v 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. Um dos objetivos do ponto de extremidade da plataforma de identidade da Microsoft v 2.0 é um tamanho de token menor para garantir o desempenho ideal dos 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, várias declarações anteriormente incluídas em tokens de acesso e ID não estão mais presentes nos tokens v2.0 e devem ser solicitadas especificamente, por aplicativo.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.

Tabela 1: AplicabilidadeTable 1: Applicability

Tipo de ContaAccount Type Tokens v1.0v1.0 tokens Tokens v2.0v2.0 tokens
Conta pessoal da MicrosoftPersonal Microsoft account N/DN/A Com suporteSupported
Conta do AD do AzureAzure AD account Com suporteSupported Com suporteSupported

conjunto de declarações opcionais v 1.0 e v 2.0v1.0 and v2.0 optional claims set

O conjunto de declarações opcionais disponíveis por padrão para uso pelos aplicativos é listado abaixo.The set of optional claims available by default for applications to use are listed below. Para adicionar declarações opcionais personalizadas para o aplicativo, confira Extensões de Diretório, abaixo.To add custom optional claims for your application, see Directory Extensions, below. Ao adicionar declarações ao token de acesso, as declarações se aplicam aos tokens de acesso solicitados para o aplicativo (uma API da Web), não as declarações solicitadas pelo aplicativo.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. Não importa como o cliente acessa sua API, os dados corretos estão presentes no token de acesso que é usado para autenticar em sua 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.

Observação

A maioria dessas declarações pode ser incluída em JWTs para tokens v1.0 e v2.0, mas não para tokens SAML, exceto quando indicado na coluna 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. As contas de consumidor dão suporte a um subconjunto dessas declarações, marcadas na coluna "tipo de usuário".Consumer accounts support a subset of these claims, marked in the "User Type" column. Muitas das declarações listadas não se aplicam aos usuários do consumidor (não têm locatários, portanto tenant_ctry não tem valor).Many of the claims listed do not apply to consumer users (they have no tenant, so tenant_ctry has no value).

Tabela 2: conjunto de declarações opcionais v 1.0 e v 2.0Table 2: v1.0 and v2.0 optional claim set

NomeName DescriptionDescription Tipo de tokenToken Type Tipo de UsuárioUser Type ObservaçõesNotes
auth_time Hora em que o usuário foi autenticado pela última vez.Time when the user last authenticated. Confira especificações de OpenID Connect.See OpenID Connect spec. JWTJWT
tenant_region_scope Região do locatário do recursoRegion of the resource tenant JWTJWT
home_oid Para usuários convidados, a ID de objeto do usuário no locatário inicial do usuário.For guest users, the object ID of the user in the user’s home tenant. JWTJWT
sid ID da sessão, usada para saída do usuário por sessão.Session ID, used for per-session user sign-out. JWTJWT Contas pessoais e do Azure AD.Personal and Azure AD accounts.
platf Plataforma de dispositivosDevice platform JWTJWT Restrito aos dispositivos gerenciados que podem verificar o tipo de dispositivo.Restricted to managed devices that can verify device type.
verified_primary_email Originado de PrimaryAuthoritativeEmail do usuárioSourced from the user’s PrimaryAuthoritativeEmail JWTJWT
verified_secondary_email Originado de SecondaryAuthoritativeEmail do usuárioSourced from the user’s SecondaryAuthoritativeEmail JWTJWT
enfpolids IDs de política aplicada.Enforced policy IDs. Uma lista de IDs de política que foram avaliadas para o usuário atual.A list of the policy IDs that were evaluated for the current user. JWTJWT
vnet Informações de especificador de VNET.VNET specifier information. JWTJWT
fwd Endereço IP.IP address. JWTJWT Adiciona o endereço IPv4 original do cliente solicitante (quando dentro de uma VNET)Adds the original IPv4 address of the requesting client (when inside a VNET)
ctry O país do usuárioUser’s country JWTJWT O Azure AD retorna a declaração opcional ctry se ela estiver presente e o valor da declaração é um código de país padrão de duas letras, como FR, JP, SZ e assim por diante.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 do locatário de recursosResource tenant’s country JWTJWT
xms_pdl Local dos dados preferidoPreferred data location JWTJWT Para locatários de várias regiões geográficas, o local de dados preferencial é o código de três letras mostrando a região geográfica em que o usuário está.For Multi-Geo tenants, the preferred data location is the three-letter code showing the geographic region the user is in. Para obter mais informações, consulte a documentação de Azure ad Connect sobre o local de dados preferencial.For more info, see the Azure AD Connect documentation about preferred data location.
Por exemplo: APC para Pacífico Asiático.For example: APC for Asia Pacific.
xms_pl Idioma preferido do usuárioUser preferred language JWTJWT O idioma preferido do usuário, se definido.The user’s preferred language, if set. Originado de seu locatário inicial, em cenários de acesso de convidado.Sourced from their home tenant, in guest access scenarios. Tem o formato II-PP ("en-us").Formatted LL-CC (“en-us”).
xms_tpl Idioma preferido do locatárioTenant preferred language JWTJWT O idioma preferido do locatário do recurso, se definido.The resource tenant’s preferred language, if set. Com o formato II (“en”).Formatted LL (“en”).
ztdid ID de implantação de zero toqueZero-touch Deployment ID JWTJWT A identidade do dispositivo usada para o Windows AutoPilotThe device identity used for Windows AutoPilot
email O email endereçável para este usuário, se o usuário tiver um.The addressable email for this user, if the user has one. JWT, SAMLJWT, SAML MSA, Azure ADMSA, Azure AD Esse valor é incluído por padrão, se o usuário é um convidado no locatário.This value is included by default if the user is a guest in the tenant. Para usuários gerenciados (os usuários dentro do locatário), ele deve ser solicitado por essa declaração opcional ou, somente no v 2.0, com o escopo de 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 usuários gerenciados, o endereço de email deve ser definido portal de administração do Office.For managed users, the email address must be set in the Office admin portal.
groups Formatação opcional para declarações de grupoOptional formatting for group claims JWT, SAMLJWT, SAML Usado em conjunto com a configuração GroupMembershipClaims no manifesto do aplicativo, que também deve ser definido.Used in conjunction with the GroupMembershipClaims setting in the application manifest, which must be set as well. Para obter detalhes, consulte declarações de grupo abaixo.For details see Group claims below. Para obter mais informações sobre declarações de grupo, consulte como configurar declarações de grupoFor more information about group claims, see How to configure group claims
acct Status da conta de usuários no locatário.Users account status in tenant. JWT, SAMLJWT, SAML Se o usuário for um membro do locatário, o valor será 0.If the user is a member of the tenant, the value is 0. Se eles forem convidado, o valor é 1.If they are a guest, the value is 1.
upn Declaração UserPrincipalName.UserPrincipalName claim. JWT, SAMLJWT, SAML Embora essa declaração seja incluída automaticamente, você pode especificá-la como uma declaração opcional para anexar propriedades adicionais a fim de modificar seu comportamento, no caso do usuário convidado.Although 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.

v 2.0-conjunto de declarações opcionais específicasv2.0-specific optional claims set

Essas declarações são sempre incluídas em tokens do Azure AD v 1.0, mas não são incluídas em tokens v 2.0, a menos que solicitado.These claims are always included in v1.0 Azure AD tokens, but not included in v2.0 tokens unless requested. Essas declarações são aplicáveis somente para JWTs (tokens de ID e tokens de acesso).These claims are only applicable for JWTs (ID tokens and Access Tokens).

Tabela 3: v 2.0-apenas declarações opcionaisTable 3: v2.0-only optional claims

Declaração JWTJWT Claim NomeName DescriptionDescription ObservaçõesNotes
ipaddr Endereço IPIP Address O endereço IP com o qual o cliente se conectou.The IP address the client logged in from.
onprem_sid Identificador de Segurança LocalOn-Premises Security Identifier
pwd_exp Hora da Expiração da SenhaPassword Expiration Time A data e a hora em que a senha expira.The datetime at which the password expires.
pwd_url Alterar URL da SenhaChange Password URL Uma URL que o usuário pode acessar para alterar sua senha.A URL that the user can visit to change their password.
in_corp Dentro da Rede CorporativaInside Corporate Network Indica se o cliente está se conectando da rede corporativa.Signals if the client is logging in from the corporate network. Se não forem, a declaração não será incluída.If they're not, the claim isn't included. Baseado nas configurações de IPs confiáveis na Autenticação Multifator.Based off of the trusted IPs settings in MFA.
nickname ApelidoNickname Um nome adicional para o usuário.An additional name for the user. O apelido é separado de First ou Last Name.The nickname is separate from first or last name.
family_name SobrenomeLast Name Fornece o sobrenome, sobrenome ou nome de família do usuário, conforme definido no objeto de usuário.Provides the last name, surname, or family name of the user as defined in the user object.
"family_name":"Barros""family_name":"Miller"
Com suporte no MSA e no Azure ADSupported in MSA and Azure AD
given_name NomeFirst name Fornece o primeiro ou "dado" nome do usuário, conforme definido no objeto de usuário.Provides the first or "given" name of the user, as set on the user object.
"given_name": "Davi""given_name": "Frank"
Com suporte no MSA e no Azure ADSupported in MSA and Azure AD
upn Nome UPNUser Principal Name Um identificador para o usuário que pode ser usado com o parâmetro username_hint.An identifer for the user that can be used with the username_hint parameter. Não é um identificador durável para o usuário e não deve ser usado para dados de chave.Not a durable identifier for the user and should not be used to key data. Ver propriedades adicionais abaixo para a configuração da declaração.See additional properties below for configuration of the claim.

Propriedades adicionais de declarações opcionaisAdditional properties of optional claims

Algumas declarações opcionais podem ser configuradas para alterar o modo como a declaração é retornada.Some optional claims can be configured to change the way the claim is returned. Essas propriedades adicionais são usadas principalmente para ajudar a migração de aplicativos locais com expectativas de dados diferentes (por exemplo, include_externally_authenticated_upn_without_hash ajuda com clientes que não podem manipular marcas (#) no 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)

Tabela 4: valores para configurar declarações opcionaisTable 4: Values for configuring optional claims

Nome da propriedadeProperty name Nome de Propriedade AdicionalAdditional Property name DescriptionDescription
upn Pode ser usada para respostas SAML e JWT e para tokens v1.0 e v2.0.Can be used for both SAML and JWT responses, and for v1.0 and v2.0 tokens.
include_externally_authenticated_upn Inclui o UPN de convidado conforme armazenado no locatário do recurso.Includes the guest UPN as stored in the resource tenant. Por exemplo, foo_hometenant.com#EXT#@resourcetenant.comFor example, foo_hometenant.com#EXT#@resourcetenant.com
include_externally_authenticated_upn_without_hash O mesmo que acima, exceto que as marcas de hash (#) são substituídas por sublinhados (_), por exemplo 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

Exemplo de propriedades adicionaisAdditional properties example

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

Esse objeto OptionalClaims faz com que o token de ID retornado ao cliente inclua outro UPN com o locatário de início adicional e as informações do locatário do recurso.This OptionalClaims object causes the ID token returned to the client to include another upn with the additional home tenant and resource tenant information. A declaração de upn só será alterada no token se o usuário for um convidado no locatário (que usa um IDP diferente para autenticação).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).

Como configurar as declarações opcionaisConfiguring optional claims

Importante

Os tokens de acesso sempre são gerados usando o manifesto do recurso, não o cliente.Access tokens are always generated using the manifest of the resource, not the client. Portanto, na solicitação ...scope=https://graph.microsoft.com/user.read... o recurso é grafo.So in the request ...scope=https://graph.microsoft.com/user.read... the resource is Graph. Assim, o token de acesso é criado usando o manifesto do grafo, não o manifesto do cliente.Thus, the access token is created using the Graph manifest, not the client's manifest. Alterar o manifesto para seu aplicativo nunca fará com que os tokens do Graph pareçam diferentes.Changing the manifest for your application will never cause tokens for Graph to look different. Para validar que as alterações de accessToken estão em vigor, solicite um token para seu aplicativo, não para outro aplicativo.In order to validate that your accessToken changes are in effect, request a token for your application, not another app.

Você pode configurar declarações opcionais para seu aplicativo por meio da interface do usuário ou do manifesto do aplicativo.You can configure optional claims for your application through the UI or application manifest.

  1. Vá para o Portal do Azure.Go to the Azure portal. Pesquise Azure Active Directory e selecione-o.Search for and select Azure Active Directory.
  2. Na seção gerenciar , selecione registros de aplicativo.From the Manage section, select App registrations.
  3. Selecione o aplicativo para o qual você deseja configurar declarações opcionais na lista.Select the application you want to configure optional claims for in the list.

Configurando declarações opcionais por meio da interface do usuário:Configuring optional claims through the UI:

mostra como configurar declarações opcionais usando a interface do usuárioShows how to configure optional claims using the UI

  1. Na seção gerenciar , selecione configuração de token (versão prévia) .From the Manage section, select Token configuration (preview).
  2. Selecione Adicionar declaração opcional.Select Add optional claim.
  3. Selecione o tipo de token que você deseja configurar.Select the token type you want to configure.
  4. Selecione as declarações opcionais a serem adicionadas.Select the optional claims to add.
  5. Clique em Adicionar.Click Add.

Configurando declarações opcionais por meio do manifesto do aplicativo:Configuring optional claims through the application manifest:

mostra como configurar declarações opcionais usando o manifesto do aplicativoShows how to configure optional claims using the app manifest

  1. Na seção gerenciar , selecione manifesto.From the Manage section, select Manifest. Um editor de manifesto baseado na Web é aberto, permitindo que você edite o manifesto.A web-based manifest editor opens, allowing you to edit the manifest. Opcionalmente, você pode selecionar Baixar e editar o manifesto localmente e, em seguida, usar Carregar para reaplicá-lo ao seu aplicativo.Optionally, you can select Download and edit the manifest locally, and then use Upload to reapply it to your application. Para obter mais informações sobre o manifesto do aplicativo, consulte o artigo noções básicas sobre o manifesto do aplicativo do Azure ad.For more information on the application manifest, see the Understanding the Azure AD application manifest article.

    A seguinte entrada de manifesto de aplicativo adiciona as declarações opcionais auth_time, IPADDR e UPN aos tokens de ID, acesso e 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. Ao terminar, clique em Salvar.When finished, click Save. Agora, as declarações opcionais especificadas serão incluídas nos tokens para seu aplicativo.Now the specified optional claims will be included in the tokens for your application.

Tipo de OptionalClaimsOptionalClaims type

Declara as declarações opcionais solicitadas por um aplicativo.Declares the optional claims requested by an application. Um aplicativo pode configurar as declarações opcionais a serem retornadas em cada um dos três tipos de tokens (token de ID, token de acesso, token SAML 2) que pode receber do serviço de token de segurança.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. O aplicativo pode configurar um conjunto de declarações opcionais a serem retornadas em cada tipo de token diferente.The application can configure a different set of optional claims to be returned in each token type. A propriedade OptionalClaims da entidade do aplicativo é um objeto OptionalClaims.The OptionalClaims property of the Application entity is an OptionalClaims object.

Tabela 5: propriedades do tipo OptionalClaimsTable 5: OptionalClaims type properties

NomeName TipoType DescriptionDescription
idToken Coleção (OptionalClaim)Collection (OptionalClaim) As declarações opcionais retornadas no token de ID JWT.The optional claims returned in the JWT ID token.
accessToken Coleção (OptionalClaim)Collection (OptionalClaim) As declarações opcionais retornadas no token de acesso JWT.The optional claims returned in the JWT access token.
saml2Token Coleção (OptionalClaim)Collection (OptionalClaim) As declarações opcionais retornadas no token SAML.The optional claims returned in the SAML token.

Tipo de OptionalClaimOptionalClaim type

Contém uma declaração opcional associada a um aplicativo ou uma entidade de segurança.Contains an optional claim associated with an application or a service principal. As propriedades idToken, accessToken e saml2Token do tipo OptionalClaims são uma coleção de OptionalClaim.The idToken, accessToken, and saml2Token properties of the OptionalClaims type is a collection of OptionalClaim. Caso haja suporte por uma declaração específica, você também poderá modificar o comportamento de OptionalClaim usando o campo AdditionalProperties.If supported by a specific claim, you can also modify the behavior of the OptionalClaim using the AdditionalProperties field.

Tabela 6: propriedades do tipo OptionalClaimTable 6: OptionalClaim type properties

NomeName TipoType DescriptionDescription
name Edm.StringEdm.String O nome da declaração opcional.The name of the optional claim.
source Edm.StringEdm.String A origem (objeto de diretório) da declaração.The source (directory object) of the claim. Há declarações predefinidas e definidas pelo usuário de propriedades de extensão.There are predefined claims and user-defined claims from extension properties. Se o valor de origem for nulo, a declaração será uma declaração opcional predefinida.If the source value is null, the claim is a predefined optional claim. Se o valor de origem for um usuário, o valor na propriedade name será a propriedade de extensão do objeto de usuário.If the source value is user, the value in the name property is the extension property from the user object.
essential Edm.BooleanEdm.Boolean Se o valor for true, a declaração especificada pelo cliente será necessária para garantir uma experiência de autorização sem problemas para a tarefa específica solicitada pelo usuário 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. O valor padrão é false.The default value is false.
additionalProperties Coleção (Edm.String)Collection (Edm.String) Propriedades adicionais da declaração.Additional properties of the claim. Se uma propriedade existir na coleção, ela modificará o comportamento da declaração opcional especificado na propriedade name.If a property exists in this collection, it modifies the behavior of the optional claim specified in the name property.

Configurando declarações opcionais de extensão de diretórioConfiguring directory extension optional claims

Além do conjunto de declarações opcionais padrão, você também pode configurar tokens para incluir extensões.In addition to the standard optional claims set, you can also configure tokens to include extensions. Para obter mais informações, consulte Adicionar dados personalizados a recursos usando extensões.For more info, see Add custom data to resources using extensions. Esse recurso é útil para anexar informações adicionais do usuário que o aplicativo pode usar; por exemplo, um identificador adicional ou uma opção de configuração importante que o usuário configurou.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. Consulte a parte inferior desta página para obter um exemplo.See the bottom of this page for an example.

Observação

  • As extensões de esquema de diretório são um recurso somente do Azure AD, portanto, se o manifesto do aplicativo solicitar uma extensão personalizada e um usuário da MSA fizer logon em seu aplicativo, essas extensões não serão retornadas.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.

Formatação de extensão de diretórioDirectory extension formatting

Ao configurar declarações opcionais de extensão de diretório usando o manifesto do aplicativo, use o nome completo da extensão (no 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>). O <appid> deve corresponder à ID do aplicativo que está solicitando a declaração.The <appid> must match the ID of the application requesting the claim.

No JWT, essas declarações serão emitidas com o seguinte formato de nome: extn.<attributename>.Within the JWT, these claims will be emitted with the following name format: extn.<attributename>.

Em tokens SAML, essas declarações serão emitidas com o seguinte formato de URI: 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>

Configurando declarações opcionais de gruposConfiguring groups optional claims

Observação

A capacidade de emitir nomes de grupo para usuários e grupos sincronizados a partir do local é visualização pública.The ability to emit group names for users and groups synced from on-premises is Public Preview.

Esta seção aborda as opções de configuração em declarações opcionais para alterar os atributos de grupo usados em declarações de grupo do objectID do grupo padrão para atributos sincronizados do Windows Active Directory local.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. Você pode configurar declarações opcionais de grupos para seu aplicativo por meio da interface do usuário ou do manifesto do aplicativo.You can configure groups optional claims for your application through the UI or application manifest.

Importante

Para obter mais detalhes, incluindo advertências importantes para a visualização pública de declarações de grupo de atributos locais, consulte Configurar declarações de grupo para aplicativos com o Azure ad.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.

Configurar declarações opcionais de grupos por meio da interface do usuário:Configuring groups optional claims through the UI:

  1. Entre no Portal do AzureSign in to the Azure portal
  2. Depois de autenticado, escolha seu locatário do Azure AD selecionando-o no canto superior direito da páginaAfter you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page
  3. Selecione Azure Active Directory no menu à esquerdaSelect Azure Active Directory from the left-hand menu
  4. Na seção gerenciar , selecione registros de aplicativoUnder the Manage section, select App registrations
  5. Selecione o aplicativo para o qual você deseja configurar declarações opcionais na listaSelect the application you want to configure optional claims for in the list
  6. Na seção gerenciar , selecione configuração de token (versão prévia)Under the Manage section, select Token configuration (preview)
  7. Selecione Adicionar declaração de gruposSelect Add groups claim
  8. Selecione os tipos de grupo a serem retornados (todos os grupos, grupode segurançaou DirectoryRole).Select the group types to return (All Groups, SecurityGroup, or DirectoryRole). A opção todos os grupos inclui o grupo de segurança, DirectoryRolee DistributionListThe All Groups option includes SecurityGroup, DirectoryRole, and DistributionList
  9. Opcional: clique nas propriedades do tipo de token específico para modificar o valor da declaração grupos para conter os atributos do grupo local ou para alterar o tipo de declaração para uma funçãoOptional: 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. Clique em SalvarClick Save

Configurar declarações opcionais de grupos por meio do manifesto do aplicativo:Configuring groups optional claims through the application manifest:

  1. Entre no Portal do AzureSign in to the Azure portal

  2. Depois de autenticado, escolha seu locatário do Azure AD selecionando-o no canto superior direito da páginaAfter you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page

  3. Selecione Azure Active Directory no menu à esquerdaSelect Azure Active Directory from the left-hand menu

  4. Selecione o aplicativo para o qual você deseja configurar declarações opcionais na listaSelect the application you want to configure optional claims for in the list

  5. Na seção gerenciar , selecione manifestoUnder the Manage section, select Manifest

  6. Adicione a seguinte entrada usando o editor de manifesto:Add the following entry using the manifest editor:

    Os valores válidos são:The valid values are:

    • "All" (essa opção inclui o The Securitylist, DirectoryRole e DistributionList)"All" (this option includes SecurityGroup, DirectoryRole, and DistributionList)
    • SecurityGroup"SecurityGroup"
    • DirectoryRole"DirectoryRole"

    Por exemplo:For example:

        "groupMembershipClaims": "SecurityGroup"
    

    Por padrão, ObjectIDs de grupo serão emitidas no valor de declaração de grupo.By default Group ObjectIDs will be emitted in the group claim value. Para modificar o valor da declaração para conter os atributos do grupo local ou para alterar o tipo de declaração para função, use a configuração OptionalClaims da seguinte maneira: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. Definir declarações opcionais de configuração de nome de grupo.Set group name configuration optional claims.

    Se você quiser que os grupos no token contenham os atributos do grupo do AD local na seção declarações opcionais, especifique a qual tipo de token a declaração opcional deve ser aplicada, o nome da declaração opcional solicitada e todas as propriedades adicionais desejadas.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. Vários tipos de token podem ser listados:Multiple token types can be listed:

    • Token para o token de ID de OIDCidToken for the OIDC ID token
    • accessToken para o token de acesso do OAuth/OIDCaccessToken for the OAuth/OIDC access token
    • Saml2Token para tokens SAML.Saml2Token for SAML tokens.

    Observação

    O tipo Saml2Token aplica-se aos tokens de formato SAML 1.1 e SAML 2.0The Saml2Token type applies to both SAML1.1 and SAML2.0 format tokens

    Para cada tipo de token relevante, modifique a declaração de grupos para usar a seção OptionalClaims no manifesto.For each relevant token type, modify the groups claim to use the OptionalClaims section in the manifest. O esquema OptionalClaims é o seguinte:The OptionalClaims schema is as follows:

       {
       "name": "groups",
       "source": null,
       "essential": false,
       "additionalProperties": []
       }
    
    Esquema de declarações opcionalOptional claims schema ValorValue
    name:name: Deve ser "grupos"Must be "groups"
    originalsource: Não usado.Not used. Omitir ou especificar nuloOmit or specify null
    essential:essential: Não usado.Not used. Omitir ou especificar falseOmit or specify false
    additionalProperties:additionalProperties: Lista de propriedades adicionais.List of additional properties. As opções válidas são "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"

    Somente um de "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name" é necessário em um adicional.In additionalProperties only one of "sam_account_name", “dns_domain_and_sam_account_name”, “netbios_domain_and_sam_account_name” are required. Se mais de um estiver presente, o primeiro será usado e todos os outros serão ignorados.If more than one is present, the first is used and any others ignored.

    Alguns aplicativos exigem informações de grupo sobre o usuário na declaração de função.Some applications require group information about the user in the role claim. Para alterar o tipo de declaração para de uma declaração de grupo para uma declaração de função, adicione "emit_as_roles" a propriedades adicionais.To change the claim type to from a group claim to a role claim, add “emit_as_roles” to additional properties. Os valores de grupo serão emitidos na declaração de função.The group values will be emitted in the role claim.

    Observação

    Se "emit_as_roles" for usado, as funções de aplicativo configuradas que o usuário está atribuído não aparecerão na declaração de funçãoIf "emit_as_roles" is used any Application Roles configured that the user is assigned will not appear in the role claim

Exemplos:Examples:

  1. Emitir grupos como nomes de grupo nos tokens de acesso OAuth no formato dnsDomainName\sAMAccountNameEmit groups as group names in OAuth access tokens in dnsDomainName\sAMAccountName format

    Configuração da interface do usuário:UI configuration:

    mostra como configurar declarações opcionais usando a interface do usuárioShows how to configure optional claims using the UI

    Entrada do manifesto do aplicativo:Application manifest entry:

        "optionalClaims": {
            "accessToken": [{
            "name": "groups",
            "additionalProperties": ["dns_domain_and_sam_account_name"]
            }]
        }
    
  2. Emitir nomes de grupos a serem retornados no formato netbiosDomain\sAMAccountName como a declaração de funções em tokens de ID SAML e OIDCEmit group names to be returned in netbiosDomain\sAMAccountName format as the roles claim in SAML and OIDC ID Tokens

    Configuração da interface do usuário:UI configuration:

    mostra como configurar declarações opcionais usando a interface do usuárioShows how to configure optional claims using the UI

    Entrada do manifesto do aplicativo: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"]
        }]
    

Exemplo de declarações opcionalOptional claims example

Nesta seção, você pode examinar um cenário para ver como usar o recurso opcional de declarações para o aplicativo.In this section, you can walk through a scenario to see how you can use the optional claims feature for your application. Há várias opções disponíveis para atualizar as propriedades na configuração de identidade do aplicativo para habilitar e configurar declarações opcionais:There are multiple options available for updating the properties on an application’s identity configuration to enable and configure optional claims:

  • Você pode usar a interface do usuário de configuração de token (versão prévia) (Veja o exemplo abaixo)You can use the Token configuration (preview) UI (see example below)
  • Você pode usar o manifesto (Veja o exemplo abaixo).You can use the Manifest (see example below). Primeiro leia o documento Noções básicas sobre o manifesto do aplicativo Azure AD para obter uma introdução ao manifesto.Read the Understanding the Azure AD application manifest document first for an introduction to the manifest.
  • Também é possível escrever um aplicativo que usa a API do Graph para atualizar o aplicativo.It's also possible to write an application that uses the Graph API to update your application. O tipo OptionalClaims no guia de referência API do Graph pode ajudá-lo a configurar as declarações opcionais.The OptionalClaims type in the Graph API reference guide can help you with configuring the optional claims.

Exemplo: No exemplo a seguir, você usará a interface do usuário de configuração do token (versão prévia) e o manifesto para adicionar declarações opcionais aos tokens de acesso, ID e SAML destinados ao seu aplicativo.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. Diferentes declarações opcionais serão adicionadas a cada tipo de token que o aplicativo pode receber:Different optional claims will be added to each type of token that the application can receive:

  • Os tokens de ID agora contêm o UPN para usuários federados no formato completo (<upn>_<homedomain>#EXT#@<resourcedomain>).The ID tokens will now contain the UPN for federated users in the full form (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • Os tokens de acesso que outros clientes solicitam para esse aplicativo agora incluirão a declaração de auth_timeThe access tokens that other clients request for this application will now include the auth_time claim
  • Agora os tokens SAML contêm a extensão do esquema de diretório skypeId (neste exemplo, a ID de aplicativo para esse aplicativo é ab603c56068041afb2f6832e2a17e237).The SAML tokens will now contain the skypeId directory schema extension (in this example, the app ID for this app is ab603c56068041afb2f6832e2a17e237). Os tokens SAML vão expor a ID do Skype como extension_skypeId.The SAML tokens will expose the Skype ID as extension_skypeId.

Configuração da interface do usuário:UI configuration:

  1. Entre no Portal do AzureSign in to the Azure portal

  2. Depois de autenticado, escolha seu locatário do Azure AD selecionando-o no canto superior direito da página.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. Selecione Azure Active Directory no menu à esquerda.Select Azure Active Directory from the left-hand menu.

  4. Na seção gerenciar , selecione registros de aplicativo.Under the Manage section, select App registrations.

  5. Localize o aplicativo para o qual você deseja configurar declarações opcionais na lista e clique nele.Find the application you want to configure optional claims for in the list and click on it.

  6. Na seção gerenciar , clique em configuração de token (versão prévia) .Under the Manage section, click Token configuration (preview).

  7. Selecione Adicionar declaração opcional, selecione o tipo de token de ID , selecione UPN na lista de declarações e clique em Adicionar.Select Add optional claim, select the ID token type, select upn from the list of claims, and then click Add.

  8. Selecione Adicionar declaração opcional, selecione o tipo de token de acesso , selecione auth_time na lista de declarações e clique em Adicionar.Select Add optional claim, select the Access token type, select auth_time from the list of claims, then click Add.

  9. Na tela Visão geral da configuração do token, clique no ícone de lápis ao lado de UPN, clique na alternância autenticada externamente e, em seguida, clique em salvar.From the Token Configuration overview screen, click on the pencil icon next to upn, click the Externally authenticated toggle, and then click Save.

  10. Selecione Adicionar declaração opcional, selecione o tipo de token SAML , selecione Extn. SkypeID na lista de declarações (aplicável somente se você tiver criado um objeto de usuário do Azure AD chamado SkypeID) e, em seguida, clique em Adicionar.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.

    mostra como configurar declarações opcionais usando a interface do usuárioShows how to configure optional claims using the UI

Configuração do manifesto:Manifest configuration:

  1. Entre no portal do Azure.Sign in to the Azure portal.

  2. Depois de autenticado, escolha seu locatário do Azure AD selecionando-o no canto superior direito da página.After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. Selecione Azure Active Directory no menu à esquerda.Select Azure Active Directory from the left-hand menu.

  4. Localize o aplicativo para o qual você deseja configurar declarações opcionais na lista e clique nele.Find the application you want to configure optional claims for in the list and click on it.

  5. Na seção gerenciar , clique em manifesto para abrir o editor de manifesto embutido.Under the Manage section, click Manifest to open the inline manifest editor.

  6. Você pode editar diretamente o manifesto usando esse editor.You can directly edit the manifest using this editor. O manifesto segue o esquema para a entidade de aplicativoe formata automaticamente o manifesto depois de salvo.The manifest follows the schema for the Application entity, and automatically formats the manifest once saved. Novos elementos serão adicionados para o OptionalClaims propriedade.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.