Xác thực OAuth 2.0 (Client Credentials)
Xác thực webhook HiTechCloud Pay bằng OAuth 2.0: HiTechCloud xin access token từ máy chủ OAuth của bạn trước khi gửi webhook, token được cache và tự làm mới.
Với các tổ chức đã vận hành máy chủ OAuth nội bộ, bạn có thể yêu cầu HiTechCloud Pay lấy access token theo luồng Client Credentials rồi đính kèm vào mỗi webhook dưới dạng Authorization: Bearer <token>.
Thông tin cần cấu hình
| Trường | Mô tả |
|---|---|
token_url | Endpoint cấp token của bạn, ví dụ https://auth.yourdomain.com/oauth/token. |
client_id | Định danh client HiTechCloud Pay dùng để xin token. |
client_secret | Khóa bí mật của client, lưu mã hóa trên hệ thống HiTechCloud Pay. |
scope | Phạm vi token (tùy chọn), ví dụ webhook:write. |
Luồng hoạt động
mermaid
sequenceDiagram
autonumber
participant HTC as HiTechCloud Pay
participant Auth as OAuth Server cua ban
participant Webhook as Endpoint cua ban
HTC->>Auth: POST /oauth/token (grant_type=client_credentials)
Auth-->>HTC: { access_token, expires_in }
Note over HTC: Cache token den khi gan het han
HTC->>Webhook: POST /webhook (Authorization: Bearer <token>)
Webhook->>Webhook: Xac thuc token (introspect / verify JWT)
Webhook-->>HTC: 200 {"success": true}Yêu cầu lấy token mà HiTechCloud Pay gửi tới server của bạn
curl -X POST https://auth.yourdomain.com/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'client_id=HITECHCLOUD_PAY' \
-d 'client_secret=YOUR_CLIENT_SECRET' \
-d 'scope=webhook:write'Phản hồi token mong đợi
{
"access_token": "eyJhbGciOiJSUzI1Ni...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "webhook:write"
}Xác thực token ở endpoint
Kiểm tra Bearer Token tại endpoint webhook (PHP)
<?php
$auth = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
if (!preg_match('/^Bearer\s+(.+)$/i', $auth, $m)) {
http_response_code(401);
echo json_encode(['success' => false, 'message' => 'Missing bearer token']);
exit;
}
$token = $m[1];
// Xac thuc token: introspect hoac verify chu ky JWT bang public key cua ban
if (!verify_access_token($token)) {
http_response_code(401);
echo json_encode(['success' => false, 'message' => 'Invalid token']);
exit;
}
echo json_encode(['success' => true]);HiTechCloud Pay tự cache access token và chỉ xin token mới khi gần hết hạn (
expires_in). Nếu endpoint trả 401, hệ thống sẽ thử lấy token mới một lần rồi mới áp dụng lịch retry thông thường.Với các tổ chức đã vận hành máy chủ OAuth nội bộ, bạn có thể yêu cầu HiTechCloud Pay lấy access token theo luồng Client Credentials rồi đính kèm vào mỗi webhook dưới dạng Authorization: Bearer <token>.
Thông tin cần cấu hình
| Trường | Mô tả |
|---|---|
token_url | Endpoint cấp token của bạn, ví dụ https://auth.yourdomain.com/oauth/token. |
client_id | Định danh client HiTechCloud Pay dùng để xin token. |
client_secret | Khóa bí mật của client, lưu mã hóa trên hệ thống HiTechCloud Pay. |
scope | Phạm vi token (tùy chọn), ví dụ webhook:write. |
Luồng hoạt động
Xác thực token ở endpoint
HiTechCloud Pay tự cache access token và chỉ xin token mới khi gần hết hạn (
expires_in). Nếu endpoint trả 401, hệ thống sẽ thử lấy token mới một lần rồi mới áp dụng lịch retry thông thường.mermaid
sequenceDiagram
autonumber
participant HTC as HiTechCloud Pay
participant Auth as OAuth Server cua ban
participant Webhook as Endpoint cua ban
HTC->>Auth: POST /oauth/token (grant_type=client_credentials)
Auth-->>HTC: { access_token, expires_in }
Note over HTC: Cache token den khi gan het han
HTC->>Webhook: POST /webhook (Authorization: Bearer <token>)
Webhook->>Webhook: Xac thuc token (introspect / verify JWT)
Webhook-->>HTC: 200 {"success": true}Yêu cầu lấy token mà HiTechCloud Pay gửi tới server của bạn
curl -X POST https://auth.yourdomain.com/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'client_id=HITECHCLOUD_PAY' \
-d 'client_secret=YOUR_CLIENT_SECRET' \
-d 'scope=webhook:write'Phản hồi token mong đợi
{
"access_token": "eyJhbGciOiJSUzI1Ni...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "webhook:write"
}Kiểm tra Bearer Token tại endpoint webhook (PHP)
<?php
$auth = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
if (!preg_match('/^Bearer\s+(.+)$/i', $auth, $m)) {
http_response_code(401);
echo json_encode(['success' => false, 'message' => 'Missing bearer token']);
exit;
}
$token = $m[1];
// Xac thuc token: introspect hoac verify chu ky JWT bang public key cua ban
if (!verify_access_token($token)) {
http_response_code(401);
echo json_encode(['success' => false, 'message' => 'Invalid token']);
exit;
}
echo json_encode(['success' => true]);