JSON Web Tokens (JWT)

Owned by Roger Cruz
Last updated: Dec 22, 2019
2 min read

Intro

 

Standards

 

  • Official standard is RFC-7519

  • The suggested pronunciation of JWT is the same as the English word "jot"

     

Reading Material

 

 

Tools For Encoding/Decoding JWTs

 

Tokens are usually encoded, not encrypted.  Some OAuth servers may encrypt tokens but that is not common or the default.

 

 

Notes And Tips

 

  • JWT is not required by OAuth but it is usually in use. They are encoded BUT not encrypted. Use a JSON Web Encryption (JWE) is encryption is needed.

  • JWT token is an easy way to encode and pass around JSON data without having to escape it for all the different contexts.

  • JWT contain a lot more information. Once validated, you can use <name,value> pairs, also known as claims, to grant or deny access.  

    • The specific structure and naming conventions of those claims can vary by implementation.

 

Registered Names

 

Reserved field names in a JWT

 

  • The "iss" (issuer) claim identifies the principal that issued the JWT.

  • The "sub" (subject) claim identifies the principal that is the subject of the JWT.

  • The "aud" (audience) claim identifies the recipients that the JWT is intended for.

  • The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.

  • The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing.

  • The "iat" (issued at) claim identifies the time at which the JWT was issued.

  • The "jti" (JWT ID) claim provides a unique identifier for the JWT.

 

Token Validation

 

  • Token validation establishes trust. You should do this first before caring about the payload.

  • We'll only ever validate the access and ID tokens. Refresh tokens are handled differently

  • Steps for validating a token are always the same.

    • Retrieve the keys document, which represent the public key that the token was signed with.  These keys are available via URL from the authorization server.

    • Separate the token into the header, the payload and the signature by looking for the period.

    • Extract the claim called the KID, or the Key ID from the header. It should reference a key from the keys document above.

    • Use the referenced key and the payload to generate a signature. Compare it against the signature from the token. If they don't match, token has been tampered with.

    • Now you can trust the token. Decode payload and look at the issuer (iss) claim. It should come from our auth server.

    • The Audience (aud) claim, which should match the values set in our authorization server. 

    • The client ID (cid), which should match the application ID which originally requested the token. 

    • The Expiration Time (exp) should be in the future.

    • If any of the above checks fails, token is invalid and must not be used.

    • Don’t build this yourself. Use the libraries provided with your language

Â