服務間認證

本章詳述 Licensee 發出請求至 Game Provider 時，將根據資訊進行驗證與處理。

技術規範

Game Provider 依照以下規範提供 HTTP API 服務：

採用 RESTful 風格的請求
僅支援 HTTPS 站點
請求與回應使用 JSON 格式：使用 content-type: application/json 標頭
於 HTTP Header 要求特殊的標頭資訊，且 HTTP Header 不區分大小寫
身份驗證處理 (擇一)
1. 於 Request Header 添加 authorization: ECDSA-SHA256 <Signature> ¹
2. 於 Request Header 添加 authorization: HMAC-SHA256 <Signature> ¹
3. 於 Request Header 添加 authorization: Basic <base64(client_id:client_secret)>
4. 於 Request Header 添加 api-key: <API_KEY> ²
5. 於 Query String 添加 api_key=<API_KEY> (強烈不建議)
API_KEY 與 CLIENT_SECRET
1. 由 Game Provider 提供
2. CLIENT_SECRET 由合法的 Base64 字元組成 ³
3. API_KEY 使用隨機 22 ~ 36 個字元的 Hex 字元
API 站點要求
1. 網域必須擁有 https 證書
2. 使用固定的 Public IP；或者固定的 DNS 紀錄
3. 不使用臨時通道服務、短網址

HTTP Header

以下三個 Header 為必填欄位：

Header	說明	範例
`yac-client-id`	請求來源識別碼，由 Game Provider 指派給 Licensee	`yac-client-id: asia-platform-1`
`yac-timestamp`	請求產生時間（Unix timestamp，秒）用於檢查請求是否過期	`yac-timestamp: 1772532662`
`yac-nonce`	單次請求隨機值，用於防止重放攻擊	`yac-nonce: 8f3c9a1e7b`

若基於簽章驗證，還需要將 PATHNAME⁴ 納入簽章範圍。

根據您使用的驗證模式，還需要添加以下兩個 Header：

Header	說明	範例
`authorization`	用於傳送簽章或憑證資訊。依驗證模式不同，可能包含 ECDSA 或 HMAC 簽章，亦可攜帶 API Key。	`authorization: <scheme> <signature>`
`api-key`	以自訂 Header 傳遞 API Key。此方式僅提供客戶端識別能力，不涉及請求簽章。若使用此模式，服務端將依 `API_KEY` 對應到合作方配置進行授權檢查。	`api-key: AbCdEf123456`

HTTP請求憑證範例

ECDSA-SHA256HMAC-SHA256BasicAPI Key

生成非對稱金鑰

openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem

範例輸出：

Licensee 在發送請求時，需要先構造簽章字串，請依照以下順序組合：
```
{yac-client-id};{yac-timestamp};{yac-nonce};<PATH_NAME>
```
若 API URL 為 https://endporint.example.com/api/example，簽章字串應為：
```
asia-platform-1;1772532662;8f3c9a1e7b;/api/example
```

進行簽章

printf "asia-platform-1;1772532662;8f3c9a1e7b;/api/example" \
| openssl dgst -sha256 -sign private.example.pem | base64 -w 0

# 若 base64 沒有 -w 參數，請將換行符號去除
printf "asia-platform-1;1772532662;8f3c9a1e7b;/api/example" \
| openssl dgst -sha256 -sign private.example.pem | base64 | tr -d '\n'

範例輸出：

MEUCIAxFDTqxDSQqkhWVoBPVPkLpZ2legE+jdSrmc56GXdc6AiEA+XOgxPad1YFScBdP6VoSAr01zzdGzPGKR017MAfjNUk=

建構 HTTP 請求

curl -X POST "https://endpoint.example.com/api/example" \
    -H "content-type: application/json" \
    -H "yac-client-id: asia-platform-1" \
    -H "yac-timestamp: 1772532662" \
    -H "yac-nonce: 8f3c9a1e7b" \
    -H "authorization: ECDSA-SHA256 MEUCIAxFDTqxDSQqkhWVoBPVPkLpZ2legE+jdSrmc56GXdc6AiEA+XOgxPad1YFScBdP6VoSAr01zzdGzPGKR017MAfjNUk=" \
    -d '{"payload": {}}'

verify example — CyberChef: Verify Recipe

由 Game Provider 提供 CLIENT_SECRET：

openssl rand -base64 32

範例輸出：

FUg7pODYd+z48OlcaMlTddUQDaH8CABxoOC7Q5EIxGM=

Licensee 在發送請求時，需要先構造簽章字串，請依照以下順序組合：
```
{yac-client-id};{yac-timestamp};{yac-nonce};<PATH_NAME>
```
若 API URL 為 https://endporint.example.com/api/example，簽章字串應為：
```
asia-platform-1;1772532662;8f3c9a1e7b;/api/example
```

進行簽章

printf "asia-platform-1;1772532662;8f3c9a1e7b;/api/example" \
| openssl dgst -sha256 -hmac "FUg7pODYd+z48OlcaMlTddUQDaH8CABxoOC7Q5EIxGM=" -binary | base64 -w 0

# 若 base64 沒有 -w 參數，請將換行符號去除
printf "asia-platform-1;1772532662;8f3c9a1e7b;/api/example" \
| openssl dgst -sha256 -hmac "FUg7pODYd+z48OlcaMlTddUQDaH8CABxoOC7Q5EIxGM=" -binary | base64 | tr -d '\n'

範例輸出：

kSVTmTq9QvJHa786VCkzjBmMpQ4WFk7qTupR8SBPOKo=

建構 HTTP 請求

curl -X POST "https://endporint.example.com/api/example" \
    -H "content-type: application/json" \
    -H "yac-client-id: asia-platform-1" \
    -H "yac-timestamp: 1772532662" \
    -H "yac-nonce: 8f3c9a1e7b" \
    -H "authorization: HMAC-SHA256 kSVTmTq9QvJHa786VCkzjBmMpQ4WFk7qTupR8SBPOKo=" \
    -d '{}'

由 Game Provider 提供 CLIENT_SECRET：

# 長度隨機 22 ~ 36 個字元
openssl rand -hex $string_length

範例輸出：

bf6bcfba6cd20a2f0ba80208c3de9e1604358ba813b48cdfe7fd

Licensee 在發送請求時，需要先構造base64字串，請依照以下順序組合：
```
<CLIENT_ID>:<CLIENT_SECRET>
```
並使用 base64 進行編碼：
```
printf "asia-platform-1:bf6bcfba6cd20a2f0ba80208c3de9e1604358ba813b48cdfe7fd" | base64 -w 0
```
範例輸出：
```
YXNpYS1wbGF0Zm9ybS0xOmJmNmJjZmJhNmNkMjBhMmYwYmE4MDIwOGMzZGU5ZTE2MDQzNThiYTgxM2I0OGNkZmU3ZmQ=
```
將此內容放入 authorization: Basic <base64(client_id:client_secret)> 取代 <base64(client_id:client_secret)>

建構 HTTP 請求

curl -X POST "https://endporint.example.com/api/example" \
    -H "content-type: application/json" \
    -H "yac-client-id: asia-platform-1" \
    -H "yac-timestamp: 1772532662" \
    -H "yac-nonce: 8f3c9a1e7b" \
    -H "authorization: Basic YXNpYS1wbGF0Zm9ybS0xOmJmNmJjZmJhNmNkMjBhMmYwYmE4MDIwOGMzZGU5ZTE2MDQzNThiYTgxM2I0OGNkZmU3ZmQ=" \
    -d '{}'

由 Game Provider 提供 API_KEY：

# 長度隨機 22 ~ 36 個字元
openssl rand -hex $string_length

範例輸出：

590746ceb2a7b943ab123bdcc0105c3e296ef1d12b6a

將 590746ceb2a7b943ab123bdcc0105c3e296ef1d12b6a 放入 HTTP Header 或是 Query String
- api-key: 590746ceb2a7b943ab123bdcc0105c3e296ef1d12b6a
- ?api_key=590746ceb2a7b943ab123bdcc0105c3e296ef1d12b6a
建構 HTTP 請求
```
curl -X POST "https://endporint.example.com/api/example" \
    -H "content-type: application/json" \
    -H "yac-client-id: asia-platform-1" \
    -H "yac-timestamp: 1772532662" \
    -H "yac-nonce: 8f3c9a1e7b" \
    -H "api-key: 590746ceb2a7b943ab123bdcc0105c3e296ef1d12b6a" \
    -d '{}'
```
請注意

若 API_KEY 同時出現在 HTTP Header 與 Query String，伺服器僅會採用 Header 中的值進行驗證，並忽略 Query String 中的 api_key。

此外，不建議使用 API_KEY 作為主要的身份驗證方式。此方式通常用於測試環境或相容性需求。若整合系統支援簽章機制，建議優先採用 HMAC-SHA256 或 ECDSA-SHA256 進行身份驗證。
除非整合方的設備或軟體環境較為老舊，無法實作簽章機制，否則不建議在產品環境中使用 API_KEY 作為主要的身份驗證方式。

請 Licensee 與 Game Provider 確認雙方合作時使用的認證模式，並於雙方整合前將 CLIENT_SECRET 或 PUBLIC_KEY 交換完成。

請求發起者

此節內容僅紀錄 Licensee 對 Game Provider 應遵循的認證模式，若 Licensee 在整合過程中需要 Game Provider 發出請求至其端口，須額外提供文件以利整合。
請參考 Licensee Should Implement。