Referência de créditos facultativos

  • Artigo

Pode utilizar as afirmações opcionais para:

  • Selecione as declarações a serem incluídas em tokens para seu aplicativo.
  • Alterar o comportamento de determinadas afirmações que a plataforma de identidades da Microsoft devolve nos tokens.
  • Adicionar e aceder a afirmações personalizadas da aplicação.

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 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.

Nota

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 a 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.

Nome Descrição Tipo de token Tipo de Utilizador Notas
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 a xms_cc reivindicaçã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 executar 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 groups declaração é 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 login_hint parâmetro OAuth 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 login_hint declaração 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, a login_hint declaração não inclui o locatário atual do usuário e usa como 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 existente login_hint do seu SDK, no entanto que ele expôs.
sid ID de sessão, usado para sair do usuário por sessão JWT Contas pessoais e Microsoft Entra.
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 username_hint parâmetro. 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 ver 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 login_hint reivindicação para login_hint uso - 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 no token de acesso é a maneira autoritativa de identificar que um aplicativo cliente é capaz de lidar com um desafio de cp1 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 email declaração.
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. LL-CC formatado ("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 AutoPiloto .

Aviso

Nunca use email ou upn reivindique valores 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 Nome Descrição Notas
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 Hora de Expiração da Palavra-Passe O número de segundos após o tempo na declaração em que a iat 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 da Empresa 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 nas configurações de IPs confiáveis 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 Utilizador Um identificador para o usuário que pode ser usado com o username_hint parâmetro. 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 ver o seu Nome Principal de Utilizador (UPN). Em vez disso, use a seguinte preferred_username declaração 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 Nome Descrição Notas
aud Audiência 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 créditos facultativos

Algumas declarações opcionais podem ser configuradas para alterar a forma como a declaração é devolvida. Eles 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 conseguem manipular marcas de hash (#) no UPN.

Nome da propriedade additionalProperty Designação Description
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 aud declaração. Essa declaração não tem efeito em tokens v2 ou tokens de ID de qualquer versão, onde a aud declaração é 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 aud declaração 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 aud declaração de , api://MyApi.com/api://myapi.com/AdditionalRegisteredField ou qualquer outro valor definido como um URI de ID de api://MyApi.comaplicativo 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 o idtyp token de declaração para 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 optionalClaims objeto faz com que o token de ID retornado ao cliente inclua uma upn declaração com as informações do outro locatário doméstico e do locatário do recurso. A upn declaração só é 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óximos passos