Cấu hình chi tiết — IDP OAuth

OAuth 2.1 Scopes

Scope	Dữ liệu trả về	Mô tả
`openid`	ID token (JWT)	Bắt buộc cho OpenID Connect flow
`profile`	Họ tên, avatar, nickname	Thông tin hồ sơ cơ bản
`email`	Địa chỉ email, email_verified	Địa chỉ email và trạng thái xác minh
`offline_access`	Refresh token	Cho phép cấp refresh token để duy trì phiên lâu dài

Grant Types

Grant type	Mô tả	Sử dụng khi
`authorization_code`	Flow chuẩn OAuth 2.1, an toàn nhất	Web app có backend server
`authorization_code + PKCE`	Flow cho ứng dụng không có backend an toàn	SPA, mobile app
`refresh_token`	Cấp mới access token khi hết hạn	Session dài hạn

Flow Authorization Code

Flow Authorization Code + PKCE

Cấu hình Token

Tham số	Mặc định	Mô tả
Access token TTL	`3600s` (1 giờ)	Thời gian hiệu lực access token
Refresh token TTL	`86400s` (1 ngày)	Thời gian hiệu lực refresh token
ID token TTL	`3600s` (1 giờ)	Thời gian hiệu lực ID token (JWT)
Token format	JWT	Định dạng token

Tham số	Mô tả
Application logo	Logo hiển thị trên trang đồng ý
Privacy policy URL	Liên kết đến chính sách bảo mật
Terms of service URL	Liên kết đến điều khoản sử dụng
Skip consent	Bỏ qua màn hình đồng ý (chỉ cho ứng dụng nội bộ đáng tin cậy)

JWKS và Key Rotation

Plugin tự động quản lý RSA key pair cho JWT signing:

Key mặc định: RSA 2048-bit
JWKS endpoint: GET /api/idpOAuth/jwks — cung cấp public key cho client verify token
Key rotation: Hỗ trợ tạo key mới, key cũ vẫn verify được trong thời gian chuyển đổi

Endpoints chi tiết

Authorization Endpoint

GET /api/idpOAuth/auth

Parameter	Mô tả
`client_id`	Client ID của ứng dụng
`redirect_uri`	URL callback (phải khớp với cấu hình)
`response_type`	`code`
`scope`	Danh sách scope (cách bằng dấu cách)
`state`	Giá trị ngẫu nhiên để chống CSRF
`code_challenge`	PKCE code challenge (tuỳ chọn)
`code_challenge_method`	`S256` (nếu dùng PKCE)

Token Endpoint

POST /api/idpOAuth/token

Parameter	Mô tả
`grant_type`	`authorization_code` hoặc `refresh_token`
`code`	Authorization code (khi grant_type = authorization_code)
`redirect_uri`	URL callback (phải khớp với lúc authorize)
`client_id`	Client ID
`client_secret`	Client Secret
`refresh_token`	Refresh token (khi grant_type = refresh_token)
`code_verifier`	PKCE verifier (nếu dùng PKCE)

Discovery Endpoints

URL	Mô tả
`GET /api/.well-known/openid-configuration`	OpenID Connect Discovery (OIDC)
`GET /api/.well-known/oauth-authorization-server`	OAuth 2.0 Authorization Server Metadata

Trả về JSON chứa tất cả endpoint và capability của IdP.

Quản lý Application qua API

typescript

// Tạo OAuth application
await api.resource('oauthApplications').create({
  values: {
    name: 'My External App',
    redirectUris: ['https://myapp.com/callback'],
    scopes: ['openid', 'profile', 'email'],
    grantTypes: ['authorization_code', 'refresh_token'],
  },
});

// Lấy danh sách applications
const { data } = await api.resource('oauthApplications').list();

Cấu hình Resource Server

Plugin hỗ trợ đăng ký resource server để cấp access token cho API cụ thể:

Tham số	Mô tả
`identifier`	URI định danh resource server
`scope`	Danh sách scope hỗ trợ
`accessTokenTTL`	TTL riêng cho access token của resource này
`accessTokenFormat`	Format token (`jwt` hoặc `opaque`)