JWT, OAuth2 & Securing APIs

Introduction to OAuth2 & OpenID Connect

18 min Lesson 8 of 13

Introduction to OAuth2 & OpenID Connect

The JWT skills you have built so far are powerful — but they only cover one half of a modern security architecture: custom authentication you own end-to-end. In the real world, your service often needs to let users log in with Google or GitHub, or grant a mobile app limited access to your API without sharing a password. That is the problem OAuth 2.0 and OpenID Connect (OIDC) were designed to solve.

Why OAuth2 Exists — The Delegation Problem

Imagine a user wants to give a photo-printing service access to their Google Photos without handing over their Google password. Before OAuth, this was routinely "solved" by giving the third-party app the user's credentials — a practice that is both dangerous and impossible to revoke selectively.

OAuth 2.0 (RFC 6749, 2012) introduces a delegated authorization framework. The user authorises a third-party application to act on their behalf, but the application never learns the user's password. Instead it receives a scoped, time-limited access token. The user can revoke that token at any time without changing their password.

OAuth2 is an authorization framework, not an authentication protocol. It answers "what is this app allowed to do?" — not "who is this user?" OpenID Connect adds identity on top.

The Four Core Roles

  • Resource Owner — the end user (or system) that owns the protected data.
  • Client — the application requesting access (e.g., your Spring Boot service, a mobile app, an SPA).
  • Authorization Server — the server that authenticates the resource owner and issues tokens (e.g., Keycloak, Auth0, Okta, Google).
  • Resource Server — the API that holds the protected resources and validates tokens before serving them. In the next lesson, your Spring Boot app is the resource server.

Grant Types — How a Client Obtains a Token

A grant type defines the protocol flow a client uses to obtain an access token. OAuth 2.0 defines several; you need to know four.

1. Authorization Code Grant (+ PKCE)

This is the safest and most commonly used grant for applications that have a server-side component or a browser-based frontend. The flow:

  1. The client redirects the user's browser to the authorization server, supplying response_type=code, client_id, redirect_uri, and scope.
  2. The user authenticates and consents at the authorization server.
  3. The authorization server redirects back to redirect_uri with a short-lived authorization code.
  4. The client (server-side) exchanges the code for tokens by posting to the token endpoint — this call includes the client_secret, which never leaves the server.
  5. The authorization server returns an access_token, optionally a refresh_token, and (if OIDC) an id_token.

PKCE (Proof Key for Code Exchange) was originally designed for mobile apps that cannot keep a client secret, but RFC 9700 now mandates it for all public clients (SPAs, mobile). The client generates a random code_verifier, hashes it to produce a code_challenge, and sends the challenge in step 1. In step 4, it sends the plain verifier, and the authorization server checks it. This prevents an attacker who intercepts the code from being able to exchange it.

# Step 1: redirect the browser to: GET https://auth.example.com/authorize ?response_type=code &client_id=my-app &redirect_uri=https://app.example.com/callback &scope=openid%20profile%20email%20api:read &state=random-csrf-token &code_challenge=BASE64URL(SHA256(code_verifier)) &code_challenge_method=S256 # Step 4: server-to-server token exchange POST https://auth.example.com/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=AUTH_CODE_FROM_STEP_3 &redirect_uri=https://app.example.com/callback &client_id=my-app &client_secret=SECRET (confidential client only) &code_verifier=ORIGINAL_VERIFIER
Always validate the state parameter on the callback. It is a CSRF token — without checking it, an attacker can perform a CSRF login attack and link their account to the victim's session.

2. Client Credentials Grant

Used for machine-to-machine (M2M) communication — a microservice calling another microservice with no human user involved. The client authenticates directly with its own credentials; there is no browser redirect and no resource owner consent.

POST https://auth.example.com/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials &client_id=order-service &client_secret=ORDER_SERVICE_SECRET &scope=inventory:read inventory:write

The response is an access token scoped to what the service is allowed to do. This is the grant type you will configure in Spring Security when your microservice needs to call an upstream API.

3. Refresh Token Grant

Access tokens are intentionally short-lived (typically 5–15 minutes). When an access token expires, the client can use a refresh token — which was issued alongside the access token and has a longer lifetime — to silently obtain a new access token without bothering the user.

POST https://auth.example.com/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &refresh_token=REFRESH_TOKEN_VALUE &client_id=my-app &client_secret=SECRET
Refresh tokens are high-value secrets. Store them encrypted at rest (server-side session or encrypted cookie). If a refresh token is stolen, an attacker can mint new access tokens indefinitely until the authorization server revokes it. Always use refresh token rotation — each use of a refresh token invalidates the old one and issues a new one, so a replayed stolen token is detected.

4. Implicit Grant (Deprecated)

The implicit grant returned an access token directly from the authorization endpoint — no code exchange, no client secret. It was designed for browser SPAs before PKCE existed but has fundamental security flaws (tokens visible in the URL fragment, no sender binding). Do not use it in new applications. Replace it with Authorization Code + PKCE.

OpenID Connect (OIDC) — Adding Identity

OAuth 2.0 tells a resource server what the client is allowed to do. It does not tell your application who the user is. OpenID Connect is a thin identity layer built on top of OAuth 2.0 that adds exactly that.

When a client requests the openid scope, the authorization server includes an ID Token in the token response alongside the access token. An ID Token is a signed JWT that contains:

  • iss — the issuer URI (authorization server).
  • sub — the subject identifier (the user's unique ID at the issuer).
  • aud — the intended audience (your client ID).
  • exp and iat — expiry and issued-at timestamps.
  • nonce — a value you sent in the authorization request, preventing replay attacks.
  • Standard profile claims: name, email, picture, locale, etc. (gated on scopes like profile, email).
// Decoded OIDC ID Token payload example { "iss": "https://accounts.google.com", "sub": "110248495819764", "aud": "812741506391.apps.googleusercontent.com", "exp": 1718900000, "iat": 1718896400, "nonce": "0394852-3190485-2490358", "email": "alice@example.com", "email_verified": true, "name": "Alice Example", "picture": "https://lh3.googleusercontent.com/..." }

The client must validate the ID Token before trusting any claim: verify the signature against the issuer's JWKS endpoint, confirm iss, aud, exp, and nonce. Spring Security's OAuth2 Login does all of this automatically.

Scopes and the UserInfo Endpoint

OAuth2 scopes define what an access token is permitted to do. OIDC defines standard scopes:

  • openid — required to trigger OIDC; returns the ID Token.
  • profile — name, family_name, given_name, picture, locale.
  • email — email and email_verified.
  • address and phone — postal address, phone number.
  • offline_access — requests a refresh token.

Additional claims not present in the ID Token can be fetched from the UserInfo endpoint — a protected REST endpoint on the authorization server that accepts the access token and returns the user's attributes. Spring Security calls this automatically when you configure OAuth2 Login.

The Discovery Document

Any OIDC-compliant authorization server publishes a discovery document at /.well-known/openid-configuration. It lists every endpoint URL, supported scopes, signing algorithms, and JWKS URI. Spring Security reads this automatically when you set spring.security.oauth2.resourceserver.jwt.issuer-uri — you do not need to configure endpoints manually.

# application.yml — resource server minimal config spring: security: oauth2: resourceserver: jwt: issuer-uri: https://accounts.google.com # Spring fetches /.well-known/openid-configuration and validates tokens # using the published JWKS automatically

OAuth2 vs Your Custom JWT Setup

The JWTs you generated in lessons 3–5 are proprietary tokens — your application is both the issuer and the validator. That works well for simple systems. OAuth2/OIDC is appropriate when:

  • You want users to log in with a third-party identity provider (Google, GitHub, corporate IdP).
  • You operate multiple services and want a single authorization server to issue tokens all services trust.
  • You need delegated API access — allowing a third-party app to call your API on behalf of a user.
  • Compliance requires standards-based identity (FIDO2, enterprise SSO, audit trails).

Summary

OAuth 2.0 defines four roles (resource owner, client, authorization server, resource server) and multiple grant types for each scenario: Authorization Code + PKCE for user-facing apps, Client Credentials for machine-to-machine calls, and Refresh Token for silent renewal. OpenID Connect layers identity on top by adding the ID Token — a signed JWT carrying the user's identity claims. In the next lesson you will configure your Spring Boot application as an OAuth2 Resource Server that validates JWTs issued by an external authorization server.

Previous Lesson Refresh Tokens
Next Lesson Spring Security as a Resource Server
Back to Course