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.

Xem Markdown

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ườngMô tả
token_urlEndpoint 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_secretKhóa bí mật của client, lưu mã hóa trên hệ thống HiTechCloud Pay.
scopePhạ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.