Partilhar via

Referência de créditos facultativos

  • Artigo

Você pode usar declarações opcionais para:

  • Selecione as 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 suportadas em tokens de formato v1.0 e v2.0 e tokens SAML, eles fornecem a maior parte de seu valor ao mover de v1.0 para v2.0. Na plataforma de identidade da Microsoft, tamanhos de token menores são usados para garantir o desempenho ideal pelos clientes. Como resultado, várias declarações anteriormente incluídas nos 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/A Suportado
Conta Microsoft Entra Suportado Suportado

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

O conjunto de declarações opcionais disponíveis por padrão para 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 aos tokens de acesso solicitados para o aplicativo (uma API da Web), não às declarações solicitadas pelo o aplicativo. Não importa como o cliente acessa sua API, os dados corretos estão presentes no token de acesso usado para autenticar em 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 tokens SAML, exceto quando observado na coluna Tipo de Token. As contas de consumidor suportam um subconjunto dessas declarações, marcadas na coluna Tipo de usuário. Muitas das reclamações listadas não se aplicam aos usuários consumidores (eles não têm inquilino, portanto, tenant_ctry não tem valor).

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

Designação Descrição Tipo de token Tipo de Utilizador 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 hóspede, o valor é 1.
acrs IDs de contexto de autenticação JWT Microsoft Entra ID Indica os IDs de contexto de autenticação das operações que o portador está qualificado para executar. Os IDs de contexto de autenticação podem ser usados para disparar uma demanda de autenticação step-up de dentro de seu aplicativo e serviços. Muitas vezes usado junto com o xms_cc alegação.
auth_time Hora em que o usuário se autenticou pela última vez. JWT
ctry País/região do utilizador JWT Essa declaração é retornada se estiver presente e o valor do campo for um código padrão de país/região de duas letras, como FR, JP, SZ e assim por diante.
email O endereço de e-mail relatado para este usuário JWT, SAML MSA, Microsoft Entra ID Esse valor é 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. Não é garantido que esse valor esteja 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 que o usuário tem permissão para acessar esses dados. Se você estiver usando a declaração de e-mail para autorização, recomendamos executando uma migração para mover para uma declaração mais segura. Se você precisar de um endereço de e-mail endereçável em seu aplicativo, solicite esses dados diretamente ao usuário, usando essa declaração como uma sugestão ou pré-preencha sua 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 definida.
idtyp Tipo de token Tokens de acesso JWT Especial: apenas em tokens de acesso somente para aplicativos O valor é app quando o token é um token somente de aplicativo. Essa declaração é a maneira mais precisa de uma API determinar se um token é um token de aplicativo ou um token de aplicativo+usuário.
login_hint Dica de login JWT MSA, Microsoft Entra ID Uma alegação de dica de login opaca e confiável que é codificada na 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 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 de 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 ao aplicativo B. Para evitar condições de corrida e problemas de confiabilidade, o de declaração de login_hint não inclui o locatário atual do usuário e o padrão é o locatário doméstico 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. Esta declaração destina-se a ser usada com a funcionalidade de login_hint existente do seu SDK, independentemente de ter sido exposta.
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 o ID do objeto do usuário (oid) como uma chave de banco de dados. Para obter mais informações, consulte Proteger aplicativos e APIs validando declarações. Os utilizadores que iniciam sessão com um ID de início de sessão alternativo não devem ser mostrados o seu Nome Principal de Utilizador (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 outras propriedades para modificar seu comportamento no caso do usuário convidado. Você deve usar a declaração de 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 VNET. JWT
xms_cc Capacidades do cliente JWT Microsoft Entra ID Indica se o aplicativo cliente que adquiriu o token é capaz de lidar com desafios de declarações. É frequentemente usado juntamente com a reivindicação acrs. Essa declaração é comumente usada em cenários de Acesso Condicional e Avaliação de Acesso Contínuo. O servidor de recursos ou aplicativo de serviço para o qual o token é emitido controla a presença dessa declaração em um token. Um valor de cp1 no token de acesso é a maneira autorizada 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 do cliente.
xms_edov Valor booleano que indica se o proprietário do domínio de e-mail do usuário foi verificado. JWT Um e-mail é considerado domínio verificado se pertencer ao locatário onde a conta de usuário reside e o administrador do locatário tiver feito a verificação do domínio. Além disso, o e-mail deve ser de uma conta da Microsoft (MSA), uma conta do Google ou usado para autenticação usando o fluxo de código de acesso único (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 Localização de dados preferida JWT Para locatários Multi-Geo, o local de dados preferido é 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 preferido.
xms_pl Língua preferida do utilizador JWT O idioma preferido do usuário, se definido. Originado de seu inquilino doméstico, em cenários de acesso de convidado. Formatado LL-CC ("en-us").
xms_tpl Idioma preferido do locatário JWT O idioma preferido do locatário de recurso, se definido. LL formatado ("en").
ztdid ID de implantação zero-touch JWT A identidade do dispositivo usada para Windows AutoPilot.

Advertência

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 reivindicaçã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 nos tokens v1.0, mas não são incluídas nos tokens v2.0, a menos que sejam solicitadas. Essas declarações só são aplicáveis para JWTs (tokens de ID e tokens de acesso).

Reivindicação JWT Designação Descrição Observações
ipaddr Endereço IP O endereço IP a partir do qual o cliente iniciou sessão.
onprem_sid Identificador de segurança local
pwd_exp Tempo de expiração da palavra-passe O número de segundos após o tempo na declaração de iat em que a senha expira. Essa declaração só é incluída quando a senha está expirando em breve (conforme definido por "dias de notificação" na política de senha).
pwd_url Alterar URL da palavra-passe Um URL que o usuário pode visitar para alterar sua senha. Essa declaração só é incluída quando a senha está expirando 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 login a partir da rede corporativa. Se não estiverem, a reivindicação não está incluída. Com base no IPs confiáveis configurações no 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". Suportado em MSA e Microsoft Entra ID. Requer o profile escopo.
given_name Nome próprio Fornece o primeiro nome ou "dado" do usuário, conforme definido no objeto de usuário. Por exemplo, "given_name": "Frank". Suportado em MSA e Microsoft Entra ID. Requer o profile escopo.
upn Nome Principal do 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 Proteger aplicativos e APIs validando declarações. Em vez disso, use o ID do objeto do usuário (oid) como uma chave de banco de dados. Os utilizadores que iniciam sessão com um ID de início de sessão alternativo não devem ser mostrados o seu Nome Principal de Utilizador (UPN). Em vez disso, use a seguinte declaração de preferred_username para exibir o estado de entrada para o usuário. Requer o profile escopo.

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 só se aplicam a JWTs, não a tokens SAML.

Reivindicação JWT Designação Descrição Observações
aud Público-alvo Sempre presente em JWTs, mas em tokens de acesso v1 pode ser emitido de várias maneiras - qualquer URI appID, com ou sem uma barra à direita, e o 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. v1 Somente tokens de acesso JWT
preferred_username Nome de utilizador preferido Fornece a declaração de nome de usuário preferencial em tokens v1. Essa afirmação torna mais fácil para os aplicativos fornecer dicas de nome de usuário e mostrar 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 pedidos facultativos

Algumas declarações opcionais podem ser configuradas para alterar a forma como a declaração é devolvida. 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 manipular 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 como armazenado no locatário do recurso. Por exemplo, foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash O mesmo que listado anteriormente, exceto que as marcas de hash (#) 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 de aud. Essa declaração não tem efeito em tokens v2 ou tokens de ID de qualquer versão, onde 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 público. Como todas as declarações opcionais que afetam o token de acesso, o recurso na solicitação deve definir essa declaração opcional, uma vez 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 tempo de execução. Por exemplo, se um recurso definir esse sinalizador e sua ID de cliente for 00001111-aaaa-2222-bbbb-3333cccc4444, qualquer aplicativo que solicitar 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 de 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, uma vez que os recursos possuem o 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 obtém apenas a declaração para 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 de upn com as informações do outro locatário doméstico e do locatário do recurso. A declaração upn só é alterada no token se o usuário for um convidado no locatário (que usa um IDP diferente para autenticação).

Ver também

Próximos passos