top of page

OAuth 2.0 | JSON Web Token (JWT) | Claims

Dear Reader,


The way I'm enjoying writing this series, I hope you're enjoying reading too! Starting from the very basics to deep diving now into JWT, it been amazing and thanks to you for devoting your time to read the stuff. I hope I'm able to add some value to your learning.


Coming back to JWT which stands for JSON Web Token. We touched this concept briefly in last article: https://www.techlearnings.org/single-post/oauth-2-0-client-authentication ; today it's time to learn more about it.


A very easy to understand statement from jwt.io to start with. I think, it beautifully explains the concept.

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

The above line is self explanatory. Only thing I feel which needs explanation and marked in bold is claims, and believe me this topic is enough big to write a complete article on. Hence, we'll discuss today only claims.


Let's see first how a claim looks like.


{
    "sub" : "techlearnings-jwt-claims-article",
    "iss" : "techlearnings",
    "iat" : 1651598413,
    "exp" : 1651684813,
    "jti" : "2ed198ae-8a5d-4c16-9830-00c690926299",
    "non-registered-claim" : {
        "message" : "Hello JWT!"
    }
}


What is a claim?


A claim is a piece of information that we're asserting. Going by Google definition of claim - it means to state a fact or belief confidently and forcefully. In this case, e.g. If we're saying this token is issued by X, then it means we are claiming this information about who issued this token. If we're saying this token expires at this time, it means we're claiming it must not be accepted for processing after this timestamp.


Therefore, information in a claim is going to have two parts. One - Claim Name and Second - Claim Value. In other words, a key value pair, where key is claim name which is a string and value is claim value which can be an JSON.


A group of claims is called Claims Set. Set word implicitly means the names within a JWT Claims Set must be unique.


Claims are represented by a JWT Claims set which is a JSON object whose members are claims conveyed by JWT. It will be more clearer with below -


Different Classes of Claim Names


i. Registered Claims Names

ii. Public Claim Names

iii. Private Claim Names


i. Registered Claim Names:


The claim names which are registered at IANA (Internet Assigned Numbers Authority - maintains collection of registries that are critical in ensuring global coordination of the DNS root zone, IP addressing, and other Internet protocol resources) Please refer - https://www.iana.org/assignments/jwt/jwt.xhtml#claims


Mentioning some important ones below (Full list you can go through at provided link)

  • iss: Issuer claim - identifies who issued the token. It's case sensitive string.

  • sub: Subject claim - identifies the subject of JWT. Again it's a case sensitive string.

  • aud: Audience claim - identifies the intended recipients of the JWT. Usually, it's an array of strings.

  • exp: Expiration time claim - identifies timestamp equal to or beyond which token is expired (no longer eligible for processing). It's contains a numeric date value.

  • nbf: Not before claim - identifies timestamp before which token must not be accepted for any processing. It's also a numeric date value.

  • iat: Issued at claim - identifies timestamp at which token is issued. Again same - It's a numeric date value.

  • jti: JWT Id claim - contains a unique identifier for the JWT. Not to mention, no two tokens should have same id. If there are multiple issuers, id collisions must be prevented. It's a case sensitive string.

The usage of all above mentioned registered claims is optional. A sample screenshot below from iana.org.



ii. Public Claim Names:


The claim names which are user defined. As it's a user defined name that also means the definer of the name has to make sure the name collision is avoided. Either the new name should be registered in IANA or definer needs to make sure that it controls the namespace used to define the name.


iii. Private Claim Names:


Names which are agreed upon by the producer and consumer of the JWT. Not to mention, precaution needs to be taken to avoid name collision in this case as well.


That's it, we're done with claims for today. Lot more still to cover in JWT & OAuth. Stay tuned, Stay connected!


Mentioning other OAuth articles already published as a handy reference guide for further learning. Do check out in case you missed.


Happy Tech Learnings!

Comments

​
bottom of page