OAuth 2.0

The security protocols we’ve discussed so far (HTTP authentication, API keys, JWTs) provide the building blocks for secure API access. However, they often fall short when it comes to robust authorization, which determines what actions a user or application is permitted to perform.  This is where OAuth 2.0 comes in, offering a standardized and widely adopted framework for API authorization.

OAuth 2.0, short for Open Authorization 2.0, tackles some key limitations of standalone authentication methods:

• Secure Key Transmission:  API keys, while useful for identifying applications, require a secure way to be transmitted to prevent interception.
• Token Security:  Repeatedly sending authentication tokens with each request increases the risk of compromise.

OAuth 2.0 provides a standardized approach to authorization, allowing applications to access resources on behalf of a user without directly exposing their credentials.  This standardization allows security experts to focus on improving a widely used framework, reducing the risk of vulnerabilities associated with custom solutions.

OAuth 2.0:

OAuth 2.0 is an industry-standard framework for token-based authorization, born from a collaboration between Google and Twitter in 2010.  It enables applications to access user data on other platforms without requiring users to share their passwords with those applications.

Example:

Imagine you’re signing up for a food delivery service and it gives you the option to “Sign in with Google.”  Behind the scenes, this seamless integration likely relies on OAuth 2.0.

OAuth 2.0 accomplishes this by using access tokens, which are time-limited credentials that grant specific permissions to applications.  Here’s why access tokens are preferred over passwords:

• Limited Scope:  Access tokens typically grant access to specific resources for a limited time.
• Enhanced Security:  User credentials (passwords) are never shared with the third-party application.

Understanding Roles

OAuth 2.0 involves four key entities:

1. Resource Owner:  The user who owns the protected resources (e.g., their Google account data).
2. Resource Server:  The server that hosts the protected resources (e.g., Google’s servers).
3. Client:  The application requesting access to the resources on behalf of the user (e.g., the food delivery app).
4. Authorization Server:  The server that issues access tokens to the client after verifying the user’s identity and obtaining their consent.

OAuth 2.0 Flows

OAuth 2.0 defines several flows, or authorization grant types, each suited for specific scenarios.

graph TD
    O[OAuth 2.0 Flows]

    O --> AC[Authorization Code]
    O --> ACPKCE[Authorization Code with PKCE]
    O --> IG[Implicit Grant]
    O --> CC[Client Credentials]

    AC --> AC1[For server-side apps]
    AC --> AC2[Most secure]
    AC --> AC3[Returns auth code, exchanged for token]

    ACPKCE --> ACPKCE1[For mobile/native apps]
    ACPKCE --> ACPKCE2[Protects against code interception]
    ACPKCE --> ACPKCE3[Uses code verifier and challenge]

    IG --> IG1[For single-page apps]
    IG --> IG2[Returns token directly]
    IG --> IG3[Less secure, being phased out]

    CC --> CC1[For machine-to-machine auth]
    CC --> CC2[No user involvement]
    CC --> CC3[Uses client ID and secret]

    classDef flow fill:#f9f,stroke:#333,stroke-width:2px;
    classDef char fill:#ff9,stroke:#333,stroke-width:2px;
    class AC,ACPKCE,IG,CC flow;
    class AC1,AC2,AC3,ACPKCE1,ACPKCE2,ACPKCE3,IG1,IG2,IG3,CC1,CC2,CC3 char;

Here’s a brief overview of the common flows:

• Authorization Code:  The most common flow, often used for web applications. The user is redirected to the authorization server to grant permission. An authorization code is then exchanged for an access token.
• Authorization Code with Proof Key for Code Exchange (PKCE):  An enhanced version of the authorization code flow, designed for mobile and single-page applications (SPAs) where storing client secrets is risky.
• Implicit Grant:  Similar to the authorization code flow but returns an access token directly without an intermediate code.  Generally considered less secure and not recommended for new implementations.
• Client Credentials:  Used when the client application needs to access its own resources, not user data.  No user interaction is required.

Let’s examine each flow in more detail:

Authorization Code Flow

The authorization code flow is widely used for web applications that can securely store client secrets.

sequenceDiagram
    participant User
    participant Client as Client (Web App)
    participant AuthServer as Authorization Server
    participant API as Resource Server

    User->>Client: Initiate login
    Client->>AuthServer: Redirect to Auth Server<br/>(client_id, redirect_uri, scope)
    AuthServer->>User: Present login and consent form
    User->>AuthServer: Authenticate and grant permission
    AuthServer->>Client: Redirect with authorization code
    Client->>AuthServer: Exchange code for tokens<br/>(code, client_id, client_secret)
    AuthServer->>Client: Return access token (and refresh token)
    Client->>API: API request with access token
    API->>API: Validate token
    API->>Client: Return requested resource

    Note over Client,API: Client can now make authenticated API requests

1. The client redirects the user to the authorization server, including its client ID and requested permissions (scope).

Example:

https://accounts.google.com/o/oauth2/v2/auth?

response_type=code&

client_id=YOUR_CLIENT_ID&

scope=openid%20profile%20email&

redirect_uri=YOUR_REDIRECT_URI

2. The authorization server prompts the user to log in (if needed) and approve the client’s access request.
3. Upon approval, the authorization server redirects the user back to the client with an authorization code as a query parameter.
4. The client exchanges this authorization code for an access token by making a request to the authorization server, including its client ID, client secret, and the authorization code.
5. The authorization server verifies the request and issues an access token to the client.

Key Point:  The authorization code is a temporary credential used only for exchanging it for an access token. It’s not the actual access token itself.

Authorization Code with PKCE:  Securing Public Clients

Public clients, such as mobile apps and SPAs, cannot securely store client secrets, making them vulnerable to attacks. Proof Key for Code Exchange (PKCE) addresses this by introducing a code verifier (a random secret generated by the client) and a code challenge (a transformed version of the code verifier).

sequenceDiagram
    participant User
    participant Client as Client (Mobile App/SPA)
    participant AuthServer as Authorization Server
    participant API as Resource Server

    Note over Client: Generate code_verifier<br/>Generate code_challenge

    User->>Client: Initiate login
    Client->>AuthServer: Authorization Request<br/>(client_id, redirect_uri, code_challenge)
    AuthServer->>User: Present login and consent form
    User->>AuthServer: Authenticate and grant permission
    AuthServer->>Client: Redirect with authorization code
    Client->>AuthServer: Token Request<br/>(code, client_id, code_verifier)
    AuthServer->>AuthServer: Verify code_verifier matches<br/>original code_challenge
    AuthServer->>Client: Return access token (and refresh token)
    Client->>API: API request with access token
    API->>API: Validate token
    API->>Client: Return requested resource

    Note over Client,API: Client can now make authenticated API requests

The key difference from the standard authorization code flow is that the client:

• Generates a code verifier and code challenge before initiating the flow.
• Includes the code challenge in the initial authorization request.
• Presents the code verifier when exchanging the authorization code for an access token.

The authorization server validates the code verifier against the stored code challenge, proving the client’s authenticity even without a client secret.  This effectively prevents an attacker from intercepting the authorization code and obtaining an access token.

Implicit Grant Flow

The implicit grant flow was once common for public clients but is now generally discouraged due to security concerns.  It skips the authorization code exchange step, directly returning an access token to the client.

sequenceDiagram
    participant UserAgent as User's Browser
    participant Client as Your Web App
    participant AuthServer as Authorization Server
    
    UserAgent->>Client: Initiate login
    Client->>AuthServer: Redirect to authorization endpoint (with `response_type=token`)
    activate AuthServer
    AuthServer->>UserAgent: Request user authentication (if needed)
    UserAgent->>AuthServer: User provides credentials
    AuthServer->>UserAgent: Redirect to redirect URI with access token in URL fragment (#access_token=...) 
    deactivate AuthServer
    UserAgent->>Client: Browser follows redirect (token is in fragment)
    Note over Client: Client extracts token from URL fragment 

However, this approach risks the access token being exposed in the browser’s history or through other means.

Client Credentials Flow

The client credentials flow is used when an application needs to access its own data, not user data.  The client authenticates with the authorization server using its client ID and client secret, receiving an access token without any user interaction.

sequenceDiagram
    participant ClientApp as Client Application
    participant AuthServer as Authorization Server

    ClientApp->>AuthServer: Request access token (grant_type=client_credentials)
    activate ClientApp
    Note over ClientApp,AuthServer: Includes Client ID and Client Secret 
    deactivate ClientApp
    activate AuthServer
    AuthServer->>ClientApp: Respond with access token
    Note over ClientApp,AuthServer: Access token scoped to client's resources
    deactivate AuthServer

Example:  A backend service might use the client credentials flow to access configuration data stored on a separate authorization server.

Choosing the Right OAuth 2.0 Flow:  Factors to Consider

Selecting the appropriate OAuth 2.0 flow depends on your application type, security requirements, and the capabilities of the authorization server you’re interacting with.

Notes:

• Token refreshability for the Client Credentials flow can vary depending on the specific implementation of the authorization server.
• The Authorization Code flow with PKCE is becoming the recommended standard for most application types, including those traditionally using the Implicit flow.
• The Implicit flow is considered less secure and is being phased out in favor of the Authorization Code flow with PKCE for Single Page Applications.

OAuth 2.0:  Authorization, Not Authentication

It’s crucial to remember that OAuth 2.0 is primarily an authorization framework, not an authentication protocol.  It focuses on granting access permissions based on access tokens.  The actual authentication of the client (verifying its identity) is often handled by other mechanisms, such as OpenID Connect.