JWTs with Asymmetric Keys

8. JWTs with Public/Private Key Digital Signatures

JWTs can be signed using symmetric algorithms like HMAC (e.g., HS256), where a shared secret key is used for both signing and verification, or asymmetric algorithms like RSA (e.g., RS256) and ECDSA (e.g., ES256), where a pair of keys—public and private—are used. Using public/private key pairs enhances security by allowing only the trusted issuer (holding the private key) to sign tokens, while anyone with the corresponding public key can verify the signature.

8.1 Public/Private Key Digital Signatures

1. Symmetric vs. Asymmetric Signing

   • Symmetric Signing (HMAC): Uses the same secret key to sign and verify the JWT. While simple and fast, it requires secure handling of the key, as both the issuer and verifier need access to the secret key.

   • Asymmetric Signing (RSA/ECDSA): Uses a private key to sign the JWT and a public key to verify it. The private key is kept secure on the server side, while the public key can be distributed openly. This approach improves security and scalability, especially in distributed environments.

2. How Asymmetric Signing Works:

   • Token Creation: The server signs the JWT using its private key, ensuring the integrity and authenticity of the claims.
   • Token Verification: Clients or other services verify the JWT using the public key. Since the private key is never shared, only the entity holding the private key can create valid tokens.

3. Benefits of Asymmetric JWT Signing:

   • Enhanced Security: Only the trusted issuer (e.g., authentication server) can sign tokens, reducing the risk of key compromise.
   • Scalability and Flexibility: Public keys can be distributed widely, allowing multiple services to verify JWTs without exposing the private key.
   • Support for Multiple Issuers: Asymmetric signing enables a centralized authority to issue tokens, while decentralized services can independently verify them.

8.2 Implementing JWTs with Public/Private Key Signatures in Fastify

Below is an example demonstrating how to implement JWT authentication using RSA asymmetric signing with the Fastify framework. This example uses RSA keys to sign and verify JWTs.

Example: JWT Authentication with Public/Private Key Digital Signatures in Fastify

const fastify = require("fastify")({ logger: true });
const fs = require("fs");
const path = require("path");
const jwt = require("fastify-jwt");

// Load RSA keys (ensure keys are securely stored in production environments)
const privateKey = fs.readFileSync(path.join(__dirname, "private.key"), "utf8");
const publicKey = fs.readFileSync(path.join(__dirname, "public.key"), "utf8");

// Register the JWT plugin with RSA keys for asymmetric signing
fastify.register(jwt, {
  secret: {
    private: privateKey,
    public: publicKey,
  },
  sign: { algorithm: "RS256" }, // Use RS256 algorithm for signing
  verify: { algorithms: ["RS256"] }, // Use RS256 for verification
});

// Route to authenticate a user and issue a JWT
fastify.post("/login", async (request, reply) => {
  const { username, password } = request.body;

  // Mock user authentication (replace with actual logic)
  if (username === "user" && password === "password") {
    // Create a JWT signed with the private key
    const token = fastify.jwt.sign(
      { username, role: "user" },
      { expiresIn: "1h" }
    );
    return { token };
  }

  reply.code(401).send({ error: "Invalid credentials" });
});

// Middleware to verify JWTs for protected routes using the public key
fastify.addHook("onRequest", async (request, reply) => {
  try {
    await request.jwtVerify(); // Verifies the token using the public key
  } catch (err) {
    reply.code(401).send({ error: "Unauthorized" });
  }
});

// Protected route example
fastify.get("/protected", async (request, reply) => {
  return {
    message: `Hello, ${request.user.username}! You have access to this protected route.`,
  };
});

// Start the Fastify server
fastify.listen({ port: 3000 }, (err, address) => {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }
  fastify.log.info(`Server running at ${address}`);
});

Key Points in the Example:

• RSA Keys: The private key is used to sign the JWT, and the public key is used to verify it. These keys are typically stored securely and managed with appropriate access controls.
• Asymmetric Signing: The RS256 algorithm is used, ensuring that only the server holding the private key can generate valid tokens, while the public key can be widely distributed for verification.
• Stateless Verification: The public key allows for stateless verification, which is ideal for distributed systems or microservices where multiple services need to validate tokens without sharing secrets.

8.3 Benefits of Using Public/Private Key Digital Signatures with JWTs

1. Separation of Issuer and Verifier Roles

   • With asymmetric signing, the roles of issuer (private key holder) and verifier (public key holder) are separated, enhancing security and allowing for more flexible system architectures.

2. Simplified Key Management in Distributed Systems

   • In a microservices architecture, distributing the public key to all services that need to verify JWTs simplifies key management, as only the private key needs to be securely managed and protected.

3. Improved Security and Trust

   • Only the issuer’s private key can sign valid JWTs, ensuring that no unauthorized entities can generate tokens. The public key can be freely distributed without compromising security, allowing any trusted party to verify the tokens.

4. Support for Multiple Environments and Clients

   • Different environments (e.g., development, staging, production) can use different key pairs, ensuring secure and environment-specific token management without risking cross-environment interference.

5. Revocation and Rotation Flexibility

   • Public keys can be rotated or revoked without disrupting the system, as long as the clients update their verification keys accordingly. This flexibility supports best practices in key management.

8.4 Best Practices for Using JWTs with Asymmetric Keys

1. Secure Key Storage

   • Store private keys securely, using environment variables, secure vaults, or key management services (e.g., AWS KMS, Azure Key Vault) to prevent unauthorized access.

2. Rotate Keys Regularly

   • Implement key rotation policies to ensure keys are regularly updated, minimizing the impact of potential key compromise. Ensure new public keys are distributed promptly.

3. Use Strong Algorithms

   • Use strong, widely-accepted algorithms like RS256 or ES256 to sign JWTs, ensuring that tokens are resistant to cryptographic attacks.

4. Implement Token Expiration and Revocation

   • Set short expiration times for JWTs and implement mechanisms to handle token revocation, especially in scenarios where immediate access control is critical.

5. Distribute Public Keys Securely

   • Public keys should be distributed securely, often through trusted sources or endpoints (e.g., JWKS – JSON Web Key Sets), to ensure that verifiers always have the correct key.

6. Validate Claims and Signature

   • Always validate the JWT’s signature and inspect claims for expected values. Ensure claims are not manipulated and that tokens have not expired.

7. Monitor and Log Authentication Events

   • Log all authentication and authorization events, including JWT verification failures, to help detect unauthorized access attempts or potential security breaches.

9. Conclusion

Using JWTs with public/private key digital signatures significantly enhances the security and scalability of authentication and authorization in REST APIs. By leveraging asymmetric cryptography, JWTs ensure that only trusted entities can issue valid tokens, while allowing multiple distributed services to verify tokens independently. Following best practices in key management, validation, and secure storage helps maintain a robust and resilient authentication system that meets the demands of modern, distributed applications.