Referência de declarações opcionais

  • Artigo

Você pode usar declarações opcionais para:

  • Selecione declarações para incluir nos tokens para o seu aplicativo.
  • Altere o comportamento de determinadas declarações retornadas em tokens pela plataforma de identidade da Microsoft.
  • Adicione e acesse as declarações personalizadas para o aplicativo.

Embora as declarações opcionais sejam compatíveis com os tokens de formato v1.0 e v2.0, bem como os tokens SAML, elas têm mais valor quando mudam de v1.0 para v2.0. Na plataforma de identidade da Microsoft, tamanhos de token menores são usados para garantir um desempenho ideal dos clientes. 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.

Tipo de Conta Tokens v1.0 Tokens v2.0
Conta pessoal da Microsoft N/D Com suporte
Conta do Microsoft Entra Com suporte Com suporte

Conjunto de declarações opcionais v 1.0 e v 2.0

O conjunto de declarações opcionais disponíveis por padrão para uso dos aplicativos está listado na tabela a seguir. Você pode usar dados personalizados em atributos de extensão e extensões de diretório para adicionar declarações opcionais para seu aplicativo. Quando você adiciona declarações ao token de acesso, as declarações se aplicarão aos tokens de acesso solicitados para o aplicativo (uma API Web) e não às declarações solicitadas pelo aplicativo. Não importa como o cliente acesse sua API, os dados corretos estão presentes no token de acesso que é usado para autenticar na sua 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. As contas de consumidor dão suporte a um subconjunto dessas declarações, marcadas na coluna Tipo de Usuário. Muitas das declarações listadas não se aplicam aos usuários do consumidor ( eles não têm locatários e, portanto, tenant_ctry não tem valor).

A tabela a seguir lista o conjunto de declarações opcionais v1.0 e v2.0.

Nome Descrição Tipo de token Tipo de Usuário Observações
acct Status da conta de usuários no locatário JWT, SAML Se o usuário for um membro do locatário, o valor será 0. Se for um convidado, o valor será 1.
acrs IDs de contexto de autenticação JWT ID do Microsoft Entra Indica as IDs de Contexto de Autenticação das operações que o portador está qualificado para executar. As IDs de Contexto de Autenticação podem ser usadas para disparar uma demanda por autenticação passo a passo de dentro de seu aplicativo e serviços. Geralmente usado junto com a declaração xms_cc.
auth_time Hora em que o usuário foi autenticado pela última vez. JWT
ctry País/região do usuário JWT A declaração é retornada se ela estiver presente, e o valor do campo é um código de país/região padrão de duas letras, como FR, JP, SZ etc.
email O endereço de email relatado para este usuário JWT, SAML MSA, ID do Microsoft Entra Esse valor é incluído por padrão, se o usuário é um convidado no locatário. Para usuários gerenciados (os usuários dentro do locatário), ele deve ser solicitado por meio dessa declaração opcional ou, somente na versão 2.0, com o escopo do OpenID. Não há garantia de que este valor esteja correto e ele pode ser alterado ao longo do tempo – nunca o use para a autorização ou para salvar dados de um usuário. Para obter mais informações, confira Validar se o usuário tem permissão para acessar esses dados. Se você estiver usando a declaração de email para autorização, recomendamos executar uma migração para migrar para uma declaração mais segura. Se você precisar de um endereço de email endereçável em seu aplicativo, solicite esses dados diretamente ao usuário usando esta declaração como uma sugestão ou preenchendo sua experiência do usuário.
fwd Endereço IP JWT Adiciona o endereço original do cliente solicitante (quando dentro de uma VNET).
groups Formatação opcional para declarações de grupo JWT, SAML A declaração groups é usada com a configuração GroupMembershipClaims no manifesto do aplicativo, que também precisa ser definido.
idtyp Tipo de token Tokens de acesso JWT Especial: apenas em tokens de acesso somente de aplicativo O valor é app quando o token é um token somente de aplicativo. Essa instrução é a maneira mais precisa para uma API determinar se um token é um token de aplicativo ou um token de aplicativo + usuário.
login_hint Dica de logon JWT MSA, ID do Microsoft Entra Uma declaração de dica de logon opaca e confiável que é codificada em base 64. Não modifique este valor. Essa declaração é o melhor valor a ser usado para o parâmetro OAuth login_hint em todos os fluxos para obter o SSO. Ela também pode ser passada entre aplicativos para ajudar a fazer o SSO silenciosamente – o aplicativo A poderá conectar um usuário, ler a declaração login_hint e enviá-la juntamente com o contexto do locatário atual para o aplicativo B na cadeia de caracteres de consulta, ou fragmento, quando o usuário selecionar um link que o direcionar para o aplicativo B. Para evitar condições de corrida e problemas de confiabilidade, a declaração login_hintnão inclui o locatário atual para o usuário, e o padrão é o locatário residencial do usuário quando usado. Em um cenário de convidado em que o usuário é de outro locatário, um identificador de locatário deve ser fornecido na solicitação de entrada. e passar o mesmo para aplicativos com os quais você faz parceria. Essa declaração deve ser usada com a funcionalidade login_hint existente de seu SDK, independentemente de sua exposição.
sid ID da sessão, usada para saída do usuário por sessão JWT Contas pessoais e do Microsoft Entra.
tenant_ctry País/região do locatário do recurso JWT Igual a ctry, mas definido em um nível de locatário por um administrador. Também deve ser um valor padrão de duas letras.
tenant_region_scope Região do locatário do recurso JWT
upn UserPrincipalName JWT, SAML Um identificador para o usuário que pode ser usado com o parâmetro username_hint . Não é um identificador durável para o usuário e não deve ser usado para autorizar ou identificar exclusivamente as informações do usuário (por exemplo, como uma chave de banco de dados). Em vez disso, use a ID de objeto de usuário (oid) como uma chave de banco de dados. Para obter mais informações, consulte Proteger aplicativos e APIs validando declarações. Os usuários que se conectam com uma ID de logon alternativa não devem ver o próprio nome UPN. Em vez disso, use as seguintes declarações de token de ID para exibir o estado de entrada para o usuário: preferred_username ou unique_name para tokens v1 e preferred_username para tokens v2. 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. Você deve usar a declaração login_hint para uso de login_hint – identificadores legíveis como UPN não são confiáveis.
verified_primary_email Originado de PrimaryAuthoritativeEmail do usuário JWT
verified_secondary_email Originado de SecondaryAuthoritativeEmail do usuário JWT
vnet Informações de especificador de VNET. JWT
xms_cc Recursos do cliente JWT ID do Microsoft Entra Indica se o aplicativo cliente que adquiriu o token conseugue lidar com desafios de declarações. Geralmente, ele é usado junto com a declaração acrs. Essa declaração é comumente usada em cenários de Acesso condicional e Avaliação contínua de acesso. O servidor de recursos ou o aplicativo de serviço que o token é emitido para controlar a presença dessa declaração em um token. Um valor de cp1 no token de acesso é a maneira autoritativa de identificar que um aplicativo cliente é capaz de lidar com um desafio de declarações. Para obter mais informações, confira Desafios de declarações, solicitações de declarações e recursos de cliente.
xms_edov Valor booliano que indica se o proprietário do domínio de email do usuário foi verificado. JWT Um email é considerado como domínio verificado se ele pertence ao locatário onde reside a conta de usuário e o administrador do locatário fez a verificação do domínio. Além disso, o email deve ser de uma conta Microsoft (MSA), uma conta do Google ou usado para autenticação usando o fluxo de senha única (OTP). As contas do Facebook e SAML/WS-Fed não têm domínios verificados. Para que essa declaração seja retornada no token, é necessária a presença da declaração email.
xms_pdl Local dos dados preferido JWT Para locatários de várias regiões geográficas, o local de dados preferencial é o código de três letras que mostra a região geográfica em que o usuário está. Para obter mais informações, consulte a Documentação do Microsoft Entra Connect sobre o local de dados preferencial.
xms_pl Idioma preferido do usuário JWT O idioma preferido do usuário, se definido. Originado de seu locatário inicial, em cenários de acesso de convidado. Tem o formato II-PP ("en-us").
xms_tpl Idioma preferido do locatário JWT O idioma preferido do locatário do recurso, se definido. Com o formato II (“en”).
ztdid ID de implantação de zero toque JWT A identidade do dispositivo usada para Windows AutoPilot.

Aviso

Nunca use os valores de declaração email ou upn para determinar se o usuário em um token de acesso deve ter acesso aos dados. Valores mutáveis de declaração como esses podem mudar ao longo do tempo, tornando-os inseguros e não confiáveis para autorização.

Conjunto de declarações opcionais específicas v2.0

Essas declarações são sempre incluídas em tokens da v1.0, mas não em tokens da v2.0, a menos que solicitado. Essas declarações só são aplicáveis a JWTs (tokens de ID e tokens de acesso).

Declaração JWT Nome Descrição Observações
ipaddr Endereço IP O endereço IP com o qual o cliente se conectou.
onprem_sid Identificador de Segurança Local
pwd_exp Hora da Expiração da Senha O número de segundos após o tempo na declaração iat em que a senha expira. Essa declaração só será incluída quando a senha expirar em breve (conforme definido por "dias de notificação" na política de senha).
pwd_url Alterar URL da Senha Uma URL que o usuário pode acessar para alterar sua senha. Essa declaração só será incluída quando a senha expirar em breve (conforme definido por "dias de notificação" na política de senha).
in_corp Dentro da Rede Corporativa Indica se o cliente está se conectando da rede corporativa. Se não estiver, a declaração não será incluída. Baseado nas configurações de IPs confiáveis na Autenticação Multifator.
family_name Sobrenome Fornece o sobrenome do usuário, conforme definido no objeto do usuário. Por exemplo, "family_name":"Miller". Compatível com MSA e ID do Microsoft Entra. Requer o escopo de profile.
given_name Nome Fornece o nome ou nome “especificado” do usuário, conforme definido no objeto de usuário. Por exemplo, "given_name": "Frank". Compatível com MSA e ID do Microsoft Entra. Requer o escopo de profile.
upn Nome UPN Um identificador para o usuário que pode ser usado com o parâmetro username_hint . Não é um identificador durável para o usuário e não deve ser usado para autorizar ou identificar exclusivamente as informações do usuário (por exemplo, como uma chave de banco de dados). Para obter mais informações, consulte Proteger aplicativos e APIs validando declarações. Em vez disso, use a ID de objeto de usuário (oid) como uma chave de banco de dados. Os usuários que se conectam com uma ID de logon alternativa não devem ver o próprio nome UPN. Em vez disso, use a declaração preferred_username a seguir para exibir o estado de entrada para o usuário. Requer o escopo de profile.

Conjunto de declarações opcionais específicas da v1.0

Alguns dos aprimoramentos do formato de token v2 estão disponíveis para os aplicativos que usam o formato de token v1, pois ajudam a aprimorar a segurança e a confiabilidade. Esses aprimoramentos só se aplicam aos JWTs, não aos tokens SAML.

Declaração JWT Nome Descrição Observações
aud Público Sempre presente nos JWTs, mas nos tokens de acesso v1, ela pode ser emitida de várias maneiras: qualquer URI de appID, com ou sem uma barra "/" à direita, bem como a ID do cliente do recurso. Essa aleatoriedade pode ser difícil de ser embutida em código ao executar a validação de token. Use additionalProperties nesta declaração para garantir que ela seja sempre definida como a ID do cliente do recurso em tokens de acesso v1. Somente tokens de acesso JWT da v1
preferred_username Nome de usuário preferencial Fornece a declaração de nome de usuário preferencial nos tokens v1. Essa declaração facilita para os aplicativos fornecer dicas de nome de usuário e mostrar nomes de exibição legíveis, independentemente do tipo de token. Recomendamos que você use essa declaração opcional em vez de usar, por exemplo, upn ou unique_name. Tokens de ID e tokens de acesso v1

additionalProperties de declarações opcionais

Algumas declarações opcionais podem ser configuradas para alterar o modo como a declaração é retornada. Essas additionalProperties são usadas principalmente para ajudar na migração de aplicativos locais com diferentes expectativas de dados. Por exemplo, include_externally_authenticated_upn_without_hash ajuda com os clientes que não podem processar marcas de hash (#) no UPN.

Nome da propriedade nome de additionalProperty Descrição
upn Pode ser usada para respostas SAML e JWT e para tokens v1.0 e v2.0.
include_externally_authenticated_upn Inclui o UPN de convidado conforme armazenado no locatário do recurso. Por exemplo, foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Igual ao que foi listado anteriormente, exceto que as marcas de jogo da velha (#) são substituídas por sublinhados (_), por exemplo foo_hometenant.com_EXT_@resourcetenant.com.
aud Nos tokens de acesso v1, essa declaração é usada para alterar o formato da declaração aud. Essa declaração não tem efeito nos tokens v2 nem nos tokens de ID de qualquer uma das versões, em que a declaração aud é sempre a ID do cliente. Use essa configuração para garantir que sua API possa realizar a validação de público com mais facilidade. Assim como todas as declarações opcionais que afetam o token de acesso, o recurso na solicitação precisa definir essa declaração opcional, pois os recursos são os proprietários do token de acesso.
use_guid Emite a ID do cliente do recurso (API) no formato GUID como a declaração aud sempre, em vez de ser dependente do runtime. Por exemplo, se um recurso definir esse sinalizador e a ID do cliente for 00001111-aaaa-2222-bbbb-3333cccc4444, qualquer aplicativo que solicite um token de acesso para esse recurso receberá um token de acesso com aud: 00001111-aaaa-2222-bbbb-3333cccc4444. Sem esse conjunto de declarações, uma API pode obter tokens com uma declaração aud de api://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField ou qualquer outro valor definido como um URI da ID do aplicativo para essa API, bem como a ID do cliente do recurso.
idtyp Essa declaração é usada para obter o tipo de token (aplicativo, usuário, dispositivo). Por padrão, ela só é emitida para tokens somente de aplicativo. Assim como todas as declarações opcionais que afetam o token de acesso, o recurso na solicitação precisa definir essa declaração opcional, pois os recursos são os proprietários do token de acesso.
include_user_token Emite a declaração de idtyp para o token de usuários. Sem essa propriedade adicional opcional para o conjunto de declarações idtyp, uma API só obtém a declaração de tokens de aplicativo.

Exemplo do additionalProperties

"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 uma declaração upn com as informações adicionais sobre o locatário inicial e o locatário do recurso. A declaração de upn somente é alterada no token se o usuário é um convidado no locatário (que usa um IDP diferente para autenticação).

Confira também

Próximas etapas