0Pricing
Spring Boot 4 Complete Guide · Lesson

OAuth2 Client and Authorization Code Flow

Configure the OAuth2 client to obtain and refresh tokens via the authorization code grant.

OAuth2 Client and Authorization Code Flow is a free Spring Boot 4 Complete Guide lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Boot 4 Complete Guide learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why an OAuth2 Client?

When your Spring Boot app needs to act on behalf of a user against an external provider (Google, GitHub, Keycloak, Okta), it becomes an OAuth2 Client.

The client never sees the user's password. Instead it redirects the browser to the provider's authorization endpoint, the user logs in there, and the provider hands back an access_token (and optionally a refresh_token) that the client uses to call protected APIs.

  • Authorization Code grant is the recommended browser-based flow.
  • Spring Security's spring-boot-starter-oauth2-client implements the entire dance for you.

Adding the Starter

Bring in the OAuth2 client support. In Spring Boot 4 this lives in spring-boot-starter-oauth2-client, which transitively pulls in spring-security-oauth2-client and the JOSE/JWT libraries needed for OIDC.

This Maven dependency is all you need to enable login-with-provider and token acquisition.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Registering a Client via Properties

The fastest way to register a provider is through application.yml. Spring auto-binds these into a ClientRegistration.

  • client-id / client-secret — issued by the provider.
  • scope — openid, profile, email for OIDC login.
  • authorization-grant-type — authorization_code.
  • redirect-uri — the callback Spring exposes, usually {baseUrl}/login/oauth2/code/{registrationId}.
spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: spring-app
            client-secret: "${KEYCLOAK_SECRET}"
            authorization-grant-type: authorization_code
            scope: openid, profile, email
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
        provider:
          keycloak:
            issuer-uri: https://auth.example.com/realms/demo

Issuer Discovery vs. Manual Endpoints

For OIDC providers, setting issuer-uri lets Spring fetch the /.well-known/openid-configuration document at startup and auto-discover the authorization, token, JWK set, and userinfo endpoints.

For plain OAuth2 providers without discovery (e.g. classic GitHub), you must specify the endpoints yourself.

spring:
  security:
    oauth2:
      client:
        provider:
          github:
            authorization-uri: https://github.com/login/oauth/authorize
            token-uri: https://github.com/login/oauth/access_token
            user-info-uri: https://api.github.com/user
            user-name-attribute: id

Enabling oauth2Login in SecurityFilterChain

Wire the flow into your SecurityFilterChain. Calling oauth2Login() activates the full Authorization Code flow: unauthenticated requests get redirected to the provider, and the callback is handled automatically.

This is framework configuration, not a standalone program.

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/", "/error").permitAll()
                .anyRequest().authenticated())
            .oauth2Login(Customizer.withDefaults());
        return http.build();
    }
}

The Authorization Code Flow Step by Step

Once oauth2Login() is active, here is what happens behind the scenes:

  • 1. User hits a protected URL; Spring redirects the browser to /oauth2/authorization/{registrationId}.
  • 2. Spring sends the browser to the provider's authorization endpoint with response_type=code, state, and a PKCE code_challenge.
  • 3. The user authenticates and consents at the provider.
  • 4. The provider redirects back to /login/oauth2/code/{registrationId} carrying a one-time authorization code.
  • 5. Spring exchanges that code (server-to-server) at the token endpoint for tokens.

The browser never sees the access token in step 5 — it's a back-channel call.

Accessing the Authorized Client and Token

After login, the access token is stored in an OAuth2AuthorizedClient. Inject it with the @RegisteredOAuth2AuthorizedClient argument resolver to read the token your app obtained.

This token is what you attach when calling the downstream resource server.

@RestController
public class ApiController {

    @GetMapping("/token")
    public String token(
            @RegisteredOAuth2AuthorizedClient("keycloak")
            OAuth2AuthorizedClient client) {
        OAuth2AccessToken accessToken = client.getAccessToken();
        return "type=" + accessToken.getTokenType().getValue()
             + " expires=" + accessToken.getExpiresAt();
    }
}

Calling APIs with RestClient and the Token

Spring Boot 4 favors RestClient. Configure it with the OAuth2ClientHttpRequestInterceptor so it automatically attaches the bearer token from the authorized client (and refreshes it when needed).

  • The interceptor reads the registration id from the request attributes.
  • No manual Authorization header building required.
@Bean
RestClient restClient(OAuth2AuthorizedClientManager manager) {
    OAuth2ClientHttpRequestInterceptor interceptor =
        new OAuth2ClientHttpRequestInterceptor(manager);
    interceptor.setPrincipalResolver(
        new SecurityContextHolderPrincipalResolver());
    return RestClient.builder()
        .requestInterceptor(interceptor)
        .build();
}

The Authorized Client Manager

The OAuth2AuthorizedClientManager is the engine that obtains, caches, and refreshes tokens. You configure a provider chain describing which grants it supports.

Enabling refreshToken() here is what makes silent token renewal possible when an access token expires.

@Bean
OAuth2AuthorizedClientManager authorizedClientManager(
        ClientRegistrationRepository clients,
        OAuth2AuthorizedClientRepository authorizedClients) {

    OAuth2AuthorizedClientProvider provider =
        OAuth2AuthorizedClientProviderBuilder.builder()
            .authorizationCode()
            .refreshToken()
            .build();

    DefaultOAuth2AuthorizedClientManager manager =
        new DefaultOAuth2AuthorizedClientManager(clients, authorizedClients);
    manager.setAuthorizedClientProvider(provider);
    return manager;
}

How Refresh Works

To refresh tokens, two things must be true:

  • The provider issued a refresh_token — this typically requires the offline_access scope (Keycloak) or an offline grant.
  • The access token is expired (or within the configured clock skew) when the manager is next asked for the client.

When you call the API through a token-aware RestClient, the RefreshTokenOAuth2AuthorizedClientProvider detects expiry, posts grant_type=refresh_token to the token endpoint, and transparently swaps in the new access token. No user redirect is needed.

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            scope: openid, profile, offline_access
            authorization-grant-type: authorization_code

Modeling Token Expiry in Plain Java

The refresh decision boils down to comparing an expiry Instant against now, allowing for a clock-skew buffer. Here is that core logic as a complete standalone program you can run to see when a refresh would trigger.

import java.time.Duration;
import java.time.Instant;

public class Main {
    static boolean shouldRefresh(Instant expiresAt, Instant now, Duration skew) {
        return expiresAt == null || now.isAfter(expiresAt.minus(skew));
    }

    public static void main(String[] args) {
        Instant now = Instant.parse("2026-01-01T10:00:00Z");
        Duration skew = Duration.ofSeconds(60);

        Instant valid = now.plusSeconds(300);   // 5 min left
        Instant nearly = now.plusSeconds(30);    // inside skew window
        Instant expired = now.minusSeconds(10);

        System.out.println("valid  -> refresh? " + shouldRefresh(valid, now, skew));
        System.out.println("nearly -> refresh? " + shouldRefresh(nearly, now, skew));
        System.out.println("expired-> refresh? " + shouldRefresh(expired, now, skew));
    }
}

Quick Check

You configured oauth2Login() and call a downstream API through a token-aware RestClient. The access token expires after 5 minutes, but users stay on the page for 30 minutes without re-authenticating. What single change most directly enables silent token renewal without sending the user back to the login page?

Recap

You configured Spring Boot 4 as an OAuth2 client driving the Authorization Code flow:

  • Starter: spring-boot-starter-oauth2-client enables the flow.
  • Registration: client-id/secret, authorization_code grant, scopes, and a redirect-uri; OIDC providers auto-discover endpoints via issuer-uri.
  • Activation: oauth2Login() performs the redirect, PKCE code exchange, and callback handling.
  • Using tokens: inject @RegisteredOAuth2AuthorizedClient or call APIs via a token-aware RestClient backed by an OAuth2AuthorizedClientManager.
  • Refresh: request a refresh-capable scope and build the manager with .refreshToken() so expired access tokens renew silently via grant_type=refresh_token.

Frequently asked questions

Is the “OAuth2 Client and Authorization Code Flow” lesson free?

Yes — the full text of “OAuth2 Client and Authorization Code Flow” is free to read here on the web, and the Spring Boot 4 Complete Guide course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Boot 4 Complete Guide course, upgrade to CoddyKit PRO.

What will I learn in “OAuth2 Client and Authorization Code Flow”?

Configure the OAuth2 client to obtain and refresh tokens via the authorization code grant. You practise Spring Boot 4 Complete Guide with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Boot 4 Complete Guide?

No prior experience is required. Spring Boot 4 Complete Guide on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “OAuth2 Client and Authorization Code Flow” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Boot 4 Complete Guide lesson?

Yes. Every Spring Boot 4 Complete Guide lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Resource Server JWT Validation and Claims
  2. OAuth2 Client and Authorization Code Flow
  3. Method Security with SpEL and Custom Voters
  4. Opaque Token Introspection and Token Exchange
← Back to Spring Boot 4 Complete Guide