Phần lớn lỗi OAuth2 trong Spring không nằm ở thư viện mà ở việc gọi nhầm hai thứ khác nhau: đăng nhập bằng Google và chấp nhận token Google. Một cái là OAuth2 Client, một cái là Resource Server. Bài này làm đúng cái thứ nhất và vạch ranh giới với cái thứ hai.
Mục lục
Cập nhật 2026
- Spring Security 7.1.2 trên Spring Boot 4.1.2 và Spring Framework 7.0.10, baseline Java 25 LTS.
WebSecurityConfigurerAdapterđã bị xóa từ Security 6; toàn bộ cấu hình dùng lambda,and()không còn trong DSL. spring-boot-starter-webđược thay bằngspring-boot-starter-webmvctrong Boot 4.1. Với OAuth2 login, bạn cần thêmspring-boot-starter-oauth2-client.- Implicit grant và password grant không còn là lựa chọn cho ứng dụng mới. Authorization Code + PKCE là luồng mặc định; Spring bật PKCE tự động cho public client (không có client secret, hoặc
client-authentication-method: none). - Spring Authorization Server là authorization server chính thức của Spring; bài này không pin version vì nó release theo nhịp riêng. Nếu chỉ dùng Google/GitHub làm IdP, bạn không cần chạy nó.
Bốn vai trò trong một lần đăng nhập
OAuth2 là khung ủy quyền, không phải giao thức xác thực; OpenID Connect (OIDC) thêm lớp xác thực lên trên. Hiểu bốn vai trò giúp bạn đặt cấu hình đúng chỗ:
| Vai trò | Trong ví dụ Google | Trách nhiệm |
|---|---|---|
| Resource owner | Người dùng | Sở hữu dữ liệu và đồng ý cấp quyền. |
| Client | Ứng dụng Spring của bạn | Xin quyền, nhận code, đổi lấy token. |
| Authorization server | accounts.google.com |
Xác thực người dùng, phát code và token. |
Vai trò thứ tư là resource server — nơi chứa dữ liệu được bảo vệ, ở đây là userinfo và các API Google. Đừng gộp authorization server và resource server thành một khái niệm “Google”.
Authorization Code + PKCE: luồng duy nhất còn đúng
Luồng đầy đủ gồm bốn bước:
- Ứng dụng chuyển hướng trình duyệt tới authorization endpoint với
client_id,redirect_uri,scope,state,code_challengevàcode_challenge_method=S256. - Người dùng đăng nhập và đồng ý tại nhà cung cấp; nhà cung cấp chuyển hướng về
redirect_urikèmcodengắn hạn vàstate. - Ứng dụng kiểm tra
state, gửicodecùngcode_verifiertới token endpoint, nhận access token và (với OIDC)id_token. - Ứng dụng dùng access token để gọi userinfo hoặc API của mình; token không xuất hiện trong URL trình duyệt.
Implicit grant chết vì token nằm trong URL fragment — dễ lọt vào lịch sử trình duyệt, log proxy và Referer, và mọi JavaScript đều đọc được. Nó không có bước đổi code nên không xác thực client, không có PKCE. Password grant chết vì ứng dụng phải thu mật khẩu người dùng, đúng thứ OAuth2 sinh ra để tránh. Cả hai đã bị loại khỏi OAuth 2.1.
PKCE chặn việc code bị đánh cắp trên đường về. Client tạo code_verifier ngẫu nhiên, gửi hash SHA-256 (code_challenge) lúc xin code, và gửi lại verifier gốc lúc đổi token. Kẻ đánh cắp code không có verifier nên không đổi được token. Public client như SPA hoặc mobile bắt buộc dùng PKCE vì không giữ được secret; confidential client có secret thì Spring không tự bật PKCE, nhưng nên đặt clientSettings.requireProofKey=true nếu IdP hỗ trợ.
Scope, authority và role không phải một thứ
| Khái niệm | Ai tạo ra | Dùng để |
|---|---|---|
| Scope | Client xin, người dùng đồng ý, server cấp | Giới hạn quyền truy cập tài nguyên; xuất hiện trong token và màn hình consent. |
| Authority | Spring Security | Kiểm tra bằng hasAuthority(); là GrantedAuthority gắn vào Authentication. |
| Role | Ứng dụng của bạn | Quy ước authority có tiền tố ROLE_, kiểm tra bằng hasRole(). |
Đây là chỗ hiểu sai phổ biến: scope không tự biến thành authority trong OAuth2 login. Sau khi đăng nhập, Spring gắn authority mặc định OAUTH2_USER (OAuth2) hoặc OIDC_USER (OIDC), không phải ROLE_USER; vì vậy hasRole("USER") không khớp nếu bạn không map thêm. Ở resource server, JwtGrantedAuthoritiesConverter lại đọc claim scope và tạo authority SCOPE_x. Hai phía dùng “scope” nhưng hành vi khác.
Nếu cần phân quyền theo vai trò nội bộ, map rõ trong custom OAuth2UserService/OidcUserService, hoặc gắn authority từ bản ghi người dùng sau khi provision. Cách chặn endpoint theo role có trong bài Role-Based Access Control trong Spring Security.
OpenID Connect: id_token và userinfo
Khi scope có openid, nhà cung cấp trả thêm id_token — một JWT chứa danh tính. Các claim quan trọng: iss, sub, aud, exp, iat và nonce (chống replay trong luồng login). Spring kiểm tra chữ ký, issuer, audience, thời hạn và nonce trong OidcUserService; đừng tự parse rồi tin claim mà chưa verify.
OidcUser có hai nguồn dữ liệu: getClaims() từ id_token, và getUserInfo() từ userinfo endpoint (gọi bằng access token). Ưu tiên sub và claim đã verify cho danh tính; dùng userinfo cho hồ sơ hiển thị.
Google là OIDC; GitHub thì không. GitHub OAuth App không trả id_token, nên danh tính lấy từ API /user với id, login, name, email; email chỉ có khi người dùng để public. Vì vậy principal của GitHub là OAuth2User, không phải OidcUser — khác biệt mà nhiều bài viết cũ bỏ qua.
Cấu hình Google và GitHub trong application.yml
# File: src/main/resources/application.yml
spring:
security:
oauth2:
client:
registration:
google:
client-id: ${GOOGLE_CLIENT_ID}
client-secret: ${GOOGLE_CLIENT_SECRET}
scope:
- openid
- profile
- email
github:
client-id: ${GITHUB_CLIENT_ID}
client-secret: ${GITHUB_CLIENT_SECRET}
scope:
- read:user
- user:email
Boot đã biết endpoint của Google và GitHub qua CommonOAuth2Provider, nên không cần khai báo authorization-uri, token-uri hay user-info-uri. Với IdP nội bộ, thêm khối provider và lấy URI từ tài liệu chính thức.
Hai chi tiết dễ sai. Đừng bỏ openid khỏi scope Google: không có nó, Google trả OAuth2 thuần, không có id_token, và @AuthenticationPrincipal OidcUser không nhận được gì. GitHub cần user:email nếu muốn email, nhưng riêng scope này chưa đủ để trường email trong /user có giá trị; phải gọi endpoint email riêng và chọn địa chỉ primary đã verify.
Redirect URI mặc định là {baseUrl}/login/oauth2/code/{registrationId}, tức http://localhost:8080/login/oauth2/code/google và .../github khi chạy local. Giá trị này phải khớp chính xác với Google Cloud Console hoặc GitHub OAuth App: cùng scheme, host, port, path, kể cả dấu / cuối. Sau reverse proxy, bật server.forward-headers-strategy: framework để baseUrl dùng https và host công khai thay vì localhost.
SecurityFilterChain và trang login
// File: src/main/java/vn/evotek/shop/security/SecurityConfig.java
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
SecurityFilterChain web(HttpSecurity http, AuthenticationSuccessHandler jitSuccessHandler)
throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/", "/login", "/error", "/css/**").permitAll()
.anyRequest().authenticated())
.oauth2Login(oauth2 -> oauth2
.loginPage("/login")
.successHandler(jitSuccessHandler)
.failureUrl("/login?error"))
.logout(logout -> logout
.logoutSuccessUrl("/")
.invalidateHttpSession(true)
.deleteCookies("JSESSIONID"));
return http.build();
}
}
Không cần giao diện riêng thì dùng .oauth2Login(Customizer.withDefaults()); Boot tự tạo trang login tại /login với link cho từng registration. Với trang tùy chỉnh, permit /login và trỏ người dùng tới URL do Spring sinh ra: /oauth2/authorization/google, /oauth2/authorization/github. Không tự đặt callback URL khác.
oauth2Login() cần HTTP session để lưu authorization request và SecurityContext. Đừng đặt SessionCreationPolicy.STATELESS cho ứng dụng browser có login; state và code verifier sẽ mất. CSRF cũng nên để mặc định bật: state bảo vệ OAuth2 request, CSRF token bảo vệ form login/logout.
Đọc người dùng trong controller
// File: src/main/java/vn/evotek/shop/web/AccountController.java
@Controller
public class AccountController {
@GetMapping("/dashboard")
String dashboard(@AuthenticationPrincipal OidcUser user, Model model) {
if (user == null) {
return "redirect:/login";
}
model.addAttribute("name", user.getFullName());
model.addAttribute("email", user.getEmail());
model.addAttribute("subject", user.getSubject());
model.addAttribute("claims", user.getClaims());
return "dashboard";
}
}
Đoạn trên chỉ đúng cho Google, vì GitHub không có OidcUser. Nếu một endpoint phục vụ cả hai, dùng @AuthenticationPrincipal OAuth2User user — OidcUser là subtype của OAuth2User. user.getName() trả sub với OIDC và id với GitHub; getAttributes() chứa attribute thô. Đừng dựa vào key name cho mọi provider: name của GitHub có thể null.
Muốn lấy đúng một claim, dùng biểu thức @AuthenticationPrincipal(expression = "claims['sub']") String subject cho OIDC, hoặc attributes['id'] cho GitHub. Đừng đổ nguyên getAttributes() ra view hoặc log.
Just-in-time provisioning: map OAuth2 user vào user nội bộ
Ứng dụng thật cần một bản ghi người dùng trong database. Cách đơn giản và provider-agnostic là provision sau khi authentication thành công. Khóa danh tính phải là cặp (provider, subject), không phải email:
// File: src/main/java/vn/evotek/shop/security/JitProvisioningSuccessHandler.java
@Component
public class JitProvisioningSuccessHandler implements AuthenticationSuccessHandler {
private final LocalUserService localUsers;
public JitProvisioningSuccessHandler(LocalUserService localUsers) {
this.localUsers = localUsers;
}
@Override
public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response,
Authentication authentication) throws IOException {
if (authentication instanceof OAuth2AuthenticationToken token) {
OAuth2User user = token.getPrincipal();
Map<String, Object> attributes = user.getAttributes();
String email = (String) attributes.get("email");
String displayName = (String) attributes.get("name");
if (displayName == null) {
displayName = (String) attributes.get("login");
}
localUsers.provision(
token.getAuthorizedClientRegistrationId(),
user.getName(),
email,
displayName);
}
response.sendRedirect("/dashboard");
}
}
getAuthorizedClientRegistrationId() trả google/github; user.getName() là sub với OIDC và id với GitHub. Hai giá trị ổn định qua các lần đăng nhập, còn email có thể đổi; unique constraint đặt trên (provider, subject).
// File: src/main/java/vn/evotek/shop/user/LocalUserService.java
@Service
public class LocalUserService {
private final LocalUserRepository users;
public LocalUserService(LocalUserRepository users) {
this.users = users;
}
@Transactional
public LocalUser provision(String provider, String subject, String email, String displayName) {
return users.findByProviderAndSubject(provider, subject)
.map(user -> {
user.updateProfile(email, displayName);
return user;
})
.orElseGet(() -> users.save(
new LocalUser(provider, subject, email, displayName)));
}
}
findByProviderAndSubject phải là truy vấn theo unique key, không phải findByEmail. Nếu cần gán role ngay lúc authentication, làm trong custom OAuth2UserService cho GitHub và OidcUserService cho Google — userService(...) không tự áp dụng cho OIDC, lỗi hay gặp khi chỉ cấu hình một service.
Đăng nhập bằng Google không phải nhận token Google
| Tiêu chí | OAuth2 Client (login) | Resource Server (API) |
|---|---|---|
| Mục đích | Người dùng đăng nhập qua Google/GitHub | API chấp nhận access token do provider cấp |
| Cấu hình Spring | oauth2Login() và registration.* |
oauth2ResourceServer().jwt() và issuer-uri |
| Trạng thái | Redirect, session cookie, CSRF bật | Stateless, Authorization: Bearer |
Đừng đặt oauth2Login() trên API chỉ nhận Bearer token, hay oauth2ResourceServer() trong ứng dụng browser rồi mong có trang login. Cách cấu hình issuer-uri, jwk-set-uri, audience và map role cho API nằm trong bài JWT Authentication trong Spring Boot.
Bẫy thường gặp
- Để lộ client secret. Không commit vào
application.yml, không nhúng vào JavaScript; dùng biến môi trường hoặc secret manager và có kế hoạch rotate. SPA/mobile nên là public client dùng PKCE, không giữ secret. - Sai redirect URI. Google và GitHub so khớp chuỗi chính xác;
localhostkhác127.0.0.1,httpkháchttps, thiếu dấu/cũng fail. Sau proxy, thiếu forward-header khiến Spring sinh redirecthttp://localhost:8080. - Dùng access token như danh tính. Access token là vé gọi API, có thể opaque và xoay vòng; danh tính lấy từ
id_tokenđã verify hoặc userinfo, khóa tài khoản bằngiss+sub. Đừng log token hay đưa token vào URL. - Bỏ qua email GitHub.
user:emaillà scope cần thiết, nhưngemailtrong/uservẫn có thể null. Gọi endpoint email, chọn primary đã verify, và không tạo tài khoản chỉ vì trùng email. - Lưu token trong localStorage. Bất kỳ XSS nào cũng đọc được. Với browser app, giữ token phía server trong
OAuth2AuthorizedClienthoặc session; trình duyệt chỉ giữ cookieHttpOnly. SPA nên cân nhắc BFF pattern. - Tắt CSRF hoặc session để “cho dễ”. OAuth2 login cần session và
state; tắt đi sẽ mở lại CSRF/login-CSRF. Logout mặc định làPOST /logoutkhi CSRF bật, nên link GET không hoạt động — dùng form có CSRF token. - Liên kết tài khoản bằng email chưa verify. Kẻ tấn công tạo tài khoản ở provider khác với email của người khác rồi chiếm tài khoản. Chỉ auto-link khi email đã được provider xác minh; còn lại yêu cầu liên kết thủ công.
Logout và session
logout() ở trên xóa session và cookie JSESSIONID, nhưng chỉ kết thúc phiên trong ứng dụng của bạn; phiên Google/GitHub vẫn còn. OIDC có logout tập trung qua OidcClientInitiatedLogoutSuccessHandler, cần end_session_endpoint trong metadata provider. Không phải provider nào cũng công bố endpoint này, và không được tự bịa URL. Với nhiều instance, session bộ nhớ không dùng chung được; dùng Spring Session với Redis hoặc sticky session có kiểm soát.
Khi nào dùng gì
| Tình huống | Chọn | Không chọn |
|---|---|---|
| Web app có browser session, login Google/GitHub | oauth2Login() + registration |
Resource server cho chính trang login |
| REST API nhận token từ mobile/SPA/service khác | oauth2ResourceServer().jwt() |
oauth2Login() trong API |
| Bạn phát hành token cho bên thứ ba | Spring Authorization Server | Tự viết authorization server |
Nhìn trước 2027
OAuth 2.1 gom các phần đã ổn định: PKCE cho mọi client, bỏ implicit và password. Token binding và DPoP sẽ phổ biến hơn để giảm giá trị của access token bị đánh cắp. Spring Security 7.2.0-RC1 là preview; API passkey/WebAuthn trong 7.1 nên kiểm tra tài liệu trước khi pin. Việc cần làm trong 2027 vẫn là PKCE, xoay secret và bỏ token trong URL.
Checklist trước khi deploy
- Client secret từ biến môi trường/secret manager, có kế hoạch rotate; không có secret trong repo hoặc front-end.
- Redirect URI khớp chính xác ở Google/GitHub; bật forward headers nếu chạy sau proxy.
- Scope tối thiểu: Google có
openid profile email; GitHub córead:user user:emailnếu cần email. - Danh tính lưu theo
(provider, subject)với unique constraint; email chỉ là thuộc tính. - CSRF và session bật cho login, logout là POST; token không nằm trong localStorage hay log.
- Đã test Google (OIDC) và GitHub (OAuth2), gồm email GitHub null và trường hợp từ chối consent.
Đọc tiếp
Nền tảng xác thực và phân quyền nằm ở Spring Security 101: Xác thực vs Phân quyền. Cách cấu hình form login, password encoder và các thành phần cơ bản có trong Hướng dẫn thực hành cấu hình xác thực trong Spring.



