Chuyển tới nội dung chính

Quản lý ứng dụng & OIDC client

govex-cloud-application cung cấp tầng service nghiệp vụ để quản lý ứng dụng trong hệ sinh thái: thông tin ứng dụng, tài khoản ứng dụng, chính sách truy cập và cấu hình giao thức OIDC. Thêm dependency khi service của bạn cần đọc/ghi các dữ liệu này hoặc tra cứu cấu hình OIDC theo clientId.

Khi nào sử dụng​

  • Cần danh sách/chi tiết/tạo/khoá/mở ứng dụng trong hệ thống.
  • Cần lưu cấu hình ứng dụng (trong đó có cấu hình OIDC) và đọc lại khi vận hành.
  • Cần tra cứu cấu hình OIDC theo clientId — ví dụ khi xây cổng xác thực hoặc tích hợp luồng SSO.
  • Cần quản lý tài khoản dùng chung của ứng dụng và ma trận phân quyền theo ứng dụng.
  • Cần đọc context ứng dụng hiện hành trong luồng xử lý (theo ThreadLocal).

Cài đặt​

Thêm dependency (không khai version — version do BOM quản lý, xem Cài đặt):

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

Khi dependency có trên classpath, auto-configuration tự đăng ký repository, entity, service và mapper vào context — ứng dụng chỉ cần cấu hình datasource/JPA như bình thường.

Cấu hình​

Cấu hình cần thiết là hạ tầng dữ liệu của chính ứng dụng:

PropertyMô tảMặc định
spring.datasource.*, JPADependency chạy trên datasource/JPA của ứng dụng (entity, repository, transaction)theo ứng dụng

Sử dụng​

Inject service quản lý ứng dụng​

@RequiredArgsConstructor
@RestController
@RequestMapping(AppConstants.APP_PATH)
public class AppController {

    private final AppService appService;

    @GetMapping
    public ResultMessage<Page<AppListResult>> list(Pageable pageable, AppQuery query) {
        return ResultMessage.success(appService.getAppList(pageable, query));
    }

    @PostMapping
    public ResultMessage<AppCreateResult> create(
            @Validated(Insertable.class) @RequestBody AppCreateParam param) {
        return ResultMessage.success(appService.createApp(param));
    }

    @PutMapping("/{id}/enable")
    public ResultMessage<Boolean> enable(@PathVariable String id) {
        return ResultMessage.success(appService.enableApp(id));
    }
}

AppQuery là DTO tìm kiếm dùng annotation truy vấn (@Like cho name, @Equals cho protocol) nên được dựng Specification tự động khi truy vấn danh sách.

Lưu cấu hình ứng dụng​

AppSaveConfigParam param = new AppSaveConfigParam();
param.setId(appId);
param.setTemplate(protocol);
param.setConfig(configMap);

appService.saveAppConfig(param);

Với ứng dụng OIDC, dữ liệu cấu hình được validate theo AppOidcStandardSaveConfigParam (grant types, redirect URIs, scopes, thời gian sống token...) trước khi ghi vào bảng cấu hình OIDC.

Tra cứu cấu hình OIDC theo clientId​

OidcProtocolConfig config = oidcApplicationService.getProtocolConfigByClientId(clientId);

Dùng getProtocolConfig(appCode) khi đã biết mã ứng dụng, hoặc getDefaultProtocolConfig() để lấy cấu hình mặc định.

Context ứng dụng theo luồng​

AppContextHolder.setContext(appContext);
try {
    chain.doFilter(request, response);
} finally {
    AppContextHolder.resetContext();
}

Lưu ý​

  • Dependency không định nghĩa controller REST; tầng HTTP (/api/v1/app, /api/v1/authorize/oidc/...) do ứng dụng tự triển khai. Hằng số đường dẫn nằm ở AppConstants/ProtocolConstants.
  • Cần datasource/JPA hoạt động; dependency phụ thuộc govex-cloud-iam, govex-cloud-data-jpa, govex-cloud-security, govex-cloud-validation.
  • Các entity chính dùng soft delete, dữ liệu xoá không mất khỏi database — truy vấn qua service/repository do dependency cung cấp để đúng ngữ cảnh.
  • Exception nghiệp vụ đã có sẵn (AppNotExistException, AppNotEnableException, AppAccountExistException...) kèm bảng mã lỗi riêng; nên dùng thay vì tự ném lỗi chung.
  • Tên cache (app:basic, app:oidc...) là hằng số cố định, không cấu hình qua property.