Đồng bộ nguồn danh tính

Quản lý và đồng bộ "nguồn danh tính" bên ngoài (hiện hỗ trợ Matrix): cấu hình kết nối, đăng ký động, đồng bộ phòng ban/người dùng theo lịch hoặc thủ công, xử lý callback sự kiện và tự động tạo tài khoản nội bộ khi người dùng đăng nhập qua IdP. Dùng chủ yếu ở service định danh trung tâm.

Khi nào sử dụng

Cần kết nối Govex Cloud với hệ thống định danh bên ngoài để đồng bộ cây phòng ban và người dùng.
Cần đồng bộ định kỳ theo cron hoặc kích hoạt thủ công khi có yêu cầu.
Cần nhận callback sự kiện thay đổi người dùng/phòng ban từ hệ thống nguồn.
Cần tự động tạo/cập nhật tài khoản nội bộ khi người dùng đăng nhập qua IdP.

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-idp</artifactId>
</dependency>

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

Cấu hình

Cấu hình của từng nguồn danh tính được lưu trong database (bảng identity_source) và quản lý qua REST API:

basic_config — thông tin kết nối, được mã hoá khi lưu và giải mã bằng EncryptionModule trước khi sử dụng.
strategy_config — chiến lược đồng bộ phòng ban/người dùng.
job_config — lịch đồng bộ.

Cấu hình kết nối Matrix (basic_config):

Trường	Mô tả	Giá trị
`baseUrl`	Địa chỉ máy chủ Matrix.	bắt buộc
`adminUsername`	Tài khoản admin dùng gọi API Matrix.	bắt buộc
`adminPassword`	Mật khẩu admin (được mã hoá khi lưu).	bắt buộc
`domainOverride`	Domain ghi đè khi tạo người dùng trên Matrix.	tuỳ chọn
`adminTokenTtlMinutes`	Thời gian sống của admin token (phút).	tuỳ chọn
`incrementalEnabled`	Bật đồng bộ tăng dần thay vì toàn bộ.	tuỳ chọn
`notifyTemplateCode`	Mã template thông báo gửi cho người dùng.	tuỳ chọn

Chiến lược và lịch đồng bộ:

Trường	Mô tả	Giá trị
`strategyConfig.organization.targetId`	ID đơn vị gốc để gắn cây phòng ban đồng bộ về.	tuỳ chọn
`strategyConfig.user.defaultPassword`	Mật khẩu mặc định cho tài khoản tạo mới.	tuỳ chọn
`strategyConfig.user.enabled`	Kích hoạt tài khoản tạo mới ngay khi đồng bộ.	tuỳ chọn
`strategyConfig.user.emailNotify`	Gửi email thông báo cho người dùng mới.	tuỳ chọn
`jobConfig.mode`	Kiểu lịch: `period` (theo chu kỳ) hoặc `timed` (theo thời điểm cố định).	tuỳ chọn
`jobConfig.value`	Biểu thức lịch tương ứng với `mode`.	tuỳ chọn

Sử dụng

Bước 1 — tạo và cấu hình nguồn danh tính qua REST API:

POST /api/v1/identity_source/create — tạo nguồn danh tính (provider MATRIX).
PUT /api/v1/identity_source/save/config — lưu basic_config, strategy_config, job_config.
PUT /api/v1/identity_source/enable/{id} / PUT /api/v1/identity_source/disable/{id} — bật/tắt nguồn; khi bật, nguồn được đăng ký kèm cron task tương ứng.
GET /api/v1/identity_source/list, GET /api/v1/identity_source/get/{id} — tra cứu nguồn danh tính.
POST /api/v1/identity_source/config_validator — kiểm tra cấu hình trước khi lưu.
GET /api/v1/identity_source/sync/history_list, GET /api/v1/identity_source/sync/record_list — tra cứu lịch sử/bản ghi đồng bộ.
POST /api/v1/synchronizer/event_receive/{code} — endpoint nhận callback sự kiện từ hệ thống nguồn.

Bước 2 — thao tác bằng service khi cần gọi từ code:

@Service
@RequiredArgsConstructor
public class IdentitySourceFacade {
    private final IdentitySourceService identitySourceService;
    private final IdentitySourceSyncService identitySourceSyncService;

    public void enable(String id) {
        identitySourceService.enableIdentitySource(id);
    }

    public void disable(String id) {
        identitySourceService.disableIdentitySource(id);
    }

    public void syncNow(String id) {
        identitySourceSyncService.executeIdentitySourceSync(id);
    }

    public Page<IdentitySourceSyncRecordListResult> syncRecords(IdentitySourceSyncRecordListQuery query, Pageable page) {
        return identitySourceSyncService.getIdentitySourceSyncRecordList(query, page);
    }
}

Bước 3 — nội dung cấu hình minh hoạ gửi lên save/config:

{
  "id": "<id nguồn danh tính>",
  "basicConfig": {
    "baseUrl": "https://matrix.example.com",
    "adminUsername": "admin",
    "adminPassword": "...",
    "incrementalEnabled": true
  },
  "strategyConfig": {
    "organization": { "targetId": "<id đơn vị gốc>" },
    "user": { "enabled": true, "emailNotify": true }
  },
  "jobConfig": {
    "mode": "period",
    "value": "0 0 2 * * ?"
  }
}

Lưu ý

Hiện registry chỉ hỗ trợ provider MATRIX; provider mới cần bổ sung nhánh xử lý tương ứng (SPI IdentitySource, IdentitySourceClient, IdentitySourceConfigValidator) trong IdentitySourceBeanRegistry.
Cần UserRepository (govex-cloud-iam) để tìm/tạo người dùng, RedissonClient cho lock phân tán và phát/nhận sự kiện, EncryptionModule để giải mã basic_config, SpringSchedulerRegister để đăng ký cron task.
Phải đảm bảo các bảng identity_source, identity_provider, identity_source_sync_history, identity_source_sync_record, identity_source_event_record tồn tại trước khi chạy.
Đồng bộ theo cron (TriggerType.JOB) và thủ công (TriggerType.MANUAL) đều dùng lock Redisson để tránh chạy song song giữa các instance.
Lỗi khi đăng ký một nguồn danh tính được cô lập theo từng nguồn (nguồn lỗi bị hủy đăng ký, không chặn khởi động ứng dụng).
govex-cloud-oauth2 dùng IdpAuthenticationService cho luồng đăng nhập qua OIDC IdP.

Khi nào sử dụng​

Cài đặt​

Cấu hình​

Sử dụng​

Lưu ý​

Khi nào sử dụng

Cài đặt

Cấu hình

Sử dụng

Lưu ý