Hướng dẫn tích hợp OIDC SSO

Trang này hướng dẫn tích hợp OIDC SSO với Identity Server của Trục LMS cho các ứng dụng vệ tinh (Web, Mobile, Backend API).

Mở đầu

Trong toàn bộ hệ sinh thái Trục LMS, Căn cước công dân (citizen_id) là định danh quan trọng nhất và bắt buộc phải nhất quán giữa các hệ thống.
Mọi nghiệp vụ xác thực, liên kết tài khoản, phân quyền và đồng bộ dữ liệu người dùng đều dựa trên citizen_id.

Nếu tài khoản người dùng chưa liên kết citizen_id, hệ thống sẽ không thể hoàn tất các nghiệp vụ SSO bắt buộc.

Đăng ký khởi tạo client SSO

Để đăng ký mới hoặc cập nhật cấu hình client SSO, liên hệ:

• Phí Văn Lời
• SĐT: 0906282026
• Email: philoi@qig.vn

Khi gửi yêu cầu, cần cung cấp tối thiểu:

• Tên hệ thống/app.
• Môi trường tích hợp (dev, staging, production).
• redirect_uri và post_logout_redirect_uri.
• Loại ứng dụng (public/confidential), phương thức xác thực client.
• Danh sách scope cần sử dụng.

Endpoint theo môi trường

Development

• Issuer: https://ssoblms.vstudy.edu.vn
• Discovery: https://ssoblms.vstudy.edu.vn/.well-known/openid-configuration
• Authorize: https://ssoblms.vstudy.edu.vn/connect/authorize
• Token: https://ssoblms.vstudy.edu.vn/connect/token
• UserInfo: https://ssoblms.vstudy.edu.vn/connect/userinfo
• Logout: https://ssoblms.vstudy.edu.vn/connect/logout

Staging

• Issuer: https://ssoblms.vstudy.edu.vn
• Discovery: https://ssoblms.vstudy.edu.vn/.well-known/openid-configuration
• Authorize: https://ssoblms.vstudy.edu.vn/connect/authorize
• Token: https://ssoblms.vstudy.edu.vn/connect/token
• UserInfo: https://ssoblms.vstudy.edu.vn/connect/userinfo
• Logout: https://ssoblms.vstudy.edu.vn/connect/logout

Production

• Issuer: https://sso.hanoi.edu.vn
• Discovery: https://sso.hanoi.edu.vn/.well-known/openid-configuration
• Authorize: https://sso.hanoi.edu.vn/connect/authorize
• Token: https://sso.hanoi.edu.vn/connect/token
• UserInfo: https://sso.hanoi.edu.vn/connect/userinfo
• Logout: https://sso.hanoi.edu.vn/connect/logout

Luồng tích hợp khuyến nghị

Áp dụng chuẩn Authorization Code + PKCE cho ứng dụng frontend/public client.

1. Ứng dụng điều hướng người dùng tới /connect/authorize.
2. Người dùng đăng nhập tại Identity Server.
3. Identity Server redirect về redirect_uri kèm code.
4. Ứng dụng đổi code tại /connect/token để lấy access_token (và refresh_token nếu được cấp).
5. Ứng dụng gọi /connect/userinfo để lấy thông tin người dùng phục vụ nghiệp vụ.
6. Khi logout, điều hướng qua /connect/logout để kết thúc phiên tập trung.

Scope và claim thường dùng

Scope tham khảo:

• openid
• profile
• email
• phone
• citizen_id
• offline_access
• lms_base_api

Claim nghiệp vụ quan trọng:

• account_id
• citizen_id
• login_role_type
• group_unit_code
• doet_code
• division_code
• school_code

Nguyên tắc bắt buộc về định danh

1. Không dùng nhiều định danh chính cho cùng một người dùng.
2. citizen_id phải được lưu đúng chuẩn dữ liệu nguồn và đồng nhất giữa hệ thống xác thực và hệ thống nghiệp vụ.
3. Mọi mapping vai trò hoặc đơn vị tổ chức đều phải truy vết được từ citizen_id.
4. Không tự ý suy diễn tài khoản theo thông tin yếu hơn (ví dụ chỉ theo tên hiển thị).

Checklist triển khai

1. Đăng ký client SSO đầy đủ redirect_uri/post_logout_redirect_uri theo từng môi trường.
2. Cấu hình OIDC client với response_type=code.
3. Kiểm tra callback và đổi token thành công.
4. Kiểm tra lấy userinfo thành công và có citizen_id.
5. Kiểm tra logout 2 chiều (app và Identity Server).
6. Kiểm tra xử lý lỗi invalid_redirect_uri, invalid_client, token hết hạn.