OAuth 2.0

What is OAuth 2.0 — and Why Does it Exist?

OAuth 2.0 solves one specific problem: letting a third-party application act on a user's behalf against some resource — their Google contacts, their GitHub repositories, their shipping address stored with a carrier — without that application ever seeing the user's actual password for that resource, and with access limited to exactly the scope the user consented to. It is a delegated authorization protocol. It is explicitly not an authentication protocol, and conflating the two is the single most common OAuth2 mistake — "Login with Google" as most developers use it is actually built on OpenID Connect (OIDC), a thin identity layer added on top of OAuth2 specifically because OAuth2 alone never tells the client who the user is, only that the client was granted some access token.

// BEFORE — the "integration" asks the user to hand over their real password
public class ShippingSyncService {
    public void connectCarrierAccount(String carrierUsername, String carrierPassword) {
        // Our e-commerce backend now holds the customer's actual carrier password,
        // in full, indefinitely. It can do ANYTHING that account can do — not
        // just "read shipping addresses" — and a breach of OUR database now
        // compromises the customer's account on a system we don't even own.
        carrierApiClient.login(carrierUsername, carrierPassword);
    }
}

// AFTER — the user authorizes a SCOPED, REVOCABLE token, never sharing a password
public class ShippingSyncService {
    public String buildAuthorizationUrl(String state, String codeChallenge) {
        return UriComponentsBuilder.fromHttpUrl("https://carrier.example.com/oauth2/authorize")
            .queryParam("client_id", "shop-example-com")
            .queryParam("scope", "shipments:read")   // exactly this, nothing more
            .queryParam("response_type", "code")
            .queryParam("state", state)
            .queryParam("code_challenge", codeChallenge)
            .queryParam("code_challenge_method", "S256")
            .toUriString();
        // The customer authenticates directly with the carrier, on the carrier's
        // own login page — our application never sees their credentials at all,
        // only ever receives a token scoped to "read shipments," revocable by
        // the customer at any time from the carrier's own account settings.
    }
}

The Four Roles

Very often the Authorization Server and Resource Server are operated by the same organization (as in this example) or even the same physical service — the roles are still worth separating conceptually, because it's what makes sense of every flow diagram you'll encounter.

Authorization Code Flow with PKCE — the Only Flow You Should Use for User-Facing Clients

Of the several grant types OAuth2 originally defined, exactly one remains the current recommendation for anything a human logs into — a browser SPA, a mobile app, or a traditional server-rendered web app: Authorization Code with PKCE (Proof Key for Code Exchange, RFC 7636). Current best practice (RFC 9700) recommends PKCE for every client type, not just the traditionally "public" ones without a client secret — it closes an authorization-code-interception window that a client secret alone doesn't fully protect against.

/*
 * 1. Client generates a random "code_verifier", derives a "code_challenge"
 *    from it (SHA-256, base64url), and redirects the user's browser to the
 *    authorization server with that challenge attached.
 *
 * 2. User authenticates directly with the authorization server (never with
 *    the client) and consents to the requested scope.
 *
 * 3. Authorization server redirects back to the client's redirect_uri with a
 *    short-lived, single-use "authorization code."
 *
 * 4. Client exchanges the code for tokens by calling the authorization
 *    server's token endpoint DIRECTLY (server-to-server, not via the
 *    browser) — presenting the ORIGINAL code_verifier alongside the code.
 *
 * 5. Authorization server re-derives the challenge from the presented
 *    verifier and checks it matches what it received in step 1. If an
 *    attacker intercepted the authorization code in step 3 (e.g. via a
 *    misconfigured redirect_uri or a logged referrer), they still can't
 *    redeem it — they never had the original code_verifier, only the code.
 */

@Service
public class PkceService {

    public String generateCodeVerifier() {
        byte[] bytes = new byte[32];
        new SecureRandom().nextBytes(bytes);
        return Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
    }

    public String deriveCodeChallenge(String codeVerifier) throws NoSuchAlgorithmException {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(codeVerifier.getBytes(StandardCharsets.US_ASCII));
        return Base64.getUrlEncoder().withoutPadding().encodeToString(hash);
    }
}

Client Credentials Flow — When There is No User in the Loop

A nightly batch job that reconciles inventory counts against a supplier's API isn't acting on behalf of any specific customer — it's the e-commerce backend itself that needs authorization. The Client Credentials grant fits exactly this case: the client authenticates directly with its own client ID and secret, no resource owner or browser redirect involved at all.

# application.yml — a client registered purely for machine-to-machine calls
spring:
  security:
    oauth2:
      client:
        registration:
          supplier-api:
            provider: supplier
            client-id: ${SUPPLIER_CLIENT_ID}
            client-secret: ${SUPPLIER_CLIENT_SECRET}
            authorization-grant-type: client_credentials
            scope: inventory:sync
        provider:
          supplier:
            token-uri: https://api.supplier.example.com/oauth2/token

@Service
public class SupplierInventorySync {

    private final OAuth2AuthorizedClientManager clientManager;
    private final RestClient restClient;

    public SupplierInventorySync(OAuth2AuthorizedClientManager clientManager, RestClient.Builder builder) {
        this.clientManager = clientManager;
        this.restClient = builder.build();
    }

    public void syncInventory() {
        OAuth2AuthorizeRequest request = OAuth2AuthorizeRequest
            .withClientRegistrationId("supplier-api")
            .principal("inventory-sync-job")
            .build();

        OAuth2AuthorizedClient client = clientManager.authorize(request);
        String accessToken = client.getAccessToken().getTokenValue();
        // Spring's manager transparently handles requesting and caching this token
        // for its lifetime — application code never manually re-implements the
        // token request/refresh cycle.

        restClient.get().uri("https://api.supplier.example.com/inventory")
            .header(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken)
            .retrieve().body(InventorySnapshot.class);
    }
}

OpenID Connect — the Identity Layer OAuth2 Doesn't Provide

An OAuth2 access token tells a resource server "this bearer is authorized for this scope." It says nothing about who the human behind the request actually is, in a standardized, verifiable way — which is exactly the gap OpenID Connect fills, by adding a third token type to the Authorization Code response: the ID token, a JWT (see the previous page) whose claims describe the authenticated user directly (sub, email, name), signed by the identity provider.

# application.yml — "Sign in with Google" is OIDC, layered on top of OAuth2
spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: ${GOOGLE_CLIENT_ID}
            client-secret: ${GOOGLE_CLIENT_SECRET}
            scope: openid, profile, email   # "openid" scope is what makes this OIDC, not bare OAuth2

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .oauth2Login(oauth2 -> oauth2
                .userInfoEndpoint(userInfo -> userInfo.oidcUserService(customOidcUserService()))
            )
            .build();
    }
}

Scopes and Common Misconfigurations

A scope is the unit of consent — request the narrowest scope that accomplishes the task, since every scope granted is permanent standing access until the user or the authorization server revokes it. Requesting broad scopes "in case we need them later" is the OAuth2 equivalent of the over-privileged database credentials it was specifically designed to help avoid.

Best Practices and Common Pitfalls

Interview Questions