Hướng dẫn Tích hợp SSO cho Ứng dụng Vệ tinh
Dành cho: Kỹ sư phần mềm & Trưởng nhóm kỹ thuật phát triển các ứng dụng trong OneXCC Network (cổng ứng dụng số, công cụ nội bộ, đối tác).
Tra cứu nhanh cho Agent & Terminal
Các thông số máy đọc và lệnh kiểm tra trực tiếp qua curl dành cho automated coding agents và DevOps script:
XCC IAM đóng vai trò là OpenID Connect Provider chuẩn mực. Mọi ứng dụng relying party (client app) kết nối xác thực theo chuẩn Authorization Code Flow kết hợp PKCE (S256).
| Endpoint | Phương thức | Đường dẫn URL | Mục đích sử dụng |
|---|---|---|---|
| Issuer URL | URI | https://iam.xcc.one/api/auth | Định danh máy chủ phát hành token (Issuer URI) |
| OIDC Discovery (Máy đọc) | GET | https://iam.xcc.one/.well-known/openid-configuration | Tự động khám phá cấu hình server dành cho SDK máy đọc (RFC 8414) |
| JWKS Endpoint | GET | https://iam.xcc.one/jwks | Public keys giải mã & xác thực chữ ký JWT ID Token |
| Authorization | GET / POST | https://iam.xcc.one/oauth2/authorize | Giao diện chuyển hướng người dùng đăng nhập & cấp quyền |
| Token Endpoint | POST | https://iam.xcc.one/oauth2/token | Trao đổi mã Authorization Code lấy Access & ID Token |
| UserInfo Endpoint | GET / POST | https://iam.xcc.one/userinfo | Truy xuất thông tin hồ sơ người dùng qua Bearer Token |
| Đăng ký Client Động (RFC 7591) | POST | https://iam.xcc.one/oauth2/register | Đăng ký Client động cho IDE Hosts / Agents qua Initial Access Token (RFC 7591) |
| Thu hồi Token (RFC 7009) | POST | https://iam.xcc.one/oauth2/revoke | Thu hồi và vô hiệu hóa Access Token hoặc Refresh Token ngay lập tức (RFC 7009) |
Đặc tả Chi tiết Tham số API (API Reference)
Dành cho lập trình viên cần tra cứu cấu trúc tham số HTTP request và dữ liệu trả về cho từng endpoint:
Khởi tạo phiên đăng nhập tập trung và xin mã Authorization Code qua trình duyệt (Browser-based flow).
| Param | Type | Status | Description |
|---|---|---|---|
| client_id | string | Bắt buộc | Mã Client ID nhận được khi tạo ứng dụng trong Console hoặc đăng ký DCR. |
| redirect_uri | string | Bắt buộc | URI chuyển hướng sau đăng nhập, phải khớp 100% với cấu hình đăng ký. |
| response_type | string | Bắt buộc | Bắt buộc giá trị cố định: code |
| scope | string | Bắt buộc | Quyền truy cập yêu cầu, bắt buộc có openid (ví dụ: openid profile email mcp:access). |
| resource | string | Tùy chọn | URI tài nguyên được bảo vệ per RFC 8707 (VD: https://app.maerin.biz/api/mcp). Access Token JWT sẽ gắn claim aud khớp tài nguyên này. |
| code_challenge | string | Bắt buộc | Mã băm PKCE: BASE64URL(SHA256(code_verifier)). |
| code_challenge_method | string | Bắt buộc | Bắt buộc giá trị cố định: S256 |
| state | string | Khuyến nghị | Chuỗi ngẫu nhiên do client sinh ra để phòng chống tấn công CSRF. |
| track | string | Tùy chọn | Chỉ định loại tài khoản: personal hoặc enterprise (hỗ trợ cả alias account_type, user_type). Nếu truyền, XCC IAM khóa giao diện vào loại tài khoản đó và ẩn bộ chuyển tab; nếu không truyền, giao diện hiển thị đủ 2 tab để người dùng tự chọn. |
Triển khai kết nối đăng nhập đơn giản chỉ trong 3 bước:
Quản trị viên truy cập trang quản lý OAuth Clients, nhấn Create Client và khai báo:
- Name: Tên ứng dụng hiển thị trên màn hình cấp quyền (VD: OneXCC Portal Production).
- Redirect URIs: Danh sách callback URL hợp lệ (VD: https://app.example.com/api/auth/callback/xcc-iam, http://localhost:3101/api/auth/callback/xcc-iam cho dev).
Khai báo thông số OIDC trong file .env.local hoặc cấu hình production của ứng dụng vệ tinh:
OIDC_ISSUER=https://iam.xcc.one/api/auth
OIDC_CLIENT_ID=your_assigned_client_id
OIDC_CLIENT_SECRET=your_assigned_client_secret
OIDC_REDIRECT_URI=https://app.example.com/api/auth/callback/xcc-iam
OIDC_SCOPES="openid profile email"Tích hợp thư viện xác thực vào ứng dụng vệ tinh theo các mẫu code dưới đây:
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
export const auth = betterAuth({
plugins: [
genericOAuth({
config: [
{
providerId: "xcc-iam",
clientId: process.env.OIDC_CLIENT_ID!,
clientSecret: process.env.OIDC_CLIENT_SECRET!,
discoveryUrl: "https://iam.xcc.one/api/auth/.well-known/openid-configuration",
scopes: ["openid", "profile", "email"],
pkce: true, // Bắt buộc bật PKCE S256 theo tiêu chuẩn XCC IAM
},
],
}),
],
});Sau khi người dùng xác thực và đồng ý cấp quyền tại màn hình Consent, ứng dụng client sẽ nhận được ID Token và kết quả từ /userinfo chứa các claim tiêu chuẩn:
{
"sub": "usr_xcc_123456789",
"email": "[email protected]",
"name": "Nguyễn Văn A",
"image": "https://avatar.xcc.one/avatar.png",
"email_verified": true
}Bắt buộc bật PKCE (RFC 7636 S256)
Mọi client (kể cả SPA, Mobile App hay Server-rendered) bắt buộc phải sử dụng mã hóa PKCE S256 để triệt tiêu hoàn toàn nguy cơ tấn công đánh cắp mã Authorization Code.
Khớp Redirect URI Tuyệt đối
Mọi callback URL phải được đăng ký trước chính xác từng ký tự. XCC IAM sẽ từ chối ngay lập tức nếu redirect_uri có dấu hiệu bị giả mạo hoặc khác port/protocol.
Không lộ Client Secret ở Client-side
Client Secret chỉ được phép lưu trữ và sử dụng trong backend/server-side runtime. Tuyệt đối không để lộ trong source code JavaScript client hoặc repository công khai.
Khi chuyển hướng người dùng sang XCC IAM xác thực, ứng dụng client có thể chủ động chỉ định loại tài khoản (qua track, account_type, user_type):
Đính kèm track=enterprise (hoặc account_type=enterprise) vào URL xác thực. XCC IAM sẽ ẩn hoàn toàn thanh chuyển tab và khóa giao diện vào Doanh nghiệp với email công ty.
https://iam.xcc.one/api/auth/oauth2/authorize?client_id=...&redirect_uri=...&response_type=code&scope=openid+profile&track=enterpriseĐính kèm track=personal (hoặc account_type=personal). XCC IAM sẽ ẩn thanh chuyển tab và khóa giao diện vào tài khoản Cá nhân. Nếu không truyền loại tài khoản nào, XCC IAM sẽ hiển thị đủ 2 tab để người dùng tự chọn.
https://iam.xcc.one/sign-in?track=personal&callbackURL=https://app.example.com/dashboardXCC IAM hỗ trợ ủy quyền theo chuẩn OAuth 2.1 kết hợp Dynamic Client Registration (RFC 7591) và Resource Indicators (RFC 8707) dành riêng cho các môi trường IDE (Cursor, Windsurf, VS Code) kết nối máy chủ MCP an toàn.
IDE Hosts tự khởi tạo đăng ký Client qua POST /oauth2/register kèm token bảo mật IAT do quản trị viên cấp trong header Authorization:
# 1. Đăng ký IDE Host Client động qua Initial Access Token:
curl -X POST https://iam.xcc.one/oauth2/register \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <MCP_INITIAL_ACCESS_TOKEN>" \
-d '{
"client_name": "Cursor IDE - Workstation",
"redirect_uris": ["http://127.0.0.1:8080/callback"],
"application_type": "native",
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code"],
"response_types": ["code"]
}'IDE Host mở trình duyệt yêu cầu cấp quyền với scope mcp:access và tham số resource chỉ định máy chủ MCP mục tiêu:
https://iam.xcc.one/oauth2/authorize?
response_type=code&
client_id=mcp_clnt_YOUR_CLIENT_ID&
redirect_uri=http%3A%2F%2F127.0.0.1%3A8080%2Fcallback&
scope=openid+profile+email+mcp%3Aaccess&
resource=https%3A%2F%2Fapp.maerin.biz%2Fapi%2Fmcp&
code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
code_challenge_method=S256IDE Host đổi Authorization Code lấy Access Token. Token trả về có claim aud trỏ chính xác tới máy chủ MCP:
# 2. Đổi Authorization Code lấy Resource-Bound JWT Access Token:
curl -X POST https://iam.xcc.one/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "client_id=mcp_clnt_YOUR_CLIENT_ID" \
-d "redirect_uri=http://127.0.0.1:8080/callback" \
-d "code=AUTHORIZATION_CODE_RECEIVED" \
-d "code_verifier=YOUR_PKCE_CODE_VERIFIER" \
-d "resource=https://app.maerin.biz/api/mcp"Mọi lượt cấp quyền mcp:access được tự động ghi vết trong nhật ký kiểm toán (oauth_consent.grant). Quản trị viên có thể thu hồi quyền từ Admin Console hoặc client tự thu hồi qua POST /oauth2/revoke.