Understanding JWKS

Web security has many terms and concepts. One of them is "JWKS" or "JSON Web Key Set." Hanko uses JWKS, so let's get to know it better.

What's JWKS?

A JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by an authorization server and signed using RS256 signing algorithm. These keys are represented in a JSON format.

How Hanko Uses JWKS

Hanko's backend harnesses the power of JWT and JWKS to provide a robust, secure, and efficient user authorization mechanism. By doing so, Hanko ensures the integrity and authenticity of each user's token, offering a seamless and secure user experience.

Why JWKS Matters

When it comes to authentication, verifying the integrity and validity of a token is crucial. To do this, we require public keys. Instead of hardcoding these keys or managing them manually, JWKS offers a dynamic and flexible way to provide these keys. It acts as a public repository of keys that can be retrieved and rotated without significant changes in the systems that use them.

What Does a JWKS Look Like?

Here's a simple example:

{
 "keys": [
   {
     "alg": "RS256",
     "kty": "RSA",
     "use": "sig",
     "x5c": [
       "MIIC+DCCAeCgAw..."
     ],
     "e": "AQAB",
     "n": "vM6z..."
   }
 ]
}

• alg: The algorithm used for the key. Common examples include RS256 and ES256.
• kty: The key type. RSA is a common choice.
• use: The intended use of the public key, usually sig for signature.
• x5c: This is an X.509 certificate chain, often used when the key is available in the form of a certificate.
• e & n: These represent the exponent and modulus for the RSA public key, respectively.

Logging in with Hanko and JWKS

Here's what happens when someone logs in using Hanko:

1. The user logs in and receives a JWT from Hanko.
2. The application, to verify the JWT, needs the public key.
3. Instead of maintaining a static list of public keys, the application fetches the JWKS from Hanko, which contains the required public key.
4. Using this public key, the application verifies the JWT's signature, ensuring its validity and integrity.

Benefits of Using JWKS:

• Rotation & Revocation: Over time, for security reasons, keys need to be rotated. With JWKS, you can easily introduce new keys and retire old ones without system-wide updates (Hanko will support key rotation in a future release).
• Scalability: As your platform grows and evolves, you might use different keys for different purposes (e.g., one for user tokens, another for service-to-service communication). JWKS provides a scalable way to manage these keys.
• Interoperability: Being a standardized way to represent cryptographic keys, it promotes interoperability between different systems and services.

What's the /.well-known/jwks.json​ file?

The /.well-known/jwks.json file is a standard endpoint that contains the public keys for verifying JWT access tokens. Hanko exposes this endpoint by default for each Hanko Cloud project at:

https://{project.id}.hanko.io/.well-known/jwks.json

In Conclusion

JWKS is an essential component in the modern authentication ecosystem, especially when JWTs are involved. Its dynamic and standardized nature ensures that the process of key management becomes less cumbersome and more secure.

‍

Find out more on how to check JWTs with JWKS in our backend guides.