トークンの取り消しと承認

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示します。

トークンの取り消しについて

アプリで個々のトークンを明示的に取り消すか無効にしなければならない場合があります。たとえば、ユーザーが OAuth 対応アプリからログアウトする場合などです。取り消されたトークンは承認に使用できなくなります。トークンが取り消された後、アプリがそのトークンを API プロキシに提示すると、VerifyAccessToken オペレーションを含む OAuthV2 ポリシーはそのトークンを拒否します。

トークン取り消しの規格は IETF RFC 7009（OAuth 2.0 トークン取り消し仕様）によって定義されています。

特定のトークンを取り消す代わりに、クライアント ID またはデベロッパーアプリ全体を取り消すこともできます。詳細については、デベロッパーアプリキーの取り消しと承認をご覧ください。個々のトークンを取り消す場合と比較して、クライアント ID またはデベロッパーアプリを取り消す場合の影響は大きくなります。クライアント ID またはデベロッパーアプリを取り消すと、Apigee はそのクライアント ID またはデベロッパーアプリに関連付けられているすべてのトークンを拒否し、そのクライアント ID またはデベロッパーアプリに対して新しいトークンを発行しなくなります。

アクセストークンまたは更新トークンのいずれかを取り消した後でも、有効期限が切れる前であれば、トークンをいつでも再承認できます。トークンを再承認すると、Apigee OAuthV2 ポリシーでトークンの有効期限が切れるまで、トークンが受け入れられます。トークンの有効期限は、トークンの承認済み状態または取り消し状態とは関係ありません。ValidateAccessToken のオペレーションを含む Apigee OAuthV2 ポリシーは、トークンが承認され（または取り消されていない）、有効期限が切れていない場合にのみアクセストークンを受け入れます。同様に、RefreshAccessToken のオペレーションを含む Apigee OAuthV2 ポリシーは、トークンが承認され（または取り消されていない）、有効期限が切れていない場合にのみ更新トークンを受け入れます。

トークンを取り消すには、次の 2 つのポリシーを使用できます。

OAuthV2 ポリシー（InvalidateToken の Operation を使用）
RevokeOAuthV2 ポリシー

OAuthV2 ポリシーには、一度に 1 つのトークンを取り消して復元する機能があります。RevokeOAuthV2 ポリシーは、アプリ ID またはエンドユーザー ID によって、複数のトークンを一度に柔軟に取り消すことができます。このページの残りの部分では、OAuthV2 ポリシーを使用してトークンを取り消すか、以前に取り消したトークンを復元する方法について説明します。

アクセストークンと更新トークンの取り消し

次に、InvalidateToken オペレーションを使用する OAuthV2 ポリシーの構成例を示します。この場合、Token 要素の cascade 属性が true のため、Apigee はアクセストークンとそれに関連付けられた更新トークンの両方を取り消します。

  <OAuthV2 name="InvalidateToken">
    <Operation>InvalidateToken</Operation>
    <Tokens>
      <Token type="accesstoken" cascade="true">request.queryparam.token</Token>
    </Tokens>
  </OAuthV2>

cascade フラグの仕組みの詳細については、Token 要素の属性に関する以下のセクションをご覧ください。

<Tokens> / <Token> 要素

取り消し対象のトークンを指定するフロー変数を指定します。たとえば、デベロッパーが access_token という名前のクエリパラメータを使用して取り消しリクエストを送信する場合、正しいフロー変数は request.queryparam.access_token になります。たとえば、HTTP ヘッダーでトークンを要求するには、この値を request.header.access_token に設定します。

JWT 形式のアクセストークンを取り消すことはできません。また、OAuthV2 ポリシーを使用して、JWT 形式のアクセストークンに関連付けられている更新トークンを取り消すことはできません。ここで指定されたコンテキスト変数が、JWT アクセストークン、または JWT アクセストークンに関連付けられた更新トークンを参照している場合、ランタイムエラーが発生します。RevokeOAuthV2 ポリシーを使用すると、JWT アクセストークンに関連付けられた更新トークンを取り消すことができます。

属性

type（必須、文字列）: 指定された変数によって識別されるトークンタイプ。サポートされる値は、accesstoken と refreshtoken: です。
- アクセストークンを取り消す場合は、タイプ accesstoken を指定します。
- アクセストークンと更新トークンの両方を取り消す場合は、タイプ refreshtoken を指定します。タイプ refreshtoken が確認されると、トークンは更新トークンであると見なされます。更新トークンが見つかると、トークンが取り消されます。更新トークンが見つからない場合、Apigee はそれがアクセストークンかどうかをチェックします。アクセストークンが存在する場合は、トークンが取り消されます。
  
  注: すでに無効となっているトークンを InvalidateToken ポリシーに渡すと、ポリシーは、見込みどおりにエラーを返しません。そのようなオペレーションは効果がありません。
cascade（省略可、ブール値、デフォルト: true）: この属性の主な用途は、関連するアクセストークンを取り消さずに更新トークンを取り消すことです。次のような状況を考えてみましょう。
- 更新トークンのみを取り消し、関連するアクセストークンを取り消さない場合。これを行うには、<Token> タイプを refreshtoken に設定し、続けてカスケードを false に設定します。
- アクセストークンと更新トークンの両方を取り消す場合。これを行うには、<Token> タイプを accesstoken に設定します。カスケードの値は true（デフォルト）または false です。この値を true に設定すると、アクセストークンと更新トークンの両方が取り消されます。false に設定すると、アクセストークンが取り消され、更新トークンが使用できなくなります。詳細については、以下の注を参照してください。
- アクセストークンを取り消し、関連する更新トークンは取り消さない場合。サポートされていない詳しくは、以下の注をご覧ください。

注: セキュリティ上の理由から、アクセストークンを取り消すと、関連する更新トークンも取り消されます。このため、カスケード属性を使用してアクセストークンのみを取り消すことはできません。たとえば、<Token> タイプを accesstoken に設定して cascade=false を設定すると、アクセストークンが（予測どおり）取り消されますが、関連の更新トークンは使用できなくなります。更新トークンを、取り消されたアクセストークンの更新に使用することはできません。cascade 属性の主な用途は、更新トークンのみを取り消す必要がある場合です。その場合、<Token> タイプを refreshtoken に設定し、cascade=false を設定します。更新トークンは取り消されますが、関連するアクセストークンは有効姓が保持されます（有効期限が切れるか、取り消されるまで）。詳細は、こちらのコミュニティフォーラムのディスカッションをご覧ください。

アクセストークンと更新トークンの承認

ValidateToken オペレーションは、取り消されたトークンの「再承認」に使用されます。つまり、このオペレーションを適用すると、対象のアクセストークンや更新トークンのステータスが「取り消し済み」から「承認済み」に変更されます。すでに有効期限が切れている取り消し済みトークンを有効にできます。

<OAuthV2 name="ValidateToken">
  <Operation>ValidateToken</Operation>
  <Tokens>
    <Token type="refreshtoken" cascade="true">flow.variable</Token>
  </Tokens>
</OAuthV2>

<Tokens> /<Token> 要素

有効にするトークンを指定するフロー変数を指定します。たとえば、デベロッパーが access_token という名前のクエリパラメータを使用して検証リクエストを送信する場合、正しいフロー変数は request.queryparam.access_token になります。たとえば、HTTP ヘッダーでトークンを要求するには、この値を request.header.access_token に設定します。

属性

type（必須、文字列）: 指定された変数によって識別されるトークンタイプ。サポートされる値は、accesstoken と refreshtoken です。
cascade（省略可、ブール値）: デフォルトでは、このオプションは true に設定され、検証が関連するトークンに反映されます。このため、更新トークンに適用した場合、その関連トークンも有効化されます。アクセストークンに適用した場合は、関連する更新トークンも有効化されます。これを false に設定した場合は、指定されたアクセストークンまたは更新トークンのみが有効化されます。