GH GambleHub

API認証：OAuth2、 JWT、 HMAC

TL；DR（ドクター）

OAuth2/OIDC+JWTは、複雑な認可（スコープ/ロール/テナント）、SSO、短いTTLトークンを持つクライアントアプリケーションとサーバー統合のための標準です。
HMAC署名は、決定論的な検証とリプレイに対する強力な保護を備えたWebhookおよびシンプルなパートナー呼び出し「server→server」に最適です。
セキュリティを強化：mTLSまたはDPoP（送信者制約付きトークン）、短いTTL （5-15分）、キー回転（JWKS）、回転/反再利用によるトークンの更新、厳格な検証「aud/iss/exp/nbf/kid」およびポリシーゲートウェイのコード。

1）ソリューションマップ： どこに適用するか

シナリオ私たちはお勧めします
外部クライアント（Web/iOS/Android）、 SSOOAuth2/OIDC：承認コード+PKCE
Server↔server（マシンインテグレーション）OAuth2クライアント資格情報（可能であればmTLS/DPoP）
固定ルートパートナーコールOAuth2またはHMAC（スコープが単純な場合）
Webhook （PSP/詐欺防止/支払い）HMAC署名+タイムスタンプ+idempotency
インナー東西交通mTLS+短いJWT（または不透明+内省）
非常に敏感な取引（支払い）OAuth2+mTLS/DPoP、可能であればステップアップ（SCA/3DS）

2） OAuth2/OIDC： 流れおよび顧客

2.1フロー

認可コード+PKCE （Web/Mobile）-認可コードを傍受から保護します。
クライアント資格情報：ユーザーなしのserver↔server。スコープ-最小必要。
デバイスコード：ブラウザのないデバイスの場合。
リフレッシュトークン：信頼できるクライアントのみ；回転し、再使用検出を可能にして下さい。

2.2クライアントタイプ

機密（サーバー、BFF）：秘密を守ります。mTLSを使用します。
Public （SPA/mobile）：秘密は→PKCE、 DPoP、短いTTLおよび限られたスコープを貯えることができません。

3） JWT： 構造、タイミング、検証

3.1フィールド（クレーム）

必須：'iss'、 'sub'、 'aud'、 'exp'、 'iat'、 'nbf'、 'jti'、 'scope'/'permissions'、 'tenant'（マルチリースの場合）、'kid'。

3.2つの寿命

アクセストークン：5-15分。
トークンをリフレッシュ：日/週、各取引所で回転します。古いものを再提出するとセッションをブロックします。

クロックスキュー： 公差≤ 60秒

3.3 JWKSとキー

KMS/Vaultにキーを格納するには、'kid'が必要です。
2つのアクティブキー（ローリング）、60-90日に1回またはインシデントで再発行。
ゲートウェイのJWKSキャッシュ≤ 5分で、自動障害があります。

3.4ゲートウェイ/サービスの検証

チェック：署名、'aud'（承認されたサービス）、'iss'、 'exp/nbf'、ロックのリスト（失効）。
署名を確認せずに本体からフィールドを信頼しないでください。'alg=none'を無視します。

リクエストヘッダの例： 

Authorization: Bearer <JWT>
X-Trace-Id: <uuid>

4）クライアントへのバインディングトークン： mTLS、 DPoP

mTLS （TLSクライアント証明書）：トークンは、クライアント証明書がある場合にのみ発行され、検証されます。
DPoP （Demonstration of Proof-of-Possession）：クライアントは、パブリッククライアントのリプレイとトークン盗難に対する保護→ワンタイムキーで各リクエストに署名します。
重要なルート（支払い変異）の場合-メカニズムの1つが必要です。

5）承認： スコープ、役割、ABAC

スコープ-最小アクション（'payment： write'、 'payments： status： read'）。
役割-管理者のための単位。スコープなしでそれらを直接使用しないで下さい。
ABAC-トークン内の属性（'tenant'、 'country'、 'kyc_level'、 'risk_flags'）→ゲートウェイ/OPA上のポリシー。
ルート/フィールドレベル（GraphQL）およびドメイン操作レベル（REST/gRPC）のポリシー。

6） HMAC署名： webhooksおよびパートナー

6.1コンセプト

それぞれの統合には独自の秘密があります。

正規行の上のキャプション： 'timestamp+「\n「+method+「\n」+path+「\n「+sha256 （body）'

タイトル： 

X-Signature: v1=base64(hmac_sha256(secret, canonical_string))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF...

時間の窓：≤ 300秒；期限切れ/未来の'X-Timestamp'でリクエストを拒否します。
Idempotence： TTL （24時間）で「X-Event-Id」を保存します。重複を破棄します。

6.2ベストプラクティス

KMS/Vaultの秘密、90日ごとに回転します。
パブリッククライアントの場合、HMACは適していません（秘密漏洩）。OAuth2/DPoPを使用して下さい。

7）再生、ブルートフォースおよび漏出に対する保護

機密操作のためのNonce/' jti'；使用される識別子のブラックリスト。
レート/クォータ：キー/クライアント/テナント/ルート；「高価な」操作は個別のクォータです。
パートナーとWebhookのIP/ASN/Geo allow-list。
Content-type allow （'application/json'）、本体サイズ制限。
ログのPIIマスキング；トークン/秘密を記録することを禁止します。

8）エラーと回答（シングルフォーマット）

エラー構造： 
json
{
"error": "invalid_token",
"error_description": "expired",
"trace_id": "4e3f-..."
}
ステータス：
  • '401'-いいえ/無効なトークン（WWW-Authenticate）。
  • '403'-不十分な権利（スコープ/ABAC）。
  • '429'-制限/クォータ。
  • gRPC： 'UNAUTHENTICATED'/'PERMISSION_DENIED'/'RESOURCE_EXHAUSTED'。

9）期間とセッションポリシー

アクセス≤ 15分；リフレッシュ-回転+再利用検出（提出済み-セッションのリコール）。
Webhooks HMAC： TTL署名≤ 5分；指数関数的なバックオフで繰り返し配信。
セッション/キーの失効→失効リストへの即時のエントリ（ゲートウェイ上のキャッシュ≤ 1分）。

10）観察可能性および監査

'trace_id'/'span_id'による相関。
メトリクス：auth success rate、 '401/403/429'、 OIDC/JWKSレイテンシー、回転周波数、再利用リフレッシュ、DPoP/mTLSトラフィックの共有。
監査ログ：「who、 when、 which with 'sub/tenant/scope'が何を引き起こしたか」、key/secret changes、 failed HMAC signature。

11）ゲートウェイAPIへの埋め込み

ゲートウェイ上のJWT検証（JWKSキャッシュ）とOPA/ABAC。
信頼できるクライアント/パートナーのためのmTLSプロファイル。
（社内サービスの前に）エッジ上のWebhookのHMAC検証。
レート/クォータポリシー、OIDCプロバイダのサーキットブレーカ（キャッシュJWK）。
Feature-flags：クライアント/キーの迅速な切断、署名アルゴリズムの変更。

12）ミニスニペット

疑似： JWT検証

pseudo jwks = cache. getOrFetch(iss + "/.well-known/jwks. json")
key = jwks[kid]
assert verify_signature(jwt, key)
assert aud in ALLOWED_AUDIENCES and iss in TRUSTED_ISSUERS assert now in [nbf-60s, exp+60s]

擬似： HMACのwebhookを点検すること

pseudo canonical = timestamp + "\n" + method + "\n" + path + "\n" + sha256(body)
sig = base64(hmac_sha256(secret, canonical))
assert abs(now - timestamp) <= 300 assert not seen(event_id)
assert timingSafeEqual(sig, header["X-Signature"].split("v1=")[1])
markSeen(event_id, ttl=86400)

スコープポリシー例（OPA/Regoアイデア）

rego allow {
input. jwt. scope[_] == "payments:write"
input. jwt. tenant == input. route. tenant
}

13）インシデントプレイブック

プライベートキーリーク/JWT-signer：キーの再発行、JWKSの更新、古い（'kid'→deny）の即時無効化、障害の更新、強制ログアウト。
Webhookの置換：秘密の回転、IP allow-list、 'X-Timestamp'ウィンドウの増幅、失敗したイベントの繰り返し配信。
Replay/brute-force：重要なルート、狭いクォータ、IP/ASNによる一時ブロックでDPoP/mTLSを有効にし、'jti'ブロックリストを有効にします。
OIDCの停止：キャッシュされたトークン（恵み）、サーキットブレーカープロバイダ、顧客通知の劣化。

14）実装チェックリスト

認証（最小）：
  • OAuth2： Code+PKCE （Web/Mobile）、 Client Credentials （server-to-server）
  • TTL：アクセス≤ 15分、回転とリフレッシュし、再利用検出
  • JWKS： 2つのアクティブキー、'kid'、キャッシュ≤ 5分
  • Webhooks： HMAC v1、 'X-Timestamp'、 'X-Event-Id'、ウィンドウ≤ 300 sec、 idempotency
  • 送信者制約：重要なルート上のmTLS/DPoP
  • ABAC/OPA：ゲートウェイポリシーにおけるスコープ+テナント/リスク
  • レート/クォータ#429；パートナーのIP/ASN許可リスト
  • 監査とアラート(401/403/429、再利用リフレッシュ、HMAC署名）
プライバシー/ログ：
  • トークン/シークレット/フルカード本体をログインしない
  • PIIマスキング；DSARサポート；ログの保存期間は限られています

15）アンチパターン

'alg=none'または署名検証/JWKSなしのトークンを信頼します。
長寿命のアクセストークン（時間/日）。
すべてのパートナーに共通のHMAC秘密が1つあります。
タイムスタンプ/idempotencyなしのWebhook。
回転なしで、再利用検出なしでトークンを更新します。
'aud'/'iss'の検証と'kid'の回転の欠如。
KMS/Vaultなしの環境変数にシークレットを格納します。

16） NFT/SLO（ランドマーク）

OIDC/JWKSの可用性≥ 99です。95％（エッジキャッシュは依存関係を低減）

ゲートウェイ上のJWT検証添加剤≤ 2-5 ms p95です。
認証エラー（'401'） ≤ 0。トラフィック全体の5％（ボットを除く）。
署名されたwebhooks：正常に検証された≥ 99の共有。9％、平均配達遅延≤ 3 s。

概要

メカニズムを組み合わせる：ユーザーと豊富なサーバースクリプトのためのOAuth2/OIDC+JWT、 Webhook/Simple PartnersのためのHMAC、重要な操作のためのmTLS/DPoP。短いTTL、キー回転（JWKS）、厳格なABAC/OPAポリシーを保持し、ループをリプレイやリークから保護し、APIゲートウェイレベルですべてを自動化します。そのため、UXや収益化に妥協することなく、認証は予測可能でスケーラブルで安全になります。

Contact

お問い合わせ

ご質問やサポートが必要な場合はお気軽にご連絡ください。いつでもお手伝いします！

統合を開始

Email は 必須。Telegram または WhatsApp は 任意。

お名前 任意
Email 任意
件名 任意
メッセージ 任意
Telegram 任意
@
Telegram を入力いただいた場合、Email に加えてそちらにもご連絡します。
WhatsApp 任意
形式：+国番号と電話番号（例：+81XXXXXXXXX）。

ボタンを押すことで、データ処理に同意したものとみなされます。