A complete guide to JSON Web Tokens (JWTs)Link to this section
What is JSON?Link to this section
Plus, any programming language can use JSON’s data format, making it the preferred syntax for APIs (replacing XML).
As the name suggests, JSON is the data text format used to create JSON web tokens.
What are JSON Web Tokens (JWTs)?Link to this section
JSON Web Tokens (JWTs for short) are an open standard that allows security information to be shared between a client and a server, shared as claims (encoded JSON objects). These tokens are compact and self-contained, meaning user information is saved directly in the token (without a server needing to remember or save anything).
Encryption and signing are what keep user information secure in JWTs. Inside each token, information is digitally signed using a secret or using a public/private key pair.
The benefits of JWTsLink to this section
JWTs aren’t the only type of tokens that exist. There are plenty of options to consider, including simple web tokens (SWTs) and Security Assertion Markup Language (SAML) tokens.
But, JWTs do offer a unique set of benefits including:
- They’re compact: JSON is more concise than XML. This means that a JWL is smaller than a SAML token when it’s encoded, making it the go-to choice for tokens that need to be passed in HTML and HTTP environments.
- They’re more secure: JWTs use a public/private key pair for signing and can also be signed by shared secret using the HMAC algorithm. While this is possible with SAML tokens, it’s much more difficult than the simple process of signing JSON.
- They’re commonly used: in most programming languages, JSON parsers are common are they map directly to objects. This is a key reason why JWT is easier to work with than SAML assertions.
- They’re easy to process: as JWTs are used at an internet-scale they’re easier to process on a range of user devices, particularly smartphones.
When are JWTs used?Link to this section
With a high level of security, JWTs are a secure way to authenticate users, authorize access and exchange information.
There are three main uses for JWT:
- Authentication: When a user enters their login details, an ID token is generated and returned. The OpenID Connect (OIDC) specs indicate that an ID token is always a JWT.
- Authorization: After authentication, an app might request access to specific services or resources (such as APIs) on behalf of the user. To make this happen, an access token is used, which can be in the form of a JWT.
- One type of authentication that regularly uses JWTs is single sign-on (SSO) because of its ability to be easily used across different domains.
- Information exchange: With the ability to be signed, JWTs are a secure way to share information between two places. Plus, the way JWTs are structured (more on that later) means it’s easy to spot if the data has been tampered with along the way.
What makes JWTs unique in comparison to using sessions and cookies is their self-contained design. It allows information to be easily shared between a client and server in a compact way - a great example of stateless authentication.
Unpacking the structure of JWTsLink to this section
Three important elements come together to form a JWT. Each is separated by a full stop (.), making the code easier to read than most.
The three elements of a decoded JWT are:
- Header: the first part of the code, explaining both the type of the code (JWT) as well as the signing algorithm you’re using (whether that’s HMAC SHA256 or RSA).
- Payload: this second section contains ‘claims’ about the user, as well as any additional data that could be useful. Typically, claims fall into three categories:
- Registered claims: while their not mandatory, these predefined claims are recommended and very useful. Often you’ll find iss (issuer), exp (expiration time), sub (subject) and aud (audience) used.
- Public claims: these are customizable and able to be created by those using JWTs.
- Private claims: finally, these claims are used to share information between parties that are neither registered or public.
💡 Both the header and payload are Base64Url encoded to form the first and second parts of the JWT.
- Signature: lastly, the signature is created by taking the encoded header, the encoded payload, a secret as well as the algorithm named in the header. This signature confirms that the code hasn’t been altered or changed in transit.
When the final JWT is created, you’ll see three Base64-URL strings that are separated by full spots. Not only does this make this code easy to navigate and understand, but it’s more compact and easier to use in HTML and HTTP environments.
How JWTs workLink to this section
It’s important to understand how JWTs work in practice. As JWTs perform a range of functions, it carries information that both authenticates and authorizes user access.
[IMAGE SUGGESTION: This graphic could be good to create in Kinde’s branding as a way to visually show how this process happens.]
- A user enters their login details, such as a username and password.
- An authentication server verifies these details. If correct, they issue a signed JWT.
- This JWT is used to authorize access to protected resources. This happens by passing the JWT in the HTTP authorization header.
- Then, the resource server verifies the authenticity of the token by reviewing the signature and ensuring no code has been changed or tampered with.
A good analogy for how JWTs work is this: they’re an ID badge that gives an employee access to a secured building. Inside this badge are special permissions (a.k.a. claims) that restrict which floors and rooms the employee can access.
You can think of the authorization server as the office’s reception desk (a.k.a. The issuer of the badge). Then, to verify that the badge is valid the company’s logo is printed on the card (just like the signature of a JWT).
If the employee tries to access a floor they don’t have the authorization to enter, the badge’s permission will stop them (just like the claims in a JWT).
Understanding JWT securityLink to this section
JWTs have a level of security baked into their design. The digital signing and encoding process ensures each element of the JWT’s structure is verified and protected.
We’ll be focusing on signed tokens as they allow each claim’s integrity to be verified and checked. In contrast, encoded tokens hide these claims from other parties.
There are two ways to sign a JWT: either using a secret (leveraging the HMAC algorithm) or a public/private key pair (using RSA or ECDSA). In the latter option, the signature process is a way of verifying that the party who holds the private key is the only one who signed it.
The best way to retain a JWT’s security is to make sure the signature has been validated before use. This means the token’s information hasn’t been changed, altered or compromised.
It’s important to remember that JWTs are stored in plain text, meaning you shouldn’t store any sensitive information inside these tokens. Only sending JWTs over HTTPs is another proactive way to ensure these tokens aren’t intercepted and remain secure.
If you’re looking for a compact, self-contained way to securely share information between two parties, JSON Web Tokens can be a good fit. Their small size and ability to be shared by HTTPs make them easy to transmit and fast to share (without needing to call a server to validate the token, either).
Get started now
Boost security, drive conversion and save money — in just a few minutes.