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

  • Artigo

Os tokens de ID são tokens da Web JSON (JWT). Os tokens de ID v1.0 e v2.0 têm diferenças nas informações que carregam. A versão é baseada no ponto de extremidade de onde foi solicitada. 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, salvo indicação em contrário. Os tokens de ID consistem em um cabeçalho, carga útil e assinatura. O cabeçalho e a assinatura são usados para verificar a autenticidade do token, enquanto a carga útil contém as informações sobre o usuário solicitadas pelo seu cliente.

Declarações de cabeçalho

A tabela a seguir mostra as declarações de cabeçalho presentes nos tokens de ID.

Afirmação Formato Description
typ String - 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 para a chave pública que pode ser usada para validar a assinatura do token. Emitido em 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 apenas em tokens de ID v1.0 para fins de compatibilidade.

Declarações de carga útil

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

Afirmação Formato Description
aud String, um GUID de ID de aplicativo Identifica o destinatário pretendido do token. No id_tokens, o público é a ID do Aplicativo do seu aplicativo, atribuída ao seu aplicativo no portal do Azure. Este valor deve ser validado. O token deve ser rejeitado se não corresponder à ID do aplicativo do seu aplicativo.
iss String, um URI do emissor Identifica o emissor ou "servidor de autorização" que constrói e retorna o token. Ele também identifica o locatário para o qual o usuário foi autenticado. Se o token foi emitido pelo ponto de extremidade v2.0, o URI termina em /v2.0. O GUID que indica que o usuário é um usuário consumidor de uma conta da Microsoft é 9188040d-6c67-4c5b-b112-36a304b66dad. Seu aplicativo deve usar a parte 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 do token.
idp String, geralmente um URI STS Regista o fornecedor de identidade que autenticou o requerente do token. Esse valor é idêntico ao valor da declaração do emissor, a menos que a conta do usuário não esteja no mesmo locatário que o emissor - convidados, por exemplo. Se a declaração não estiver presente, significa que o valor de iss pode ser usado em vez disso. Para contas pessoais que estão sendo usadas em um contexto organizacional (por exemplo, uma conta pessoal convidada para um locatário), a idp declaração pode ser 'live.com' ou um URI STS contendo o locatário 9188040d-6c67-4c5b-b112-36a304b66dadda conta da Microsoft.
nbf int, um carimbo de data/hora Unix Identifica o tempo antes do qual o JWT não pode ser aceito para processamento.
exp int, um carimbo de data/hora Unix Identifica o tempo de expiração no qual ou após o qual o JWT não pode ser aceito para processamento. Em determinadas circunstâncias, um recurso pode rejeitar o token antes desse período. Por exemplo, se uma alteração na autenticação for necessária ou uma revogação de token tiver sido detetada.
c_hash String O hash de código está incluído nos tokens de ID apenas quando o token de ID é emitido com um código de autorização de 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, consulte a especificação do OpenID Connect. Essa declaração não é retornada em tokens de ID do ponto de extremidade /token.
at_hash String O hash de token de acesso está incluído nos tokens de ID apenas quando o token de ID é emitido a partir do ponto final /authorize com um token de acesso de OAuth 2.0. Ele pode ser usado para validar a autenticidade de um token de acesso. Para entender como fazer essa validação, consulte a especificação do OpenID Connect. Essa declaração não é retornada em tokens de ID do /token ponto de extremidade.
aio Corda opaca Uma declaração interna que é usada para registrar dados para reutilização de token. Deve ser ignorado.
preferred_username String O nome de usuário principal que representa o usuário. Pode ser um endereço de e-mail, número de telefone ou um nome de usuário genérico sem um formato especificado. Seu valor é mutável e pode mudar ao longo do tempo. Como é 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 por humanos como um nome de usuário. O profile escopo é necessário para receber essa reivindicação. Presente apenas em tokens v2.0.
email String Presente por padrão para contas de convidado que tenham um endereço de e-mail. 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 é garantido que esse valor esteja correto e é mutável ao longo do tempo. Nunca o utilize para autorização ou para guardar dados para um utilizador. 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. No ponto de extremidade v2.0, seu aplicativo também pode solicitar o escopo do email OpenID Connect - você não precisa solicitar a declaração opcional e o escopo para obter a declaração.
name String A name declaração fornece um valor legível por humanos que identifica o assunto do token. Não é garantido que o valor seja exclusivo, pode ser alterado e deve ser usado apenas para fins de exibição. O profile escopo é necessário para receber essa reivindicaçã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 String, um GUID O identificador imutável para um objeto, neste caso, uma conta de usuário. Esse ID identifica exclusivamente o usuário entre aplicativos - dois aplicativos diferentes que entram no mesmo usuário recebem o mesmo valor na oid declaração. O Microsoft Graph retorna essa ID como a propriedade de id uma conta de usuário. Como o oid permite que vários aplicativos correlacionem usuários, o profile escopo é necessário para receber essa declaração. Se existir um único utilizador em vários inquilinos, o utilizador contém um ID de objeto diferente em cada inquilino - são consideradas contas diferentes, mesmo que o utilizador inicie sessão em cada conta com as mesmas credenciais. A oid declaração é um GUID e não pode ser reutilizada.
roles Matriz de cadeias O conjunto de funções que foram atribuídas ao usuário que está fazendo logon.
rh Corda opaca Uma declaração interna usada para revalidar tokens. Deve ser ignorado.
sub String O assunto das informações no token. Por exemplo, o usuário de um aplicativo. Esse valor é imutável e não pode ser reatribuído ou reutilizado. O assunto é um identificador de pares e é exclusivo para um ID de aplicativo. Se um único usuário entrar em dois aplicativos diferentes usando duas IDs de cliente diferentes, esses aplicativos receberão dois valores diferentes para a declaração de assunto. Você pode ou não querer dois valores, dependendo de sua arquitetura e requisitos de privacidade.
tid String, um GUID Representa o locatário no qual o usuário está entrando. Para contas corporativas e de estudante, o GUID é a ID de locatário imutável da organização na qual o usuário está entrando. Para iniciar sessão no inquilino pessoal da conta Microsoft (serviços como Xbox, Teams for Life ou Outlook), o valor é 9188040d-6c67-4c5b-b112-36a304b66dad.
unique_name String Presente apenas em tokens v1.0. Fornece um valor legível por humanos que identifica o requerente do token. Não é garantido que esse valor seja exclusivo dentro de um locatário e deve ser usado apenas para fins de exibição.
uti String Declaração de identificador de token, equivalente à jti especificação JWT. Identificador exclusivo por token que diferencia maiúsculas de minúsculas.
ver String, 1.0 ou 2.0 Indica a versão do token de ID.
hasgroups Boolean Se presente, sempre verdadeiro, denotando que o usuário está em pelo menos um grupo. Indica que o cliente deve usar a API do Microsoft Graph para determinar os grupos de usuários (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 comprimento (consulte hasgroups), mas ainda muito grandes para o token, um link para a lista completa de grupos para o usuário é incluído. Para JWTs como uma reivindicação distribuída, para SAML como uma nova reivindicação no lugar da groups reivindicação.

Exemplo de valor JWT:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }

Para obter mais informações, consulte Reivindicação de excesso de idade de grupos.

Usar 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 únicas ao longo do tempo. Às vezes, os aplicativos herdados usam campos como endereço de e-mail, número de telefone ou UPN. Todos esses campos podem mudar ao longo do tempo e também podem ser reutilizados ao longo do tempo. Por exemplo, quando um funcionário muda seu nome, ou um funcionário recebe um endereço de e-mail que corresponde ao de um funcionário anterior, não está mais presente. Seu aplicativo não deve usar dados legíveis por humanos para identificar um usuário - legível por humanos geralmente significa que alguém pode lê-lo e deseja alterá-lo. Em vez disso, use as declarações fornecidas pelo padrão OIDC ou as declarações de extensão fornecidas pela Microsoft - as sub oid e declarações.

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

Nota

Não use a idp declaração para armazenar informações sobre um usuário em uma tentativa de correlacionar usuários entre locatários. Ele não funciona, pois as oid declarações de sub 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 convidado, em que um usuário está hospedado em um locatário e se autentica em outro, devem tratar o usuário como se fosse um novo usuário para o 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 o vazamento acidental de dados entre locatários e a aplicação de ciclos de vida de dados. A remoção de um hóspede de um inquilino também deve remover o seu acesso aos dados que criou nesse inquilino.

Reivindicação de excesso de idade 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 groups declaração é limitado. Se um usuário for membro de mais grupos do que o limite de ultrapassagem (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 de excesso no token que indica ao aplicativo para 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óximos passos