Spring Boot 4 Complete Guide · درس

عميل OAuth2 وتدفق رمز التفويض

تهيئة عميل OAuth2 للحصول على الرموز وتحديثها عبر منح رمز التفويض.

عميل OAuth2 وتدفق رمز التفويض درس مجاني في Spring Boot 4 Complete Guide على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Spring Boot 4 Complete Guide، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Spring Boot 4 Complete Guide 4 دروس في المجموع.

بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.

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.

الأسئلة الشائعة

هل درس «عميل OAuth2 وتدفق رمز التفويض» مجاني؟

نعم — نص درس «عميل OAuth2 وتدفق رمز التفويض» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Spring Boot 4 Complete Guide، انتقل إلى CoddyKit PRO. تتضمن دورة Spring Boot 4 Complete Guide 4 دروس في المجموع.

ماذا ستتعلم في «عميل OAuth2 وتدفق رمز التفويض»؟

تهيئة عميل OAuth2 للحصول على الرموز وتحديثها عبر منح رمز التفويض. تتمرن على Spring Boot 4 Complete Guide مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Spring Boot 4 Complete Guide؟

لا تُشترط خبرة سابقة. Spring Boot 4 Complete Guide على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «عميل OAuth2 وتدفق رمز التفويض»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Spring Boot 4 Complete Guide هذا؟

نعم. كل درس في Spring Boot 4 Complete Guide يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

التحقق من JWT ومطالباته في خادم الموارد
عميل OAuth2 وتدفق رمز التفويض
أمان الأساليب باستخدام SpEL والمصوّتين المخصصين
فحص الرموز غير الشفافة وتبادل الرموز

← العودة إلى Spring Boot 4 Complete Guide