Máy chủ uỷ quyền OAuth2/OIDC

Máy chủ uỷ quyền OAuth2/OIDC: cung cấp configurer cho các endpoint chuẩn (authorization, token, introspection, revocation, device, userinfo, logout, JWKS), hỗ trợ grant password/implicit mở rộng, đăng nhập OTP email/SMS, đăng nhập qua OIDC IdP, quản lý JWK và lưu authorization trên Redis. Dùng cho service đóng vai trò máy chủ định danh trung tâm.

Khi nào sử dụng

Xây dựng máy chủ uỷ quyền OIDC trung tâm cấp token cho các service khác.
Cần grant type password hoặc implicit (phần mở rộng do dependency này cung cấp) bên cạnh các grant chuẩn.
Cần luồng đăng nhập OTP qua email/SMS, đăng nhập qua OIDC IdP hoặc reset password.
Cần quản lý khóa ký JWT (load từ setting, xoay khóa an toàn).

Cài đặt

Thêm dependency vào pom.xml (không cần khai version vì đã được quản lý qua BOM):

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-oauth2</artifactId>
</dependency>

Version do BOM vn.govex.cloud:dependencies quản lý — xem Cài đặt.

Cấu hình

Property	Mô tả	Mặc định
`govex.iam.server.portal-public-base-url`	Base URL công khai của portal; dùng làm issuer và các endpoint OIDC.	rỗng
`govex.iam.server.console-public-base-url`	Base URL công khai của console, dùng để dựng liên kết trong luồng OAuth2/OIDC.	rỗng
`govex.iam.server.open-api-public-base-url`	Base URL công khai của Open API.	rỗng
`govex.iam.security.jump.default-redirect-url`	URL chuyển hướng mặc định khi luồng jump không chỉ định redirect target.	`/`

Cấu hình JWK được load từ setting govex.jwk.config (qua SettingRepository của govex-cloud-config), không khai báo trong application.yml.

Sử dụng

Bước 1 — cấu hình URL công khai:

govex:
  iam:
    server:
      portal-public-base-url: https://id.govex.vn
      console-public-base-url: https://console.govex.vn
      open-api-public-base-url: https://api.govex.vn
    security:
      jump:
        default-redirect-url: /

Bước 2 — lắp configurer của máy chủ uỷ quyền vào SecurityFilterChain của ứng dụng host; host chủ động thêm bằng http.with(...):

@Bean
@Order(1)
SecurityFilterChain authorizationServerSecurityFilterChain(HttpSecurity http) throws Exception {
    http.with(new OAuth2AuthorizationServerConfigurer());
    return http.build();
}

Token endpoint đã bao gồm sẵn converter/provider cho các grant type chuẩn và grant password mở rộng — không cần đăng ký thêm thủ công.

Bước 3 — bật form login và luồng reset password:

http.with(new FormLoginConfigurer<>());           // đăng nhập form tại /api/v1/login
http.with(new ResetPasswordHttpSecurityConfigurer<>());

Bước 4 — luồng đăng nhập qua OIDC IdP (cần govex-cloud-idp):

@Bean
SecurityFilterChain idpSecurityFilterChain(HttpSecurity http,
        IdpAuthenticationService idpAuthenticationService,
        RegisteredIdentityProviderClientRepository clientRepository) throws Exception {
    http.with(new OidcIdentityProviderConfigurer(idpAuthenticationService, clientRepository));
    return http.build();
}

Bước 5 — xoay khóa ký JWT khi cần (ví dụ theo lịch vận hành):

JwkRotationResult result = jwkRotationService.rotate(3);

Luồng hoạt động

Sơ đồ dưới đây mô tả luồng cấp token từ client tới máy chủ uỷ quyền:

Lưu ý

Ứng dụng host phải tự lắp các configurer/endpoint vào filter chain của mình.
Redis là bắt buộc: authorization và consent được lưu trên Redis (RedisOAuth2AuthorizationService, RedisOAuth2AuthorizationConsentService), đồng thời session cluster dùng spring-session-data-redis.
Cần SettingRepository cho JwkConfiguration và SecuritySettingService. Nếu cấu hình JWK thiếu khóa ký, quá trình khởi tạo bị từ chối để tránh vô hiệu hoá token đang lưu hành.
JwkRotationService.rotate(maxPreviousKeys) giữ 1–5 khóa xác minh chuyển tiếp, thao tác tuần tự và persist xuống database trước khi thay bộ ký trong bộ nhớ.
Cấu hình client OIDC của ứng dụng đọc từ bảng app_oidc_config (trong govex-cloud-application); luồng đăng nhập IdP cần IdentityProviderRepository (trong govex-cloud-idp).
Luồng OTP dùng chung URL /api/v1/login/otp với tham số recipient và code.
Ứng dụng tự khai báo changelog/schema của mình.

Khi nào sử dụng​

Cài đặt​

Cấu hình​

Sử dụng​

Luồng hoạt động​

Lưu ý​