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, num 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 email com o valor [email protected].

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

Usos das declarações (claims)

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

• JSON Web Token (JWT) : Num JWT, as declarações são usadas para representar informações sobre o token, como o issuer (iss), sujeito (sub) e tempo de expiração (exp).
• OpenID Connect (OIDC) : No OIDC, as declarações são usadas para representar informações do utilizador no Token de ID (ID token) e Endpoint de userinfo (userinfo endpoint) , como o endereço de email do utilizador (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 issuer 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 se refere. Por exemplo, num ID token, a declaração sub geralmente representa o identificador do utilizador.
• aud: O audience 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.

O OIDC também define declarações padrão adicionais para informações do utilizador. Veja Declarações (Claims) na especificação OIDC para mais detalhes.

Declarações personalizadas

Além das declarações padrão, podes definir declarações personalizadas para representar informações específicas da aplicação. Por exemplo, podes incluir uma declaração role para representar o papel do utilizador na aplicação.

As 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, podes definir o teu 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 (userinfo endpoint)