JSON Web Tokens Claims

JSON Web Token claims (JWT Claims) are used to authenticate and authorize applications and APIs. JWT claims provide a secure way to share information between different parties and are made up of three elements: a header, payload, and a signature.

JWT claims can be categorized into two parts, registered claims, and custom claims, and provide a flexible, lightweight, and easily integrated way of authenticating and authorizing users.

JSON Web Tokens (JWTs) are an open industry standard used to share information between two parties: a client and a server. JWTs provide a secure way to authenticate users, authorize access, and share information. JWTs are made up of three parts: a header, a payload, and a signature.

• Header: this is the first part of the code, which contains information about the type of token and the cryptographic algorithm used to sign it.
• Payload: contains ‘claims’ about the user and other data that is deemed useful.
• Signature: the signature is created by taking the encoded header, the encoded payload, a secret, and the algorithm named in the header. The signature of a JWT is employed to confirm that the code has not been tampered with or altered during transmission.

JWT claims are located in the payload section and provide essential information regarding the user and the context of the token. JWT claims can be divided into two categories: registered claims and custom claims.

Registered claims are a set of predetermined claims that aren’t required but are recommended to be used to deliver useful and interoperable claims. Examples of the most important registered claims include:

• iss (issuer): Issuer of the JWT.
• sub (subject): Subject of the JWT (the user).
• aud (audience): The JWT intended recipient or audience.
• exp (expiration time): The time the JWT expires.
• nbf (not before policy): Identifies the time before which JWT can not be accepted into processing.
• iat (issued at time): Identifies the time at which the JWT was issued. This can be used to establish the age of the JWT or the exact time the token was generated.
• jti (JWT ID): Unique identifier; this can be used to prevent the JWT from being used more than once.

You can set and control your own custom claims and add them to a token using Actions. Custom claims are specific to a given application or use case and aren’t established by the JWT specification.

For example, you could add custom claims to a dashboard managing user accounts. In addition to the standard claims sub and iat you might want additional information about a user by adding custom claims called user_type which provides information about whether the user is an administrator or a regular user.

Public claims are JWT claims that aren’t defined by the JWT specification and there are no predetermined names used for them. Instead, developers can create custom public claims that suit their specific needs.

Although public claims are not required, they are recommended to provide useful and interoperable claims and can be used by various parties if they agree on their meaning. If developers create public claims, they must be registered or use collision-resistant names. Public claims can be found in the IANA JSON Web Token Claims Registry.

Common public names used by developers include:

• Name: the name of the user
• Email: the email address of the particular user
• Locale: the user’s preferred language

Private claims are additional bits of information relating to your specific application or organization and much like public claims, they are not standardized by the JWT specification.

For example, a public claim may contain a user’s name and email, but private claims can provide more information about a user such as their department name, role in an organization, and permissions.

Since private claims are not standardized, they should not be used when sensitive information is involved or shared throughout various applications.

JWTs provide companies with a secure way of authenticating and authorizing users by offering a secure way to establish claims between two parties. JWT claims are typically divided into two categories. Registered claims provide predetermined information, whereas custom, private and public claims allow developers to set their own claims, whether that’s widely accepted definitions of public claims or private claims that are specific to the company.

See how Kinde compares to other authentication providers.