Solution Design: /token Endpoint

Central entry point for issuing JWTs

---

Solution Design: /token Endpoint

Purpose

The /token endpoint is the central entry point for issuing JWTs within the microservices ecosystem. It ensures secure, claim-based authentication between services (e.g., careergpt-backend → logging-service).

Issue short-lived JWTs for other microservices.

Embed claims (e.g., issuer, audience, subject) that downstream services can validate.

Provide a trust boundary: Identity-Backend is the single source of truth for authentication.

Responsibility

Responsible for issuing signed JSON Web Tokens (JWTs) to other services within the architecture. These tokens are used for secure service-to-service communication, ensuring each request can be authenticated and authorized without relying on static API keys.

---

Endpoint

Method: POST
URL: https://aurorahours.com/identity-backend/token

Request Payload

{
  "sub": "careergpt-backend",
  "aud": "logging-service"
}

• sub (Subject):
  The microservice requesting the token (e.g., careergpt-backend).

• aud (Audience):
  The intended recipient microservice the token will be used with (e.g., logging-service).

---

Processing Logic

1. Input Validation

   • Verify both sub and aud are provided.

   • Log error and return 400 Bad Request if missing.

2. Token Generation

   • Construct JWT payload with:

     • iss: Identity service name (identity-backend)

     • sub: Requesting microservice name

     • aud: Target service name

     • iat: Issued-at timestamp

     • exp: Expiration timestamp (default 15 minutes, configurable)

3. Signing

   • Sign JWT using HS256 and the JWT_SECRET_KEY (shared secret).

4. Response

   • Return signed JWT to the caller.

---

Response Example

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJpZGVudGl0eS1iYWNrZW5kIiwic3ViIjoiY2FyZWVyZ3B0LWJhY2tlbmQiLCJhdWQiOiJsb2dnaW5nLXNlcnZpY2UiLCJpYXQiOjE3NTM4MzUwNzksImV4cCI6MTc1MzgzNTk3OX0.s2ryI5Tc3O312NvfVs1bpoCiUpsX4igX1EA1duvwMmI"
}

The returned token is a JWT signed with the Identity-Backend’s secret key. This token must be included in the Authorization: Bearer <token> header for calls to other microservices.

---

Design Considerations

1. Security

   • Tokens are HMAC-signed using JWT_SECRET_KEY (shared only between Identity-Backend and other services).

   • Tokens are short-lived (default 15 minutes) to reduce impact if leaked.

   • Audience and issuer are validated by consuming services.

2. Scalability

   • Stateless authentication: no session storage required.

   • Token validation only requires the signing secret (no database lookups).

3. Extensibility

• Future migration to asymmetric signing (RSA) for external clients is possible.

• Claims can be expanded (e.g., roles, permissions) without breaking existing consumers.

Key Design Principles

• Centralized Trust
  Only identity-backend issues JWTs, ensuring all microservices validate against a single source of truth.

• Least Privilege via Audience Claim
  Tokens are valid only for the intended service (aud), preventing cross-service misuse.

• Short-Lived Tokens
  Expiration is enforced (e.g., 15 min) to reduce blast radius of compromised tokens.

• Stateless Authentication
  JWTs remove the need for a central session store; each service can independently verify tokens.

Integration Flow

1. Service A (e.g., CareerGPT-Backend) requests a token from /token.

2. Identity-Backend signs and returns the token with the proper claims.

3. Service A calls Service B (e.g., Logging-Backend) with the token in the Authorization header.

4. Service B validates:

   • Signature

   • aud (audience matches its service name)

   • iss (issuer = identity-backend)

   • Expiry time (exp)