JWKS (JSON Web Key Set) Overview

What is JWKS?

JSON Web Key Set (JWKS) is a standard format for sharing public keys. It enables secure communication by allowing third parties to verify the authenticity of JSON Web Tokens (JWTs) signed by our system.

How it works in inTandem

In our inTandem platform, partner applications are embedded as iframes within our system. When these embedded apps need to send requests, they communicate with the platform using the getAuth method from the inTandem SDK.

Key Steps in the Flow:

1. Token request via SDK:

   • The app uses the inTandem SDK to call the getAuth method.
   • The platform processes this request and generates an authentication token (JWT) for the current user.

2. Token usage by the app:

   • The app receives the JWT and includes it in its API requests to its backend.
   • The app's backend retrieves our public key from the JWKS URL (https://api.vcita.biz/v3/apps/.well-known/jwks.json) and uses it to validate the JWT.

3. User validation and security:

   • The app's backend checks the aud (audience) property of the token to ensure the token is meant for the specific app.
   • The app's backend checks the sub (subject) property of the token to ensure the token is meant for the specific staff.
   • This ensures that the token corresponds to the correct user and context.

Security measures:

• Key rotation: Public and private keys are rotated periodically to minimize the risk in case of key leakage.
• Short-lived tokens: Authentication tokens have a short lifespan and can be revoked to enhance security.

Why use JWKS?

• No private key sharing: The private key remains secure within our system, while only the public key is shared.
• Token integrity: Ensures the token hasn’t been altered or tampered with.
• Ease of integration: Third-party systems can easily fetch and use our public key from the JWKS URL.

By using JWKS, inTandem ensures secure and reliable communication between our platform and third-party systems, maintaining a robust security model and streamlined developer experience.

Relevant reference documentation

• inTandem SDK getAuth: https://developers.intandem.tech/v3.0/docs/getauth
• Compact JWS token: https://developers.intandem.tech/v3.0/reference/compact-jws-token

Code sample

import { decodeJwt, jwtVerify } from 'jose';
import axios from 'axios';

async verify(token: string): Promise<JWTPayload> {
  const response = await axios.get('https://api.vcita.biz/v3/apps/.well-known/jwks.json');
  const { keys } = response.data;
  const decodedJwt = decodeJwt(token);
  if (!decodedJwt.kid) {
    throw new Error('No kid in token header');
  }

  const matchingKey = keys.find((key) => key.kid === decodedJwt.kid);
  if (!matchingKey) {
    throw new Error('No matching key found');
  }

  const verifyResult = await jwtVerify(token, matchingKey);
  return verifyResult.payload;
}

More information and reads

A great resource to read more about JWKS and related concepts is the RFC 7517, which provides an in-depth explanation of the JSON Web Key (JWK) standard.

Additionally, you can explore the following resources:

Auth0 Blog - JSON Web Keys (JWKs): https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets - A developer-friendly guide that explains how JWKS is used with JWTs.
Okta Developer Docs: https://developer.okta.com/docs/concepts/jwks/ - A practical breakdown of JWKS implementation and its importance in API security.
JWT.io: https://jwt.io/ - This interactive tool helps you inspect, decode, and learn more about JWTs, often used with JWKS.
These references should provide you with both foundational knowledge and real-world use cases. Let me know if you'd like a deeper dive into any of these concepts!