Solution Design: /verify endpoint

Purpose

The /verify endpoint is responsible for validating JWTs issued by the identity-backend. It ensures any token presented to a microservice is authentic, unaltered, and scoped correctly for its intended use.

---

Request Payload

{
  "token": "<jwt_here>",
  "aud": "logging-service"
}

• token:
  The JWT to validate (generated via /token).

• aud (Audience):
  The microservice performing validation (e.g., logging-service), used to confirm token scope.

---

Validation Steps

1. Signature Verification

   • Decode the JWT using HS256 and the JWT_SECRET_KEY.

   • If the signature doesn’t match, return 401 Invalid token.

2. Issuer Check

   • Validate iss claim equals identity-backend.

3. Audience Check

   • Ensure aud claim matches the expected microservice.

4. Expiration Check

   • Verify current time is before exp claim.

   • Expired tokens result in 401 Token expired.

5. Structured Logging

   • Log success or failure reasons to both:

     • The logging microservice (central log).

     • Local stderr log for troubleshooting.

---

Response Examples

Valid Token

{
  "valid": true,
  "claims": {
    "iss": "identity-backend",
    "sub": "careergpt-backend",
    "aud": "logging-backend",
    "iat": 1753835079,
    "exp": 1753835979
  }
}

Invalid Token

{
  "valid": false,
  "error": "Signature verification failed"
}

---

Key Design Principles

• Single Source of Truth
  Validation depends on identity-backend’s shared secret and claims.

• Defense-in-Depth
  Multiple checks (signature, issuer, audience, expiration) prevent token misuse.

• Detailed Logging
  All validation attempts are logged centrally and locally for audit and debugging.

• Extensible for Future Keys
  Endpoint can evolve to validate tokens signed with asymmetric keys (RSA/ECDSA).