Luồng OAuth2 · Tài liệu Tích hợp K ID

Mục lục tài liệu

Tài liệu

Luồng OAuth 2.0 Hoàn Chỉnh

Chi tiết các giai đoạn truyền nhận dữ liệu giữa Client Application, Authorization Server và Resource Server.

1. Yêu Cầu Ủy Quyền (Authorization Request)

Ứng dụng khách chuyển hướng trình duyệt của người dùng đến endpoint ủy quyền với các tham số truy vấn sau:

Endpoint: https://accounts.lequangkhai.id.vn/authorize

Phương thức: GET

Tham Số	Bắt Buộc	Mô Tả Kỹ Thuật
`client_id`	Có	Định danh công khai của ứng dụng đã đăng ký trong hệ thống.
`response_type`	Có	Phải là giá trị cố định `code`.
`redirect_uri`	Có	Địa chỉ URI nhận kết quả chuyển hướng (phải khớp chính xác danh sách đã đăng ký).
`scope`	Tùy chọn	Các quyền cần yêu cầu, phân cách bởi khoảng trắng (ví dụ: `openid profile email`).
`state`	Có	Chuỗi ngẫu nhiên do Client sinh ra nhằm ngăn chặn tấn công giả mạo yêu cầu chéo trang (CSRF).
`code_challenge`	PKCE	Chuỗi mã hóa từ code_verifier (Bắt buộc đối với Public Clients theo RFC 7636).
`code_challenge_method`	PKCE	Phương thức mã hóa, khuyến nghị sử dụng `S256`.

2. Người Dùng Xác Thực & Chấp Thuận

Tại máy chủ SSO:

Nếu người dùng chưa đăng nhập, hệ thống hiển thị màn hình đăng nhập.
Sau khi đăng nhập thành công, hệ thống hiển thị màn hình yêu cầu cấp quyền (Consent Screen) với danh sách các quyền hạn được yêu cầu.
Nếu người dùng nhấn "Cho phép", máy chủ tạo mã authorization_code và chuyển hướng về ứng dụng khách.

3. Tiếp Nhận Mã Ủy Quyền (Authorization Code Callback)

Máy chủ SSO chuyển hướng trình duyệt về redirect_uri kèm mã ủy quyền:

GET https://yourapp.com/callback?code=AUTH_CODE_HERE&state=ORIGINAL_STATE_HERE HTTP/1.1

Quy trình kiểm tra tại Client:

So khớp giá trị state nhận được với giá trị state đã lưu trong phiên trước đó. Nếu không khớp, hủy bỏ yêu cầu ngay lập tức.
Trích xuất tham số code để chuẩn bị gửi yêu cầu đổi token.

4. Trao Đổi Mã Lấy Mã Thông Báo (Token Exchange)

Backend của ứng dụng khách gửi yêu cầu POST trực tiếp đến Token Endpoint (Server-to-Server):

Endpoint: https://accounts.lequangkhai.id.vn/api/token

Phương thức: POST

Content-Type: application/x-www-form-urlencoded

POST /api/token HTTP/1.1
Host: accounts.lequangkhai.id.vn
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTH_CODE_HERE&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=https://yourapp.com/callback

Máy chủ phản hồi payload chứa các mã thông báo truy cập:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_8f1a7b...",
  "scope": "openid profile email"
}

5. Truy Vấn Thông Tin Người Dùng (UserInfo Request)

Ứng dụng sử dụng access_token trong tiêu đề Authorization để truy vấn thông tin định danh của người dùng:

GET /api/userinfo HTTP/1.1
Host: accounts.lequangkhai.id.vn
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Phản hồi từ UserInfo Endpoint:

{
  "sub": "1042",
  "username": "nguyenvana",
  "email": "[email protected]",
  "name": "Nguyễn Văn A",
  "avatar_url": "https://example.com/avatar.jpg"
}

6. Luồng Làm Mới Mã Thông Báo (Refresh Token Flow)

Khi Access Token hết hạn (sau 3600 giây), ứng dụng sử dụng refresh_token để nhận một cặp token mới mà không cần người dùng thao tác lại:

POST /api/token HTTP/1.1
Host: accounts.lequangkhai.id.vn
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=rt_8f1a7b...&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Bảng Mã Lỗi Tiêu Chuẩn

Mã Lỗi (Error Code)	Mô Tả Nguyên Nhân
`invalid_request`	Yêu cầu thiếu tham số bắt buộc hoặc định dạng không hợp lệ.
`unauthorized_client`	Client ID không hợp lệ hoặc ứng dụng bị khóa.
`access_denied`	Người dùng từ chối cấp quyền truy cập trên màn hình Consent.
`invalid_grant`	Authorization code hoặc refresh token không hợp lệ hoặc đã hết hạn.
`invalid_scope`	Phạm vi quyền hạn yêu cầu nằm ngoài danh sách được hỗ trợ.

← Khởi động nhanh Xem code tích hợp PHP →

Cập nhật gần nhất: Tháng 10, 2025

Lên đầu trang

Làm việc với AI