O que é Declaração (Claim)?

O que é uma declaração (claim)?

Uma declaração (claim) é um par nome-valor que transmite informações específicas. Por exemplo, em um objeto JSON:

{
  "sub": "foo",
  "email": "[email protected]"
}

Neste exemplo, sub é uma declaração que representa o identificador do sujeito com o valor foo, e email é uma declaração que representa o endereço de e-mail com o valor [email protected].

Usamos sujeito em vez de usuário porque, sem uma definição clara, o sujeito (sub) pode representar um usuário, dispositivo ou qualquer entidade.

Usos das declarações (claims)

Declarações (claims) são amplamente utilizadas em vários contextos, como:

• JSON Web Token (JWT) : Em um JWT, declarações são usadas para representar informações sobre o token, como o emissor (iss), sujeito (sub) e tempo de expiração (exp).
• OpenID Connect (OIDC) : No OIDC, declarações são usadas para representar informações do usuário no Token de ID (ID token) e Endpoint de userinfo , como o endereço de e-mail do usuário (email), nome (name) e foto de perfil (picture).

Declarações padrão

No JWT e OIDC, existem declarações padrão definidas pelas especificações. Algumas declarações padrão comuns incluem:

• iss: O emissor do token. Por exemplo, se o Servidor de autorização que emitiu o token é https://example.com, na maioria dos casos a declaração iss será a mesma (https://example.com).
• sub: O sujeito do token. Representa a entidade sobre a qual o token trata. Por exemplo, em um ID token, a declaração sub geralmente representa o identificador do usuário.
• aud: A audiência do token. Indica os destinatários para os quais o token é destinado. Por exemplo, se o token é destinado ao acesso a uma API em https://api.example.com, a declaração aud será a mesma (https://api.example.com).
• exp: O tempo de expiração do token. Indica quando o token não deve mais ser aceito para processamento.
• nbf: O tempo “não antes” do token. Indica quando o token deve começar a ser aceito para processamento.
• iat: O tempo de emissão do token. Indica quando o token foi emitido.
• jti: O ID do JWT do token. Fornece um identificador único para o token.

OIDC também define declarações padrão adicionais para informações do usuário. Veja Claims na especificação OIDC para mais detalhes.

Declarações personalizadas

Além das declarações padrão, você pode definir declarações personalizadas para representar informações específicas da aplicação. Por exemplo, você pode incluir uma declaração role para representar o papel do usuário na aplicação.

Declarações personalizadas podem ser nomeadas com Identificadores de Recursos Uniformes (URIs) para evitar conflitos com outras declarações. Por exemplo:

{
  "https://example.com/claims/role": "admin"
}

Neste exemplo, a declaração role é nomeada com https://example.com/claims/ para garantir a exclusividade. Alternativamente, você pode definir seu próprio Nome de Recurso Uniforme (URN) para declarações personalizadas:

{
  "urn:example:claims:role": "admin"
}

Neste exemplo, a declaração role é nomeada com urn:example:claims:.

Veja também

• JSON Web Token (JWT)
• OpenID Connect (OIDC)
• Token de ID (ID token)
• Endpoint de userinfo