0Pricing
Spring Boot 4 Complete Guide · Aula

Cliente OAuth2 e fluxo do código de autorização

Configure o cliente OAuth2 para obter e atualizar tokens por meio da concessão de código de autorização.

Cliente OAuth2 e fluxo do código de autorização é uma aula grátis de Spring Boot 4 Complete Guide no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Spring Boot 4 Complete Guide, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Spring Boot 4 Complete Guide inclui 4 aulas no total.

Partes desta aula ainda não foram traduzidas e aparecem em inglês.

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.

Perguntas Frequentes

A aula “Cliente OAuth2 e fluxo do código de autorização” é grátis?

Sim — o texto completo de “Cliente OAuth2 e fluxo do código de autorização” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Spring Boot 4 Complete Guide, atualize para CoddyKit PRO. O curso de Spring Boot 4 Complete Guide inclui 4 aulas no total.

O que vou aprender em “Cliente OAuth2 e fluxo do código de autorização”?

Configure o cliente OAuth2 para obter e atualizar tokens por meio da concessão de código de autorização. Você pratica Spring Boot 4 Complete Guide com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Spring Boot 4 Complete Guide?

Nenhuma experiência prévia é necessária. Spring Boot 4 Complete Guide no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Cliente OAuth2 e fluxo do código de autorização”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Spring Boot 4 Complete Guide?

Sim. Cada aula de Spring Boot 4 Complete Guide inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Validação de JWT e declarações em servidor de recursos
  2. Cliente OAuth2 e fluxo do código de autorização
  3. Segurança de métodos com SpEL e votantes personalizados
  4. Introspecção de Tokens Opacos e Troca de Tokens
← Voltar para Spring Boot 4 Complete Guide