Compartilhar via

Referência de declarações opcionais

  • Artigo

Você pode usar declarações opcionais para:

  • Selecione declarações a serem incluídas em tokens para seu aplicativo.
  • Altere o comportamento de determinadas declarações que a plataforma de identidade da Microsoft retorna em tokens.
  • Adicione e acesse declarações personalizadas para seu aplicativo.

Embora as declarações opcionais sejam compatíveis com tokens de formato v1.0 e v2.0 e tokens SAML, elas fornecem a maior parte de seu valor ao migrar da v1.0 para a v2.0. Na plataforma de identidade da Microsoft, tamanhos de token menores são usados para garantir o desempenho ideal dos clientes. Como resultado, várias declarações anteriormente incluídas nos tokens de acesso e ID não estão mais presentes em tokens v2.0 e devem ser solicitadas especificamente por aplicativo.

Tipo de conta Tokens v1.0 Tokens v2.0
Conta pessoal da Microsoft N/A Suportado
Conta do Microsoft Entra Suportado Suportado

v1.0 e v2.0 conjunto de declarações opcionais

O conjunto de declarações opcionais disponíveis por padrão para os aplicativos usarem 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 aplicam a tokens de acesso solicitados para o aplicativo (uma API Web), não declarações solicitadas por o aplicativo. Não importa como o cliente acessa sua API, os dados certos estão presentes no token de acesso usado para autenticar em sua API.

Nota

A maioria dessas declarações pode ser incluída em JWTs para tokens v1.0 e v2.0, mas não em tokens SAML, exceto quando observado na coluna Tipo de Token. As contas de consumidor dão suporte a um subconjunto dessas declarações, marcado na coluna Tipo de Usuário. Muitas das declarações listadas não se aplicam aos usuários consumidores (eles não têm locatário, 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 Anotaçõ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 eles forem convidados, o valor será 1.
acrs IDs de contexto de autenticação JWT Microsoft Entra ID 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 se autenticou pela última vez. JWT
ctry País/região do usuário JWT Essa declaração será retornada se ela estiver presente e o valor do campo for um código de país/região de duas letras padrão, como FR, JP, SZ e assim por diante.
email O endereço de email relatado para este usuário JWT, SAML MSA, Microsoft Entra ID Esse valor será incluído por padrão se o usuário for 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 v2.0, com o escopo OpenID. Esse valor não tem garantia de estar correto e é mutável ao longo do tempo - nunca use-o para autorização ou para salvar dados para um usuário. Para obter mais informações, consulte 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 essa declaração como sugestão ou pré-arquivo em seu UX.
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 deve ser definido.
idtyp Tipo de token Tokens de acesso JWT Especial: somente em tokens de acesso somente de aplicativo O valor é app quando o token é um token somente de aplicativo. Essa declaraçã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, Microsoft Entra ID Uma declaração de dica de logon opaca e confiável que é codificada em base 64. Não modifique esse 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. Ele pode ser passado entre aplicativos para ajudá-los silenciosamente SSO também – o aplicativo A pode entrar em um usuário, ler a declaração login_hint e, em seguida, enviar a declaração e o contexto de locatário atual para o aplicativo B na cadeia de caracteres de consulta ou fragmento quando o usuário seleciona em um link que os leva para o aplicativo B. Para evitar problemas de confiabilidade e condições de corrida, o login_hint declaração não incluir o locatário atual para o usuário e o padrão para 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 passe o mesmo para aplicativos com os quais você faz parceria. Essa declaração destina-se a ser usada com a funcionalidade de login_hint existente do SDK, no entanto, que ela expôs.
tenant_ctry País/região do locatário do recurso JWT O mesmo que ctry, exceto 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 autorização ou para identificar exclusivamente informações do usuário (por exemplo, como uma chave de banco de dados). Em vez disso, use a ID do objeto de usuário (oid) como uma chave de banco de dados. Para obter mais informações, consulte Aplicativos seguros e APIs validando declarações. Os usuários que entrarem com uma ID de logon alternativa não devem ser mostrados no UPN (Nome de Entidade de Usuário). 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 outras propriedades para modificar seu comportamento no caso do usuário convidado. Você deve usar a declaração login_hint para uso login_hint - identificadores legíveis por humanos, como UPN, não são confiáveis.
verified_primary_email Originado do PrimaryAuthoritativeEmail do usuário JWT
verified_secondary_email Originado do SecondaryAuthoritativeEmail do usuário JWT
vnet Informações do especificador da VNET. JWT
xms_cc Funcionalidades do cliente JWT Microsoft Entra ID Indica se o aplicativo cliente que adquiriu o token é capaz de lidar com desafios de declarações. Geralmente, ele é usado junto com acrsde declaração. Essa declaração é comumente usada em cenários de Acesso Condicional e Avaliação de Acesso Contínuo. 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, consulte 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 da Microsoft (MSA), uma conta do Google ou usado para autenticação usando o fluxo de senha única (OTP). Contas do Facebook e SAML/WS-Fed não têm domínios verificados. Para que essa declaração seja retornada no token, a presença da declaração email é necessária.
xms_pdl Local de dados preferencial JWT Para locatários multigeográficos, o local de dados preferencial é o código de três letras mostrando 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 preferencial do usuário JWT O idioma preferencial do usuário, se definido. Originado de seu locatário de casa, em cenários de acesso de convidado. LL-CC formatado ("en-us").
xms_tpl Idioma preferencial do locatário JWT O idioma preferencial do locatário do recurso, se definido. LL formatada ("en").
ztdid ID de implantação de toque zero JWT A identidade do dispositivo usada para Windows AutoPilot.

Aviso

Nunca use email ou upn valores de declaração para armazenar ou determinar se o usuário em um token de acesso deve ter acesso aos dados. Valores de declaração mutáveis 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 da v2.0

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

Declaração JWT Nome Descrição Anotações
ipaddr Endereço IP O endereço IP do qual o cliente fez logon.
onprem_sid Identificador de segurança local
pwd_exp Hora de 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 de Senha Uma URL que o usuário pode visitar 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 Sinaliza se o cliente está fazendo logon na rede corporativa. Se não estiverem, a declaração não será incluída. Com base nas configurações de de IPs confiáveis na MFA.
family_name Apelido Fornece o sobrenome, sobrenome ou nome de família do usuário, conforme definido no objeto de usuário. Por exemplo, "family_name":"Miller". Com suporte no MSA e na ID do Microsoft Entra. Requer o escopo profile.
given_name Nome próprio Fornece o nome primeiro ou "fornecido" do usuário, conforme definido no objeto de usuário. Por exemplo, "given_name": "Frank". Com suporte no MSA e na ID do Microsoft Entra. Requer o escopo profile.
upn Nome da entidade de usuário 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 autorização ou para identificar exclusivamente informações do usuário (por exemplo, como uma chave de banco de dados). Para obter mais informações, consulte Aplicativos seguros e APIs validando declarações. Em vez disso, use a ID do objeto de usuário (oid) como uma chave de banco de dados. Os usuários que entrarem com uma ID de logon alternativa não devem ser mostrados no UPN (Nome de Entidade de Usuário). Em vez disso, use a declaração de preferred_username a seguir para exibir o estado de entrada para o usuário. Requer o escopo profile.

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

Algumas das melhorias do formato de token v2 estão disponíveis para aplicativos que usam o formato de token v1, pois ajudam a melhorar a segurança e a confiabilidade. Essas melhorias se aplicam apenas a JWTs, não a tokens SAML.

Declaração JWT Nome Descrição Anotações
aud Público Sempre presente em JWTs, mas em tokens de acesso v1 ele pode ser emitido de várias maneiras - qualquer URI appID, com ou sem uma barra à direita e a ID do cliente do recurso. Essa randomização pode ser difícil de codificar ao executar a validação de token. Use additionalProperties para essa declaração para garantir que ela esteja sempre definida como a ID do cliente do recurso em tokens de acesso v1. Somente tokens de acesso JWT v1
preferred_username Nome de usuário preferencial Fornece a declaração de nome de usuário preferencial em tokens v1. Essa declaração facilita que os aplicativos forneçam dicas de nome de usuário e mostrem nomes de exibição legíveis por humanos, independentemente do tipo de token. É recomendável que você use essa declaração opcional em vez de usar, upn ou unique_name. Tokens de ID v1 e tokens de acesso

additionalProperties de declarações opcionais

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

Nome da propriedade additionalProperty nome Descrição
upn Pode ser usado para respostas SAML e JWT e para tokens v1.0 e v2.0.
include_externally_authenticated_upn Inclui o UPN convidado, conforme armazenado no locatário do recurso. Por exemplo, foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Igual ao listado anteriormente, exceto que as marcas de hash (#) são substituídas por sublinhados (_), por exemplo, foo_hometenant.com_EXT_@resourcetenant.com.
aud Em tokens de acesso v1, essa declaração é usada para alterar o formato da declaração de aud. Essa declaração não tem efeito em tokens v2 ou tokens de ID da versão, em que a declaração aud é sempre a ID do cliente. Use essa configuração para garantir que sua API possa executar mais facilmente a validação de audiência. Como todas as declarações opcionais que afetam o token de acesso, o recurso na solicitação deve definir essa declaração opcional, já que os recursos possuem o 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 sua 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 poderia 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 de ID do aplicativo para essa API e a ID do cliente do recurso.
idtyp Essa declaração é usada para obter o tipo de token (aplicativo, usuário, dispositivo). Por padrão, ele só é emitido para tokens somente de aplicativo. Como todas as declarações opcionais que afetam o token de acesso, o recurso na solicitação deve definir essa declaração opcional, já que os recursos possuem o token de acesso.
include_user_token Emite a declaração 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.

additionalProperties exemplo

"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 outras informações de locatário e locatário de recurso. A declaração upn só será alterada no token se o usuário for um convidado no locatário (que usa um IDP diferente para autenticação).

Consulte também

Próximas etapas