OAuth 2.0 for microservices - System Design Guide

Problem Statement

When multiple microservices need to securely communicate and verify user identity, relying on each service to handle authentication separately leads to inconsistent security, duplicated effort, and potential vulnerabilities. Without a centralized authorization mechanism, services may expose sensitive data or fail to enforce proper access controls, risking data breaches and unauthorized actions.

Solution

OAuth 2.0 provides a standardized way for microservices to delegate user authentication and authorization to a trusted authorization server. Services receive access tokens that prove the user's identity and permissions, allowing them to verify requests without managing credentials themselves. This centralizes security, reduces duplication, and enables fine-grained access control across services.

Architecture

┌───────────────┐       ┌────────────────────┐       ┌───────────────┐
│               │       │                    │       │               │
│   Client App  ├──────▶│ Authorization Server├──────▶│   Microservice│
│               │       │                    │       │               │
└───────────────┘       └────────────────────┘       └───────────────┘
         │                        ▲                          │
         │                        │                          │
         │                        │                          │
         │                        │                          │
         └────────────────────────┴──────────────────────────┘

Legend:
Client App requests access token from Authorization Server.
Authorization Server issues token after user authentication.
Client App calls Microservice with token.
Microservice validates token with Authorization Server or introspection endpoint.

This diagram shows the flow where a client app obtains an access token from an authorization server and then calls a microservice with that token. The microservice validates the token to authorize the request.

Trade-offs

✓ Pros

→

Centralizes authentication and authorization logic, reducing duplicated code in microservices.

→

Enables fine-grained access control with scopes and roles embedded in tokens.

→

Improves security by avoiding direct credential sharing between services.

→

Supports token expiration and revocation for better session management.

✗ Cons

→

Adds complexity with the need for an authorization server and token management.

→

Token validation can introduce latency if done synchronously via introspection.

→

Requires careful token design to avoid overly large tokens or insufficient permissions.

Use OAuth 2.0 when your system has multiple microservices requiring secure, delegated user authorization, especially when user identity and permissions must be consistently enforced across services at scale (hundreds to thousands of requests per second).

Avoid OAuth 2.0 if your system is a simple monolith or has very low inter-service communication where simpler authentication methods suffice, as the overhead of token management may outweigh benefits.

Real World Examples

Netflix

Uses OAuth 2.0 tokens to authorize user requests across many microservices, ensuring consistent access control for streaming content.

Uber

Employs OAuth 2.0 to manage user permissions and secure communication between rider, driver, and backend microservices.

Google

Implements OAuth 2.0 extensively to allow users to authorize third-party apps and to secure internal microservice interactions.

Code Example

The before code shows a microservice directly validating user credentials, which duplicates authentication logic and is insecure. The after code shows the microservice validating an OAuth 2.0 JWT access token issued by an authorization server, checking scopes for authorization. This centralizes auth and improves security.

Microservices

### Before: Microservice directly checks user credentials (bad practice)

class Microservice:
    def handle_request(self, user_credentials):
        if not self.validate_user(user_credentials):
            return "Unauthorized"
        return "Data for user"

    def validate_user(self, creds):
        # Naive check, duplicates auth logic
        return creds == "valid_password"


### After: Microservice validates OAuth 2.0 access token

import jwt

class Microservice:
    AUTH_SERVER_PUBLIC_KEY = "<public_key_here>"

    def handle_request(self, access_token):
        try:
            payload = jwt.decode(access_token, self.AUTH_SERVER_PUBLIC_KEY, algorithms=["RS256"])
            if "read:data" in payload.get("scopes", []):
                return "Data for user"
            else:
                return "Forbidden: insufficient scope"
        except jwt.ExpiredSignatureError:
            return "Unauthorized: token expired"
        except jwt.InvalidTokenError:
            return "Unauthorized: invalid token"

Alternatives

API Key Authentication

Uses static keys for service authentication without user delegation or fine-grained scopes.

Use when: Choose when services only need simple authentication without user context or complex permissions.

Mutual TLS (mTLS)

Uses client and server certificates for mutual authentication at the transport layer, not user authorization.

Use when: Choose when strong service-to-service authentication is needed without user identity delegation.

JWT without OAuth

Services issue and validate JWT tokens independently without a centralized authorization server.

Use when: Choose when you want lightweight token-based auth but can manage token issuance and revocation internally.

Summary

OAuth 2.0 centralizes authorization for microservices by issuing access tokens that prove user permissions.

Microservices validate tokens to enforce consistent access control without managing user credentials.

This pattern improves security and scalability but adds complexity with token management and validation.

Practice

1. What is the main purpose of using OAuth 2.0 in a microservices architecture?

easy

A. To allow microservices to securely share user permissions without sharing passwords

B. To encrypt all communication between microservices

C. To store user data centrally in one microservice

D. To replace HTTPS for secure communication

Solution

1. Step 1: Understand OAuth 2.0 role in microservices

   OAuth 2.0 is designed to delegate access without sharing user passwords, enabling secure permission sharing.

2. Step 2: Differentiate from other security methods

   OAuth 2.0 does not encrypt communication or replace HTTPS; it focuses on authorization, not data storage or transport security.

3. Final Answer:

   To allow microservices to securely share user permissions without sharing passwords -> Option A

4. Quick Check:

   OAuth 2.0 = Secure permission sharing [OK]

Hint: OAuth 2.0 is about permissions, not encryption or storage [OK]

Common Mistakes:

• Confusing OAuth 2.0 with encryption protocols
• Thinking OAuth 2.0 stores user data centrally
• Assuming OAuth 2.0 replaces HTTPS

2. Which of the following is the correct way to include an OAuth 2.0 access token in an HTTP request header?

easy

A. Auth-Token: <access_token>

B. Token: OAuth <access_token>

C. Authorization: Bearer <access_token>

D. Access: BearerToken <access_token>

Solution

1. Step 1: Recall OAuth 2.0 token header format

   The standard way to send an OAuth 2.0 token is using the Authorization header with the Bearer scheme.

2. Step 2: Verify header syntax

   Correct syntax is exactly "Authorization: Bearer <token>"; other options use incorrect header names or schemes.

3. Final Answer:

   Authorization: Bearer <access_token> -> Option C

4. Quick Check:

   OAuth token header = Authorization: Bearer [OK]

Hint: OAuth tokens go in Authorization header with Bearer prefix [OK]

Common Mistakes:

• Using wrong header names like Token or Auth-Token
• Missing the 'Bearer' keyword before the token
• Using incorrect capitalization or spacing

3. Given a microservice receiving a JWT access token, which step correctly validates the token before processing the request?

medium

A. Decrypt the token and store it in a database

B. Check token signature, verify expiration, and confirm required scopes

C. Send the token to the user service for validation every time

D. Ignore the token if the request comes from a trusted IP

Solution

1. Step 1: Understand JWT validation steps

   JWT tokens are validated by checking their signature, expiration time, and scopes to ensure authenticity and permission.

2. Step 2: Eliminate incorrect practices

   Decrypting JWT is incorrect because JWTs are signed, not encrypted; querying user service every time reduces scalability; trusting IP alone is insecure.

3. Final Answer:

   Check token signature, verify expiration, and confirm required scopes -> Option B

4. Quick Check:

   JWT validation = signature + expiry + scopes [OK]

Hint: Validate JWT by signature, expiry, and scopes locally [OK]

Common Mistakes:

• Trying to decrypt JWT instead of verifying signature
• Validating tokens by calling user service every request
• Trusting IP addresses instead of tokens

4. A microservice is failing to authenticate requests even though clients send valid OAuth 2.0 tokens. Which is the most likely cause?

medium

A. The microservice is not verifying the token signature correctly

B. The clients are sending tokens in the URL query parameters

C. The microservice is using HTTPS for communication

D. The tokens are expired but the microservice ignores expiration

Solution

1. Step 1: Analyze token verification failure

   If valid tokens are sent but authentication fails, incorrect signature verification is a common cause.

2. Step 2: Evaluate other options

   Sending tokens in URL is discouraged but may still work; HTTPS is required for security but not cause failure; ignoring expiration would allow some tokens through, not fail all.

3. Final Answer:

   The microservice is not verifying the token signature correctly -> Option A

4. Quick Check:

   Invalid signature verification = auth failure [OK]

Hint: Check token signature verification first when auth fails [OK]

Common Mistakes:

• Blaming HTTPS for authentication issues
• Assuming tokens in URL always cause failure
• Ignoring token expiration causes failure, not ignoring it

5. In a microservices system using OAuth 2.0, how can an API Gateway improve scalability and security when handling access tokens?

hard

A. By bypassing token validation to reduce latency

B. By storing all user passwords and tokens for microservices to access

C. By encrypting all tokens with a shared secret before sending to microservices

D. By centralizing token validation and forwarding only authorized requests to microservices

Solution

1. Step 1: Understand API Gateway role in OAuth 2.0

   The API Gateway can validate tokens centrally, so microservices do not need to validate tokens individually, improving performance and security.

2. Step 2: Eliminate incorrect options

   Storing passwords centrally is insecure; encrypting tokens unnecessarily adds complexity; bypassing validation reduces security and is unsafe.

3. Final Answer:

   By centralizing token validation and forwarding only authorized requests to microservices -> Option D

4. Quick Check:

   API Gateway = central token validation [OK]

Hint: Use API Gateway to validate tokens once for all microservices [OK]

Common Mistakes:

• Thinking API Gateway stores user passwords
• Assuming tokens must be encrypted again by gateway
• Skipping token validation to save time