スロットルメカニズム throttling-mechanism
すべてのパス認証のお客様は、手順とビジネスケースに従って、各ユーザーのパス認証 API にアクセスできる必要があります。
パス認証では、お客様のユーザー間でリソースを公平に分配するためのスロットルメカニズムが導入されています。
このメカニズムが重要な理由は次のとおりです。
- マルチテナントアーキテクチャの優れたルールの 1 つは、あるユーザーの行動が他のユーザーに影響を与えないということです。
- レート制限は、API と統合する際に間違いが生じやすいため、API にとって重要です。 API はプログラムで使用されるので、意図したよりも多くのリクエストを誤って送信することは比較的簡単です。
メカニズムの概要 mechanism-overview
クライアントの実装
パス認証は、API を操作するためのガイドラインと SDK を提供しますが、顧客による API の使用方法は制御しません。 一部の実装には基本的な実装が含まれている場合があり、誤ってもしなくても、サービスに不要な API リクエストが殺到する可能性があります。これは、他のユーザーに速度の低下や容量の問題が発生することを意味する場合があります。
サービス自体は、合理的な容量を処理できる必要があります。 ただし、サービスの拡張性やパフォーマンスに関係なく、常に制限があります。 そのため、サービスには、特定の期間内で許可される呼び出しの数に対する制限が設定されている必要があります。
スロットルの概要
パス認証は、ユーザー識別と、API に対する各ユーザーのデバイスアクセスを制御するための事前定義済みの値を持つトークンバケットレート制限アルゴリズムに基づいています。
デバイスの識別メカニズム
提案されているスロットルメカニズムは、「X-Forwarded-For」ヘッダーを使用して、識別されたデバイスを個別に使用します。 制限は、各デバイスに対して同じ方法で適用されます。
必要な更新
サーバー間の実装では、「X-Forwarded-For」ヘッダーメカニズムを使用してクライアントの IP アドレスを転送する必要があります。
X-Forwarded-For ヘッダーの渡し方の詳細については、 こちらをご覧ください。
実際の上限とエンドポイント
現在、デフォルトの制限では、1 秒あたり最大 1 件のリクエストが許可され、初期バーストは 10 件のリクエストが許可されます（識別されたクライアントの最初のインタラクションで 1 回の許可が必要です。これにより、初期化が正常に終了します）。 これは、すべての顧客の通常のビジネスケースには影響しません。
スロットルメカニズムは、次のエンドポイントで有効になります。
- /o/client/register
- /o/client/token
- /o/client/scopes
- /o/client/validate
- /api/v2/
- /api/v1/tokens/usermetadata
- /api/v1/tokens/authn
- /api/v1/tokens/authz
- /api/v1/tokens/media
- /api/v1/config/
- /api/v1/checkauthn
- /api/v1/logout
- /api/v1/authorize
- /api/v1/preauthorize
- /api/v1/mediatoken
- /api/v1/authenticate/freepreview
- /api/v1/authenticate/
- /api/v1/.+/profile-requests/.+
- /api/v1/identity
- /adobe-services/config/
- /reggie/v1/.+/regcode
- /reggie/v1/.+/regcode/.+
SDK 実装の曖昧さ
Adobe Pass認証が提供する SDK を使用するクライアントは明示的にはエンドポイントとやり取りしていないため、この節では、既知の関数、スロットル応答が発生した場合の動作、実行する必要があるアクションについて説明します。
setRequestor
SDK の関数を使用してスロットル制限 setRequestor 到達すると、SDK はコールバックを通じて CFG429 エラーコード errorHandler 返します。
getAuthorization
SDK の関数を使用してスロットル制限 getAuthorization 到達すると、SDK はコールバックを通じて Z100 エラーコード errorHandler 返します。
checkPreauthorizedResources
SDK の関数を使用してスロットル制限 checkPreauthorizedResources 到達すると、SDK はコールバックを通じて P100 エラーコード errorHandler 返します。
getMetadata
SDK の関数を使用してスロットル制限 getMetadata 到達すると、SDK はコールバックを通じて空の応答 setMetadataStatus 返します。
実装の詳細については、それぞれの SDK ドキュメントを参照してください。
API 応答の変更と応答
制限に違反していると判断した場合、このリクエストを特定の応答ステータス（HTTP 429 Too Many Requests）でマークし、ユーザーデバイスに割り当てられているすべてのトークン（IP アドレス）を時間間隔で消費するように指示します。
スロットルは、最初の 429 応答のうち 1 秒後に有効期限が切れます。 429 応答を受信する各アプリケーションは、新しいリクエストを生成するまで、少なくとも 1 秒待つ必要があります。
すべての顧客アプリケーションは、「429 Too Many Requests」応答を適切に処理する必要があります。
次に、429 応答メッセージのサンプルを示します。
HTTP/2 429
date: Tue, 20 Feb 2024 11:21:53 GMT
content-type: text/html
content-length: 166
set-cookie: AWSALB=Btl/GzifUpMhUh+TQK63kU4i+gcJOIvAICVLnHTWt5pkrevNsMSQ5DMwM9KlRkNQ0UlXHIDbQoxDua0oVYYFKC8PDwxQjOuuRzxX2fozM+Jcazl2DSfaR7hU2mt2; Expires=Tue, 27 Feb 2024 11:21:53 GMT; Path=/
set-cookie: AWSALBCORS=Btl/GzifUpMhUh+TQK63kU4i+gcJOIvAICVLnHTWt5pkrevNsMSQ5DMwM9KlRkNQ0UlXHIDbQoxDua0oVYYFKC8PDwxQjOuuRzxX2fozM+Jcazl2DSfaR7hU2mt2; Expires=Tue, 27 Feb 2024 11:21:53 GMT; Path=/; SameSite=None; Secure
server: openresty
access-control-allow-credentials: true
access-control-allow-methods: POST,GET,OPTIONS,DELETE
access-control-allow-headers: ap_11,ap_42,ap_z,ap_19,ap_21,ap_23,authorization,content-type,pass_sfp,AP-Session-Identifier,AP-Device-Identifier,AP-SDK-Identifier,X-Device-Info
access-control-expose-headers: pass_sfp,Authzf-Error-Code,Authzf-Sub-Error-Code,Authzf-Error-Details
p3p: CP="NOI DSP COR CURa ADMa DEVa OUR BUS IND UNI COM NAV STA"
<html>
<head><title>429 Too Many Requests</title></head>
<body>
<center><h1>429 Too Many Requests</h1></center>
<hr><center>openresty</center>
</body>
</html>
影響と必要な変更
X-Forwarded-For ヘッダーを渡す
カスタム実装（サーバー間を含む）を使用して Pass Authentication API とやり取りするお客様は、ユーザー IP アドレスを確実に取得し、X-Forwarded-For ヘッダーを使用して正しく転送する必要があります。
詳しくは こちらを参照してください。
新しい応答コードへの対応
カスタム実装（サーバー間リクエストを含む）を使用してパス認証 API とやり取りするお客様は、429 リクエストが多すぎる後に行われる後続の呼び出しに 1 秒以上の待機期間を含める必要があります。 この待機期間により、このメカニズムを変更し、有効なビジネスレスポンスを取得する機会が確保されます。