Designing an OAuth 2.0 Authorization Server

Hello! Welcome to your next lesson.

In our last session, we designed the validation logic for a SAML Service Provider, focusing on how to securely process a SAML assertion. We saw that ensuring trust in a federated identity system requires a rigorous, multi-step validation process, especially given the complexities of XML signatures.

While SAML remains a cornerstone of enterprise web single sign-on, the modern application landscape, dominated by APIs, mobile apps, and single-page applications (SPAs), often requires a more lightweight and flexible protocol. This is the world of OAuth 2.0.

Today, we will shift our focus from consuming assertions to issuing authorization. We'll architect the heart of a modern identity system: the OAuth 2.0 Authorization Server.

The learning outcome for this lesson is to:

Design the core architecture of an OAuth 2.0 authorization server, handling Authorization Code and Client Credentials grant flows.

We will break down what an Authorization Server does and design its key components, paying close attention to the security principles that underpin its most important workflows.

1. What is an OAuth 2.0 Authorization Server?

At its core, OAuth 2.0 is a framework for delegated authorization. It allows a user to grant a third-party application limited access to their resources (like photos or contacts) without giving away their password.

To understand the problem OAuth solves and the roles involved, let's start with a foundational video.

As the video explains, our focus today is on designing the Authorization Server (AS). This is the central orchestrator in the OAuth 2.0 framework. Its primary responsibilities are:

• Authenticating the Resource Owner (the user).
• Obtaining consent from the user to grant access to a Client (the application).
• Issuing access tokens to the Client.

To fulfill these duties, an Authorization Server exposes two primary endpoints:

1. /authorize: An interactive, browser-based endpoint used to handle user authentication and consent. This is a front-channel endpoint.
2. /token: A non-interactive, API endpoint used by applications to exchange credentials for tokens. This is a back-channel endpoint.

The way a client interacts with these endpoints is defined by a grant type. Let's design our server to support the two most critical grant types.

2. Grant 1: The Authorization Code Grant

This is the most common and secure flow for applications that have a backend server, such as traditional web apps, as well as modern SPAs and mobile apps. It's designed to keep access tokens off the front-channel (i.e., out of the browser's URL and history).

The Flow

The flow involves a careful dance between the browser and a backend server. This diagram and the next video segment illustrate it perfectly.

Architectural Design

Now, let's architect the components within our Authorization Server that make this flow possible.

A. Client Registry
Before any flow can begin, the client application must be registered with our Authorization Server. This requires a persistent store (e.g., a database table) to manage client information.

The clients table would need columns for:

• client_id (public, unique identifier)
• client_secret_hash (for confidential clients, always store a hash, never plaintext)
• redirect_uris (an allow-list of valid callback URLs)
• allowed_scopes (the scopes this client is permitted to request)
• client_type (e.g., 'confidential' for apps with a backend, 'public' for SPAs/mobile)

B. The /authorize Endpoint

This endpoint orchestrates the user-facing part of the flow.

• Request Parameters: It must handle GET requests with parameters like:

  • response_type=code
  • client_id
  • redirect_uri
  • scope
  • state (an opaque value used to prevent CSRF)
  • code_challenge & code_challenge_method (for PKCE)

• Processing Logic:

  1. Validate Request: Check that the client_id exists and the redirect_uri is in the client's pre-registered allow-list.
  2. Authenticate User: This is a key integration point. The AS must authenticate the user. This is typically done by redirecting to a login page and managing a session.
  3. Obtain Consent: If the client is requesting scopes for the first time, display a consent screen to the user (e.g., "App XYZ wants to read your profile and contacts. Allow?").
  4. Generate Authorization Code: Create a short-lived, one-time-use authorization code.
     • Design Trade-off: How should we implement this code?
       • Option 1 (Stateful): Generate a random string and store it in a fast cache (like Redis) with associated metadata: user_id, client_id, scopes, code_challenge, and an expiry time (e.g., 60 seconds).
       • Option 2 (Stateless): Create a JSON object with the metadata, encrypt it using a symmetric key known only to the server (e.g., AES-GCM), and then Base64 encode the result. This creates a self-contained, tamper-proof code that doesn't require a database lookup during validation.
  5. Redirect: Send a 302 Found response to the user's browser, redirecting them to the client's redirect_uri with the code and state in the query string.

C. The /token Endpoint (Code Exchange)

This is the back-channel endpoint where the client's server exchanges the code for tokens.

• Request: It must handle POST requests with a Content-Type of application/x-www-form-urlencoded. The body includes:

  • grant_type=authorization_code
  • code (from the previous step)
  • redirect_uri
  • client_id
  • client_secret (for confidential clients)
  • code_verifier (the PKCE secret)

• Processing Logic:

  1. Authenticate Client: If the client is confidential, verify its client_id and client_secret against the client registry.
  2. Validate Code:
     • If using the stateful approach, look up the code in the cache. If not found, it's invalid or expired.
     • If using the stateless approach, decrypt and verify the code.
     • Ensure the code has not been used before (requires a short-term cache of used code IDs to prevent replay).
  3. Validate PKCE: This is essential for security. Hash the incoming code_verifier using the method specified by code_challenge_method and verify that it matches the code_challenge associated with the authorization code. This proves the same client that started the flow is finishing it.
  4. Issue Tokens: If all checks pass, generate an access_token and, if requested (offline_access scope), a refresh_token.

To see this architectural logic translated into a concrete implementation, the following resource is invaluable.

3. Grant 2: The Client Credentials Grant

This grant type is designed for machine-to-machine (M2M) communication. There is no user involved. A client (e.g., a backend microservice) needs to access an API on its own behalf.

The Flow

The flow is much simpler and uses only the back-channel.

Architectural Design

This flow reuses the /token endpoint with different logic.

• Request: The client makes a POST request to /token with:

  • grant_type=client_credentials
  • client_id
  • client_secret
  • scope (optional, to request specific permissions for itself)

• Processing Logic:

  1. Authenticate Client: Verify the client_id and client_secret from the request against the client registry. This is the primary authentication step.
  2. Validate Scopes: Ensure the requested scopes are within the client's allowed_scopes.
  3. Issue Token: Generate an access token. The claims in this token represent the client application itself. For example, the sub (subject) claim would typically be the client_id.

4. Shared Component: The Token Factory

Both grant flows culminate in the generation of an access token. This logic can be encapsulated in a shared "Token Factory" component. A key architectural decision here is the format of the access token.

• JWT (JSON Web Token): A self-contained, signed JSON object.
  • Pros: Can be validated by Resource Servers statelessly by checking the signature against a public key, which is highly scalable.
  • Cons: Cannot be easily revoked before expiry. The contents are visible (though not tamperable).
• Opaque Token: A random, high-entropy string.
  • Pros: Can be revoked instantly. Reveals no internal information.
  • Cons: Requires the Resource Server to make a network call back to the Authorization Server (to an /introspect endpoint) for every validation, which is less scalable.

For modern distributed systems, JWTs are the common choice. When generating a JWT, your Token Factory must:

1. Have access to a private signing key.
2. Populate standard claims:
   • iss (issuer): The URL of your AS.
   • sub (subject): The User ID (for Auth Code grant) or Client ID (for Client Credentials grant).
   • aud (audience): The identifier of the Resource Server the token is for.
   • exp (expiration time): A short lifetime (e.g., 15 minutes) is best practice.
   • scope: The granted scopes.
3. Sign the token using a strong algorithm (e.g., RS256).

Conclusion

In this lesson, we designed the core architecture of an OAuth 2.0 Authorization Server. We moved from conceptual flows to concrete components, focusing on the two most important grant types for modern applications.

Key Takeaways:

• An Authorization Server's primary components are the Client Registry, the interactive /authorize endpoint, and the machine-to-machine /token endpoint.
• The Authorization Code grant uses a front-channel/back-channel split for security, preventing tokens from leaking into the browser. PKCE is a mandatory security layer for this flow.
• The Client Credentials grant is a simple back-channel flow for M2M authentication, where a client authenticates on its own behalf.
• Key design decisions include how to implement authorization codes (stateful cache vs. stateless encrypted blob) and access tokens (JWT vs. opaque), each with clear trade-offs.

Preview of the Next Lesson:

We've designed the server that creates tokens, but how are they structured, signed, and validated in a scalable and secure way? In our next lesson, we will zoom in on the "Token Factory" and the full lifecycle of a token by focusing on: "Design the token issuance and validation pipeline for an OAuth 2.0 server, including JWT structure, signing, and public key distribution." We'll cover topics like JWKS (JSON Web Key Set) endpoints, key rotation, and the responsibilities of the Resource Server in token validation.