実運用でのトークンライフサイクル

どのOAuthフローガイドにもrefresh_tokenは登場しますが、多くのリクエスト・ワーカー・日数にわたって稼働し続ける長期的なインテグレーションでは、「期限が来たらトークンを差し替える」だけでは不十分です。このページでは、実際のトークン有効期間、複数ワーカー間でのトークンのキャッシュ方法、更新のタイミング、そして本来の期限より前にトークンが無効化される要因を扱います。

---

フローごとのトークン有効期間

アクセストークンの有効期間はすべてのフローで共通の固定値です。一方リフレッシュトークンの有効期間はそうではなく、どのOAuthフローが発行したかによって異なります。

フロー	アクセストークンのTTL	リフレッシュトークンのTTL
Client Credentialsフロー	約1時間	約30日
ネイティブアプリケーションフロー(PKCE、ループバックリダイレクト)	約1時間	固定の有効期限なし:ローテーションで置き換えられるか失効するまで有効
Authorization Code + Custom Redirect Flow	約1時間	固定の有効期限なし:ローテーションで置き換えられるか失効するまで有効

ノート

どちらのAuthorization Codeフローも、セッションクロックを一切持たないリフレッシュトークンを発行します。とはいえ無期限に使われないまま残るわけではありません。これは1回限りのトークンで、更新のたびに置き換えられます(詳細は下記の同時リフレッシュの競合を参照)。また、グラントが失効すると直ちに機能しなくなります。

トークンをキャッシュする(リクエストごとに新規発行しない)

APIコールのたびに、あるいは各ワーカープロセスで独立にアクセストークンを新規発行することは可能ですが、すでに約1時間有効なトークンのために、リクエストごとに往復を無駄にしてしまいます。トークンを1つ取得し、発行元の認証情報をキーとしてキャッシュし(単一プロセスならメモリ上、ワーカー群であればRedisなどの共有ストアに)、期限が近づくまではすべてのリクエストにそのキャッシュ済みトークンを渡してください。

これはリフレッシュトークンにとっても重要です。独立に交換するプロセスが少ないほど、以下で説明する競合状態に陥る可能性は低くなります。

401だけでなく有効期限で更新する

アクセストークンのTTLは固定で事前にわかっているため、プロアクティブに更新してください。トークンを取得した時刻を記録するか(あるいはexpクレームをデコードして)、その直前に新しいトークンを要求します。リクエストが失敗するのを待ってから対応するのではありません。

とはいえフォールバックとして失敗したリクエストへの対応も用意し、受け取ったエラーによって処理を分けてください。

• not_authenticatedを伴う401:リクエストに利用可能なベアラートークンがまったく含まれていませんでした。これはクライアント側の不具合(Authorizationヘッダーの欠落や不正な形式)であり、更新すべきサインではありません。
• invalid_tokenを伴う401:トークンの署名または有効期限のチェックに失敗しました。更新して一度だけ再試行してください。
• 403:トークンの問題であることは決してありません。トークンは有効ですが、呼び出し元がその操作に必要なスコープ、コンテンツアクセス権、またはロールを持っていません。更新しても解決しません。各コードの詳細はエラーコード:レート制限・認証・アクセス制御を参照してください。

同時リフレッシュの競合

リフレッシュトークンは1回限りです。grant_type=refresh_tokenで交換すると、そのリフレッシュトークンは無効化され、新しいアクセストークンと新しいリフレッシュトークンが同時に発行されます。複数のワーカーが同じキャッシュ済みリフレッシュトークンを共有していて、そのうち2つがほぼ同時に更新を試みた場合、成功するのは一方の交換だけです。もう一方は「使用済み」と区別できる特別なエラーではなく、汎用的な401を受け取ります。

注意

共有されたリフレッシュトークンに対して、各ワーカーが独立に更新を行わないようにしてください。更新呼び出しの所有者を1つに定め(更新処理をロックで保護するか、専用の更新ルーチンを用意する)、他のワーカーは自分で更新するのではなく、共有キャッシュから結果のアクセストークンを読み取るようにしてください。

トークンが早期に無効化される要因

以下のいずれの出来事も、有効なアクセストークンを直接失効させるわけではありません。それぞれがブロックするのは新規の何か(新しいトークン要求や次回の更新)であり、すでに手元にあるアクセストークンは自身のTTLが尽きるまで機能し続けます。

要因	影響
OAuthアプリケーションのクライアントシークレットがローテーションされた	古いシークレットを使った新しいトークン要求や更新要求は直ちに拒否されます。すでに発行済みのアクセストークンには影響がなく、自然に期限切れになるまで機能し続けます。
OAuthアプリケーションまたはそのサービスユーザーが削除された	そのアプリケーション向けの新しいトークン発行がブロックされます。すでに発行済みのトークンは積極的には失効されません。
OAuthアプリケーションのスコープが変更された	すでに発行済みのアクセストークンは、残りの有効期間中は元のスコープを保持します。トークンが新しいスコープを取得するのは、次回更新または再発行されたときだけです。
グラントが明示的に失効された	次回の更新試行は直ちにブロックされます。まだ有効なアクセストークンは強制的に失効させられず、自然に期限切れになるまで機能し続けます。

ノート

これらの出来事のいずれについても、実質的な影響範囲はリフレッシュトークンのTTLではなく、アクセストークン自身のTTL(約1時間)です。どの出来事もすでに発行済みのトークンには触れないためです。この影響範囲を即座にゼロにしたい場合は、グラントの失効とシークレットのローテーションを同時に行い、その後アクセストークン1回分のTTLが経過するまでインテグレーションを未承認として扱ってください。

次のステップ

• エラーコード:401と403の各レスポンスの詳細な内訳
• Client Credentialsフロー、ネイティブアプリケーションフロー、またはAuthorization Code + Custom Redirect Flow:最初のトークンを取得する方法