Blog
Software engineer
← Blog

So What's OAuth!

Marco Montorsi

OAuth authorization protocol

SecurityAuthorization

OAuth is an authorization protocol that allows applications to obtain access to third-party APIs on behalf of users without the need to share credentials.

Use Cases

Modern applications often rely on third-party service APIs. A common example is using an identity provider to centralize authentication and thus offer multiple services under unified user management. Very convenient but also very delicate to implement while respecting security aspects related to user session management. The OAuth flow, after an initial exchange of secrets (which we'll see later), authenticates through access tokens, thus limiting the communication of "API keys" but only tracking access tokens, which can also be historicized and/or limited by roles.

OAuth 2.0 Components

  • Resource Owner: the user who owns the data.
  • Resource Server: the server that hosts the user's resources.
  • Client: the application that requests authorization to access the data.
  • Authorization Server: the server that handles authorization requests and provides access tokens.

Client Types

  • Confidential Client: can securely store secrets and tokens.
  • Public Client: executed in the browser or on user devices without the ability to protect credentials.

Authorization Flows

1. Authorization Code Grant

This method is the most secure and is used for web and native applications.

  1. The user is redirected to the authorization server.
  2. After authentication and consent, the server provides an authorization code.
  3. The client exchanges the code for an access token.

2. Implicit Grant (Deprecated)

Historically used for client-side applications, today it's considered insecure because it exposes the token in the URL.

3. Resource Owner Password Credentials Grant

Used in legacy scenarios, where the user directly provides their credentials to the application.

4. Client Credentials Grant

Used when an application accesses APIs on its own behalf, without a specific user.

PKCE (Proof Key for Code Exchange)

PKCE is an extension of OAuth 2.0 designed to improve the security of the Authorization Code Grant, particularly in public client applications (e.g., mobile or JavaScript apps).

Why is PKCE needed?

Without PKCE, an attacker could intercept the authorization_code during redirection (a code interception attack). This code could then be exchanged for an access_token, allowing the attacker to impersonate the user.

With PKCE, instead, the client generates a code_verifier and a code_challenge that make the authorization code usable only by the client that requested it.

How does PKCE work?

  1. The client generates a code_verifier (a random string).
  2. From this string, it creates the code_challenge (SHA256 hash).
  3. When requesting authorization, it includes code_challenge in the request.
  4. When exchanging the authorization code for a token, the client also sends the code_verifier.
  5. The server recalculates the hash and verifies that it matches the original code_challenge.

Authorization request with PKCE

GET /authorize?
response_type=code
&client_id=<client_id>
&redirect_uri=<callback_uri>
&scope=read
&code_challenge=<hashed_verifier>
&code_challenge_method=S256

Exchanging the code for a token

POST /token
Host: authorizationserver.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<authorization_code>
&client_id=<client_id>
&redirect_uri=<callback_uri>
&code_verifier=<original_verifier>

💡 Without the code_verifier, the server will reject the request!

Complete Example of Authorization Code Grant Flow

  1. The user accesses the login page:

    GET /authorize?
response_type=code
&client_id=abc123
&redirect_uri=https://client.com/callback
&scope=read
&state=xyz123
&code_challenge=hashed_verifier
&code_challenge_method=S256

    The state parameter ensures that the response comes from the same client that initiated the request.

  2. The user grants authorization and is redirected:

    HTTP/1.1 302 Found
Location: https://client.com/callback?code=auth_code&state=xyz123

  3. The client exchanges the code for an access token:

    POST /token
Host: authorizationserver.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=auth_code
&client_id=abc123
&redirect_uri=https://client.com/callback
&code_verifier=original_verifier

  4. The server returns an access token:

    {
  "access_token": "xyz987",
  "token_type": "Bearer",
  "expires_in": 3600
}

Conclusion

OAuth 2.0 is a fundamental standard for modern API security. The correct use of OAuth ensures that applications can securely access user data without compromising personal credentials.

← All articles