Authentication Block
A production-ready authentication building block for microservice architectures that enables multi-provider login (Cognito + Okta SSO) and stateless JWT verification via either a lightweight SDK or a containerized service.
The Problem
Teams building distributed systems need a secure, consistent way to authenticate users across services without each team re-implementing auth logic. In practice, this becomes fragmented: different token checks, inconsistent provider integrations, duplicated security mistakes, and a high cost of change when identity providers evolve.
- Microservices growth: Multiple services need to verify tokens consistently without duplicating auth code.
- Provider complexity: Supporting both consumer auth (username/password) and enterprise SSO requires different flows and security considerations.
- Migration & scale: Switching providers or adding new ones is costly when auth is embedded differently in every service.
Intended Outcome
Key outcomes this block enables:
- Consistent token verification across services, regardless of the identity provider.
- Provider flexibility so products can support Cognito and enterprise SSO without re-architecture.
- Fast, low-friction integration through either a service interface or an SDK.
Scope & Boundaries
- Stateless JWT verification with caching and key rotation support.
- Multi-provider support (currently AWS Cognito and Okta SSO).
- Two integration modes: REST API for language-agnostic usage and Python SDK for direct embedding and low-latency verification.
- Production readiness surfaces such as health checks and structured logging.
- Product-specific authorization rules (roles, entitlements, resource-level permissions).
- UI/UX for login beyond enabling the auth flows (those remain product-owned).
How it Works
At a high level, how does this building block operate? Core behavior flow:
User authenticates with an identity provider (Cognito or Okta SSO).
The user receives a JWT token from the provider.
A backend service receives requests containing that token.
The Authentication Block verifies the token by: Validating signature via provider keys (with caching), Confirming token integrity and validity (expiry, issuer, audience as configured).
The service receives verified claims and continues with business logic.
System Interaction
Placement & Triggers
- Sits at the boundary of protected services, close to request handling.
- Works alongside gateways or BFF layers, but does not require them.
- Standardizes identity verification so downstream services can focus on business logic.
Supported Architectures
Experience Surface
This block is mostly invisible to end users. Its effect is experienced indirectly through: Consistent login success/failure behavior, Predictable session and access validation across services, Reduced “random auth errors” caused by inconsistent token handling. In enterprise contexts, it enables the product to support SSO flows without custom auth logic per service.
Design Assets
Available Resources
This building block is primarily backend-facing, so UI assets are optional. Auth Status Banner (optional) Purpose: A minimal pattern for showing “signed in / session expired” states consistently. Key elements: status label, refresh action, support link.
When to use
Risks & Guidelines
- Treating token verification as authorization (“JWT valid” ≠ “user can do this action”).
- Mixing integration modes inconsistently across services without clear ownership.
- Overexposing optional endpoints that aren’t required for a given product surface.
- Keep authorization decisions in the product domain; use the block only for identity verification.
- Establish a standard integration mode by context (SDK for internal services, REST for heterogeneous stacks).
- Use feature flags and least-privilege exposure for optional endpoints.
How to Measure Success
How will we know this pattern is strengthening trust?
North Star
Token Verification Success Rate: percentage of verification attempts that return a valid, verified result (excluding intentionally invalid tokens).
Verification Latency
Measures how fast token verification completes. Useful to validate the “fast path” promise, especially in SDK mode vs service mode.
Verification Failure Breakdown
Counts failures by reason category (expired token, invalid signature, issuer/audience mismatch, missing token, malformed token).
Provider Mix Over Time
Percentage of verified tokens by provider (Cognito vs Okta).