DEV Community

Cover image for Building a Robust and Cost effective Token Verification Service: A Guide to Secure API Integrations
JOOJO DONTOH
JOOJO DONTOH

Posted on

Building a Robust and Cost effective Token Verification Service: A Guide to Secure API Integrations

Introduction

In today’s interconnected systems, secure communication between services is very important 🤔. APIs are increasingly used to bridge services across organizational boundaries, often involving sensitive data exchanges such as top secret pancake recipes😅. This has amplified the need for robust mechanisms to verify and authenticate requests between systems securely. Imagine a token verification service that not only signs requests but also automates key rotation, providing security and convenience for API integrations.

In this article, we’ll walk through a solution architecture to build a scalable and secure token verification service using AWS tools like Lambda, Secrets Manager, and API Gateway 🎉. This service is designed to enable partners and internal teams to verify requests originating from your service while maintaining high availability and resilience. The solution balances functional requirements with performance and cost-effectiveness, making it an ideal addition to your organization’s security toolkit. Now let's look at the problem 😢


Problem
Imagine needing to authenticate and authorize requests from internal or external services, sign requests, or implement role-based access control. A straightforward solution could be to integrate symmetric verification endpoints into an existing service and expose them to other services that require these capabilities.
This approach provides a quick and accessible way to add secure, verifiable authentication without extensive restructuring.

But wait! While this quick fix might address the immediate problem, it may not scale well or handle similar challenges beyond the current scope. Here’s why: if the verification is symmetric, meaning the same key is used for both signing and verifying requests, it can create inefficiencies. Depending on the architecture of the host service, this could quickly turn into a bottleneck, especially under high load or across multiple services needing validation.
So, what’s the alternative? Imagine solving authentication and authorization issues “across space and time.” 🧐

Solving problems "across space" means designing a solution that addresses the current issue not just for a single team or service, but for any team or service that might face the same challenge. Meanwhile, solving "across time" involves creating a solution that can address similar problems that may have existed in the past or could arise in the future—a versatile solution that can be applied in various scenarios or extended to tackle new issues.

So, how do we devise a solution that achieves this?

We’ll create a service with the following capabilities:

  • Exposing public keys for token verification
  • Signing payloads with private keys on a secure, protected endpoint
  • Automating key rotation to avoid manual intervention
  • Ensuring high availability, security, and cost-effectiveness

Solution Overview

Our proposed solution leverages AWS’s serverless offerings—such as Secrets Manager, Lambda, and API Gateway—to handle token signing, verification, and key rotation efficiently, ensuring security, scalability, and maintainability. Here’s a breakdown of the tools and technologies we’ll use:

Tools

  • API Gateway: Manages HTTP requests, allowing secure access to endpoints.
  • AWS Lambda: Facilitates secure, on-demand execution for signing, public key retrieval, and key rotation.
  • AWS S3: Stores public keys for easy access through the public endpoint.
  • AWS Secrets Manager: Manages private keys securely and supports automated rotation.
  • Serverless Framework: Simplifies deployment and infrastructure management.

This combination allows us to build a service that is secure, highly available, and optimized for fast public key retrieval, making it both lightweight and cost-effective.

Let's scope out the requirements

Functional Requirements

  1. Public Key Retrieval

    • A public endpoint will serve public keys for verifying tokens issued by the service, allowing clients to authenticate tokens securely.
  2. Private Key Management

    • The service will securely store private keys in Secrets Manager, which can be accessible through a protected endpoint or directly from AWS Secrets Manager via authorized roles.
  3. Authorization Control for Signing

    • Only authorized clients will access the signing endpoint, and each client must have explicit permissions.
  4. Automated Key Rotation

    • Keys will be rotated automatically to ensure that they remain secure, with an immediate rotation option for emergency cases.

Non-Functional Requirements

  1. High Availability

    • The service should be designed with minimal downtime to guarantee constant availability.
  2. Robustness and Maintainability

    • Easy-to-maintain code that other teams can access, use, and adapt as needed.
  3. Security and Performance

    • Strong security practices, including efficient public key retrieval and endpoint protection, without impacting speed or availability.


Service Architecture and Flow

Key Components

  1. 🔐 Token Signing

    Clients authorized for signing can request token generation by calling a protected API endpoint. The process works as follows:

    • Permissions Check: Only clients with explicit permissions can access this endpoint.
    • Private Key Retrieval: The service retrieves the private key securely from AWS Secrets Manager.
    • Token Generation: The payload is signed using the private key, and the resulting token is returned to the client.
  2. 🔑 Token Verification

    Token verification is facilitated by a JWKS (JSON Web Key Set) endpoint, allowing clients to retrieve public keys for verifying tokens. The process is:

    • Public Key Access: The JWKS endpoint exposes public keys that match the key ID in signed tokens.
    • Verification: Clients use the retrieved public keys to validate the authenticity and integrity of the token.
  3. 🔄 Key Rotation

    Key rotation is handled automatically by AWS Secrets Manager:

    • Periodic Rotation: Secrets Manager rotates keys at set intervals.
    • Lambda Handling: An AWS Lambda function manages the updates to public and private keys in Secrets Manager, ensuring smooth transitions.
  4. ☁️ Serverless Framework and AWS Integration

    • Resource Provisioning: Serverless automates AWS Lambda and API Gateway setups, delivering responsive, load-adaptive infrastructure.
    • Environment Configuration: Enables secure, isolated environment configurations (e.g., dev, staging, production) with controlled access to AWS Secrets Manager and S3.
    • CI/CD Pipeline: Integrates with Pipelines for automated, reliable deployments without manual intervention.
    • Cost Efficiency and Scalability: Combines AWS Lambda’s pay-as-you-go model with Serverless’s efficient setup, reducing idle costs and scaling resources on demand.

High-Level Flow

High-Level Flow

1. Token Signing Process

  • Step 1: A client with the necessary authorization initiates a request to sign a payload.
  • Step 2: The signing endpoint verifies the client’s permissions, retrieves the private key from Secrets Manager, signs the payload, and returns a token with a unique key ID (kid) in the header for easy verification. If the private key is missing, the service automatically rotates keys to ensure availability before signing the payload.

Token Signing Process

2. Token Verification Process

  • Step 1: A client receives a signed token, which includes a key ID in its header.
  • Step 2: The client fetches the matching public key from the JWKS endpoint and verifies the token.

Token Verification Process

3. Key Rotation Process

  • Generates two RSA key pairs (2048 and 4096 bits) with unique key IDs.
  • Retrieves existing public keys, appends the new public keys, and saves the updated set of keys.
  • Updates or ensures the existence of a private key in AWS Secrets Manager.
  • Returns metadata upon successful rotation, with error handling for issues during the key generation or save process.

Key Rotation Process


🎉 Advantages of the Solution

  1. 🔒 Security: Private keys are securely managed in Secrets Manager, and only authorized clients can access sensitive endpoints.

  2. 🌐 Availability: AWS’s serverless infrastructure ensures high availability, even under heavy traffic.

  3. 💰 Cost-Effectiveness: Serverless architecture allows on-demand scaling, making it a highly cost-effective solution.

  4. 🔄 Resilience: Automated key rotation, with the option for immediate rotation, boosts both security and resilience.

  5. ⚙️ Rotation Atomicity: Key rotation is atomic, ensuring public keys update first. If public key storage fails, the process stops, keeping the current key pair intact.If private key storage fails, the failure isn't harmful, because the current key pair is intact. However a configured alert will call for manual intervention.

  6. 🔧 Key Signing Dynamism: The sign endpoint supports flexible payload signing, allowing dynamic expiry, key length, and algorithm selection.

  7. 📜 Key Signing Availability: If the private key is missing, the sign endpoint triggers a key rotation, ensuring keys are always available for signing.

  8. 📉 Pay-as-You-Go Model: AWS Lambda charges only for compute time, making this solution ideal for short-lived signing and verification tasks.

  9. 🚫 No Dedicated Infrastructure: Serverless architecture eliminates the need for infrastructure management, as AWS handles scaling and security patches.

  10. 🔐 Efficient Secret Management: AWS Secrets Manager securely stores and rotates private keys, reducing the risks and costs of manual management.

  11. 📦 Scalable Storage with Amazon S3: Public keys stored on Amazon S3 enjoy durable, scalable storage. Paired with CloudFront, this minimizes data transfer costs.

  12. ⚖️ Dynamic Scaling & No Downtime Costs: AWS’s serverless infrastructure scales automatically, eliminating downtime costs and avoiding idle capacity.


🛠️ Use Cases

  1. 🔑 Access and Refresh Token Management

    • Securely issues and manages access and refresh tokens, allowing clients to verify token validity with ease.
  2. 📜 API Request Signing

    • Enables clients to securely sign and validate API requests, ensuring the integrity and authenticity of requests.
  3. 👥 Role-Based Authentication

    • Supports role-specific authentication for actions, restricting access to authorized roles only.
  4. 🚨 Emergency Key Rotation and Compliance

    • Allows for immediate key rotation in case of a security incident, ensuring quick compliance with security best practices.

Conclusion

Creating a token verification service with automated key rotation and secure signing endpoints is essential in modern API ecosystems. Our solution not only provides a robust token verification framework but also ensures security, availability, and cost-effectiveness. Leveraging AWS’s serverless and managed services makes it easy to scale, maintain, and secure the service, giving partners and teams the confidence to rely on the service for request verification.

This service blueprint provides a powerful framework for implementing secure API integrations. By focusing on both functional and non-functional requirements, you can ensure that your token verification process is resilient, fast, and secure, setting the stage for a more connected and protected API ecosystem.

PS: Though the idea solution and implementation are mine, this article was reviewed and enhanced by my Uncle: Mr Chat GPT.😁

Top comments (0)