Referência de declarações do token de ID

Artigo
10/25/2023

Os tokens de ID são JWT (tokens de Web JSON). Os tokens de ID v1.0 e v2.0 têm diferenças nas informações que eles carregam. A versão é baseada no ponto de extremidade da solicitação. Embora os aplicativos existentes provavelmente usem o ponto de extremidade do Azure AD v1.0, os novos aplicativos devem usar o ponto de extremidade v2.0.

v1.0: https://login.microsoftonline.com/common/oauth2/authorize
v2.0: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Todas as declarações JWT listadas nas seções a seguir aparecem nos tokens v1.0 e v2.0, a menos que seja indicado o contrário. Tokens de ID consistem em um cabeçalho, um conteúdo e uma assinatura. O cabeçalho e a assinatura são usados para verificar a autenticidade do token, enquanto o conteúdo tem informações sobre o usuário solicitado pelo cliente.

Declarações de cabeçalho

A seguinte tabela mostra declarações de cabeçalho presentes em tokens de ID.

Declaração	Formatar	Descrição
`typ`	Cadeia de caracteres – sempre "JWT"	Indica que o token é um token JWT.
`alg`	String	Indica o algoritmo que foi usado para assinar o token. Por exemplo: "RS256"
`kid`	String	Especifica a impressão digital da chave pública que pode ser usada para validar a assinatura do token. Emitido nos tokens de ID v1.0 e v2.0.
`x5t`	String	Funciona da mesma forma (em uso e valor) que `kid`. `x5t` é uma declaração herdada emitida somente em tokens de ID da v1.0 para fins de compatibilidade.

Declarações de conteúdo

A seguinte tabela mostra as declarações que estão na maioria dos tokens de ID por padrão (exceto quando indicado). No entanto, o aplicativo pode usar declarações opcionais para solicitar mais declarações token de ID. As declarações opcionais podem ser desde uma declaração groups até informações sobre o nome de usuário.

Declaração	Formatar	Descrição
`aud`	Cadeia de caracteres, um GUID da ID do Aplicativo	Identifica o destinatário pretendido do token. Em `id_tokens`, o público-alvo é a ID de Aplicativo de seu aplicativo, atribuída a ele no portal do Azure. Este valor deve ser validado. O token deverá ser rejeitado se não corresponder à ID de Aplicativo do seu aplicativo.
`iss`	Cadeia de caracteres, um URI do emissor	Identifica o emissor ou o "servidor de autorização" que constrói e retorna o token. Ela também identifica o locatário para o qual o usuário foi autenticado. Se o token tiver sido emitido pelo ponto de extremidade v2.0, o URI termina em `/v2.0`. O GUID que indica que o usuário é um consumidor da conta da Microsoft é `9188040d-6c67-4c5b-b112-36a304b66dad`. O aplicativo deve usar a parte do GUID da declaração para restringir o conjunto de locatários que podem entrar no aplicativo, se aplicável.
`iat`	int, um carimbo de data/hora Unix	Indica quando ocorreu a autenticação desse token.
`idp`	Cadeia de caracteres, normalmente um URI de STS	Registra o provedor de identidade que autenticou a entidade do token. Esse valor é idêntico ao valor da declaração do emissor, a menos que a conta de usuário não esteja no mesmo locatário que o emissor - convidados, por exemplo. Se a declaração não estiver presente, isso significará que o valor de `iss` poderá ser usado. Para as contas pessoais usadas em um contexto organizacional (por exemplo, uma conta pessoal convidada para um locatário), a declaração `idp` pode ser 'live.com' ou um URI de STS que contém o locatário `9188040d-6c67-4c5b-b112-36a304b66dad` da conta Microsoft.
`nbf`	int, um carimbo de data/hora Unix	Identifica o horário antes do qual o JWT não pode ser aceito para processamento.
`exp`	int, um carimbo de data/hora Unix	Identifica o horário de expiração ou o horário após o qual o JWT não pode ser aceito para processamento. Em determinadas circunstâncias, um recurso pode rejeitar o token antes deste horário. Por exemplo, se for necessária uma alteração na autenticação ou se uma revogação de token tiver sido detectada.
`c_hash`	String	O hash de código é incluído em tokens de ID apenas quando eles são emitidos com um código de autorização OAuth 2.0. Ele pode ser usado para validar a autenticidade de um código de autorização. Para entender como fazer essa validação, confira a especificação do OpenID Connect. Esta declaração não é retornada nos tokens de ID do ponto de extremidade.
`at_hash`	String	O hash do token de acesso é incluído em tokens de ID apenas quando eles são emitidos do ponto de extremidade `/authorize` com um token de acesso OAuth 2.0. Ele pode ser usado para validar a autenticidade de um token de acesso. Para entender como fazer essa validação, confira a especificação do OpenID Connect. Esta declaração não é retornada nos tokens de ID do ponto de extremidade `/token`.
`aio`	Cadeia de caracteres opaca	Uma declaração interna que tem o costume de registrar os dados para reutilização de token. Deve ser ignorado.
`preferred_username`	String	O nome de usuário principal que representa o usuário. Ele pode ser um endereço de email, número de telefone ou nome de usuário genérico sem um formato especificado. Seu valor é mutável e pode ser alterado ao longo do tempo. Uma vez que é mutável, esse valor não pode ser usado para tomar decisões de autorização. Ele pode ser usado para dicas de nome de usuário e na interface do usuário legível como um nome de usuário. O escopo `profile` é necessário para receber essa declaração. Presente apenas em tokens v 2.0.
`email`	String	Presente por padrão para contas de convidados que tenham um endereço de email. Seu aplicativo pode solicitar a declaração de email para usuários gerenciados (do mesmo locatário que o recurso) usando a `email` declaração opcional. Não há garantia de 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. 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 previamente em sua experiência do usuário. No ponto de extremidade v 2.0, seu aplicativo também pode solicitar o `email` escopo da OpenID Connect - você não precisa solicitar a declaração opcional e o escopo para obter a declaração.
`name`	String	A declaração `name` fornece um valor legível por humanos que identifica o assunto do token. Não há garantia de que o valor seja exclusivo, ele pode ser alterado e deve ser usado apenas para fins de exibição. O escopo `profile` é necessário para receber essa declaração.
`nonce`	String	O nonce corresponde ao parâmetro incluído na solicitação de autorização original para o IDP. Se não corresponder, seu aplicativo deverá rejeitar o token.
`oid`	Cadeia de caracteres, um GUID	O identificador imutável de um objeto, neste caso, uma conta de usuário. Essa ID identifica o usuário de forma exclusiva em todos os aplicativos - dois aplicativos diferentes que fazem logon no mesmo usuário recebem o mesmo valor na declaração `oid`. O Microsoft Graph retorna essa ID como a propriedade `id` de uma conta de usuário. Como o `oid` permite que vários aplicativos correlacionem usuários, o escopo `profile` é necessário para receber essa declaração. Se um único usuário existir em vários locatários, o usuário contém uma ID de objeto diferente em cada locatário - elas são consideradas contas diferentes, mesmo que o usuário faça logon em cada conta com as mesmas credenciais. A declaração `oid` é um GUID e não pode ser reutilizada.
`roles`	Matriz de cadeia de caracteres	O conjunto de funções que foram atribuídas ao usuário que está fazendo logon.
`rh`	Cadeia de caracteres opaca	Uma declaração interna usada para revalidar tokens. Deve ser ignorado.
`sub`	String	A entidade das informações no token. Por exemplo, o usuário de um aplicativo. Esse valor é imutável e não pode ser reatribuído nem reutilizado. A entidade é um identificador de pares e é exclusiva de uma ID de aplicativo. Se um único usuário entrar em dois aplicativos diferentes usando duas IDs de cliente diferentes, esses aplicativos recebem dois valores diferentes para a declaração da entidade. Você pode ou não querer dois valores, dependendo da sua arquitetura e dos requisitos de privacidade.
`tid`	Cadeia de caracteres, um GUID	Representa o locatário no qual o usuário está se conectando. Para contas corporativas e de estudante, o GUID é a ID de locatário imutável da organização à qual o usuário está se conectando. Para conexões no locatário de conta Microsoft pessoal (serviços como Xbox, Teams for Life ou Outlook), o valor é `9188040d-6c67-4c5b-b112-36a304b66dad`.
`unique_name`	String	Presente apenas em tokens da v1.0. Fornece um valor legível que identifica a entidade do token. Não há garantia de que esse valor seja exclusivo dentro de um locatário, e ele deve ser usado apenas para fins de exibição.
`uti`	String	Declaração de identificador de token, equivalente a `jti` na especificação JWT. Identificador exclusivo por token que diferencia maiúsculas de minúsculas.
`ver`	Cadeia de caracteres, 1.0 ou 2.0	Indica a versão do token da ID.
`hasgroups`	Boolean	Se houver algum, sempre verdadeiro, indicando que o usuário pertence a pelo menos um grupo. Indica que o cliente deve usar a API do Microsoft Graph para determinar os grupos do usuário (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`).
`groups:src1`	Objeto JSON	Para solicitações de token que não são limitadas em tamanho (consulte `hasgroups`), mas ainda são muito grandes para o token, é incluído um link para a lista completa de grupos do usuário. Para JWTs na forma de declaração distribuída, para SAML como uma nova declaração no lugar da declaração `groups`. Valor de exemplo de JWT: `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` Para obter mais informações, confira Declaração de excedente de grupos.

Use declarações para identificar um usuário de forma confiável

Ao identificar um usuário, é fundamental usar informações que permaneçam constantes e exclusivas ao longo do tempo. Os aplicativos herdados às vezes usam campos como endereço de email, número de telefone ou UPN. Todos esses campos podem mudar com o tempo e também podem ser reutilizados com o tempo. Por exemplo, quando um funcionário altera seu nome ou recebe um endereço de email que corresponde ao de um funcionário anterior, ele não representa mais o funcionário. Seu aplicativo não deve usar dados legíveis por humanos para identificar um usuário. legíveis por humanos geralmente significa que alguém pode lê-los e querer alterá-los. Em vez disso, use as declarações fornecidas pelo padrão OIDC ou as declarações de extensão fornecidas pela Microsoft (declarações sub e oid).

Para armazenar corretamente as informações por usuário, use apenas sub ou oid (que são exclusivas como GUIDs), utilizando tid para roteamento ou fragmentação, se necessário. Se você precisar compartilhar dados entre serviços, oid e tid são melhores, pois todos os aplicativos recebem as mesmas declarações oid e tid para um usuário que atua em um locatário. A declaração sub é um valor de pares que é único. O valor é baseado em uma combinação do token, do locatário e do usuário. Dois aplicativos que solicitam tokens de ID para um usuário recebem declarações sub diferentes, mas as mesmas declarações oid para esse usuário.

Observação

Não use a declaração idp para armazenar informações sobre um usuário em uma tentativa de correlacionar usuários entre locatários. Isso não funciona, pois as declarações oid e sub de um usuário mudam entre locatários, por design, para garantir que os aplicativos não possam rastrear usuários entre locatários.

Os cenários de convidados, em que um usuário está hospedado em um locatário e se autentica em outro, devem tratar o usuário como se ele fosse um novo usuário do serviço. Seus documentos e privilégios em um locatário não devem ser aplicados em outro locatário. Essa restrição é importante para evitar a perda acidental de dados entre locatários e a imposição de ciclos de vida de dados. A remoção de um convidado de um locatário também deve remover o acesso aos dados criados nesse locatário.

Declaração de excedente de grupos

Para garantir que o tamanho do token não exceda os limites de tamanho do cabeçalho HTTP, o número de IDs de objeto que ele inclui na declaração groups é limitado. Se um usuário for membro de mais grupos do que o limite excedente (150 para tokens SAML, 200 para tokens JWT), a declaração de grupos não será incluída no token. Em vez disso, ele inclui uma declaração excedente no token que indica ao aplicativo consultar a API do Microsoft Graph para recuperar a associação de grupo do usuário.

{
  ...
  "_claim_names": {
   "groups": "src1"
    },
    {
  "_claim_sources": {
    "src1": {
        "endpoint":"[Url to get this user's group membership from]"
        }
       }
     }
  ...
}

Próximas etapas

Saiba mais sobre os Tokens de segurança usados na ID do Microsoft Entra.

Compartilhar via