Explainations on JWT Tokens structure

Question

I'm trying to understand JWT tokens usage but I'm getting lost on the theorycal part.

I have some questions about JWT Tokens structure, in order to make this question a sort of documentation for new users, providing it with a logic order, I will write them in bold below as long as I list a sample JWT content.

I will also summary them in the end of the question

A "classic" JWT token is composed as follows:

[HEADER].[PAYLOAD].[SIGNATURE]

In detail:

HEADER

{
  "alg": "HS256",
  "typ": "JWT"
}

Which contains the following fields:

ALG = Encryption algorythm (using the default HS256 could be fine)
TYP = simply tells that it's a JWT

PAYLOAD

{
  "sub": "1234567890",
  "name": "MrJohnDoe",
  "iat": 1516239022
}

~~SUB = What is SUB? Can you please tell me an example of what it could be in a common usage?~~
See @CassioMazzocchiMolin answer below for this
SUB = Is an OPTIONAL parameter. It's the subject of the token. (credits: @CassioMazzocchiMolin)
According to: Where to store user id in jwt looks like you can use it to store your user ID in it.
NAME = The username
IAT = ~~Token expiration time. Is it expressed in ms?~~
Thanks to @jps and @JeanRostan in the comments below.
- IAT = Token creation date and time, expressed in unix timestamp.

SIGNATURE

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),

secret

)

~~What's actually the "secret"? Should I use user's password as secret?~~
Thanks to @jps in the comments below.
- SECRET = Unique key known just by the server. To not confuse with the current user password, which should never be used for this!

iat is a unix timestamp, it expresses the number of seconds elapsed since 1970-01-01 00:00:00 UTC (en.wikipedia.org/wiki/Unix_time) so it's a date indicating when the token won't be valid anymore. The wiki page on JWT tokens will answer your questions most likely: en.wikipedia.org/wiki/JSON_Web_Token#Standard_fields — Jean Rostan
read here about the timestamps format. IAT is issued at, the timestamp when the token was created. The expiration is in the exp claim. — jps
secret is a key used for the signature. And you should not use the users password. The secret should only be known on server side. — jps
@Deadpool you mean iat and exp? These are simply two different claims, one for the time of creation, the other for the end of it's life — jps

cassiomolin cassiomolin · Accepted Answer · 2018-04-16T16:12:45

What is sub? Can you please provide me an example of what it could be in a common usage?

The sub claim identifies the principal that is the subject of the JWT. In other other, it can hold the username of the user who you issued the token to.

From the RFC 7519:

4.1.2. "sub" (Subject) Claim

The sub (subject) claim identifies the principal that is the subject of the JWT. The claims in a JWT are normally statements about the subject. The subject value MUST either be scoped to be locally unique in the context of the issuer or be globally unique. The processing of this claim is generally application specific. The sub value is a case-sensitive string containing a StringOrURI value. Use of this claim is OPTIONAL.

Explainations on JWT Tokens structure

1 Answers