OAuthV2 ポリシー

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

Apigee Edge のドキュメントはこちらをご覧ください。

ポリシー アイコン

概要

OAuthV2 は OAuth 2.0 権限付与タイプ オペレーションを実行するための多角的なポリシーです。これは、Apigee で OAuth 2.0 エンドポイントを構成するために使用される最も重要なポリシーです。

このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用率に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

ヒント: Apigee での OAuth の詳細については、OAuth ホームページをご覧ください。リソース、サンプル、動画などへのリンクが記載されています。

サンプル

VerifyAccessToken

VerifyAccessToken

この OAuthV2 ポリシー構成（VerifyAccessToken オペレーションで使用）は、Apigee に送信されたアクセス トークンが有効かどうかを検証します。このポリシー オペレーションがトリガーされると、Apigee はリクエストで有効なアクセス トークンを探します。アクセス トークンが有効な場合、リクエストのフローを続行できます。無効な場合、すべての処理が停止し、レスポンスでエラーが返されます。

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

クライアント アプリケーションは、トークンを使用してリクエストを送信する必要があります。たとえば、curl を使用する場合は次のようにします。

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

ここで、API_ENDPOINT は Apigee システムで構成された API へのアクセスに使用されるドメインです。

デフォルトでは、OAuthV2 ポリシーは、Authorization ヘッダーからアクセス トークンを抽出し、Bearer 接頭辞を削除します。このデフォルトの動作は、AccessToken 構成要素で変更できます。

GenerateAccessToken

アクセス トークンの生成

サポートされている権限付与タイプごとにアクセス トークンをリクエストする方法の例については、OAuth 2.0 トークンを取得するをご覧ください。このトピックには、次のオペレーションの例が記載されています。

GenerateAuthorizationCode

認証コードを生成する

認証コードをリクエストする方法を示す例については、認証コードのリクエストをご覧ください。

RefreshAccessToken

アクセス トークンを更新する

更新トークンを使用してアクセス トークンをリクエストする方法を示す例については、アクセス トークンの更新をご覧ください。

JWT アクセス トークン

JWT アクセス トークン

JWT アクセス トークンを生成、検証、更新する例については、JWT アクセス トークンの使用をご覧ください。

レスポンス フロー トークン

レスポンス フローでアクセス トークンを生成する

レスポンス フローでアクセス トークンの生成が必要になることがあります。たとえば、バックエンド サービスで行われたカスタム検証に対するレスポンスで、これを行う場合があります。この例のユースケースにはアクセス トークンと更新トークンの両方が必要で、暗黙権限付与タイプは認められません。このような場合、パスワード権限付与タイプを使用してトークンを生成します。これを成功させるコツは、次のように JavaScript ポリシーを使用して Authorization リクエスト ヘッダーで渡すことです。

まずサンプル ポリシーを見てみましょう。

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

このポリシーをレスポンス フローに配置すると、ポリシーでログイン パラメータが正しく指定されていたとしても 401 UnAuthorized エラーで失敗します。この問題を解決するには、Authorization リクエスト ヘッダーを設定する必要があります。

Authorization ヘッダーには、Base64 でエンコードした client_id:client_secret を使用した基本アクセス スキームが含まれている必要があります。

このヘッダーは、OAuthV2 ポリシーの直前に JavaScript ポリシーを配置して追加できます。コンテキスト変数「local_clientid」と「local_secret」は事前に設定し、フローで使用できるようにする必要があります。

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

基本認証用の認証情報のエンコードもご覧ください。

要素リファレンス

このポリシー リファレンスでは、OAuthV2 ポリシーの要素と属性について説明します。

次に示すサンプル ポリシーは、使用可能な多くの構成の中の 1 つです。このサンプルでは、GenerateAccessToken オペレーション用に構成された OAuthV2 ポリシーを示しています。これには、必須の要素と省略可能な要素が含まれています。詳しくは、このセクションの要素の説明をご覧ください。

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

<OAuthV2> 属性

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

次の表に、すべてのポリシーの親要素に共通する属性を示します。

属性 説明 デフォルト 要否
name

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

 なし 必須
continueOnError

ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。

ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連項目:

 false 省略可
enabled

ポリシーを適用するには、true に設定します。

ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。

 true 省略可
async

この属性は非推奨となりました。

 false 非推奨

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>
デフォルト

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます。
要否 省略可
タイプ 文字列

<AccessToken> 要素

<AccessToken>request.header.access_token</AccessToken>

デフォルトでは、Operation が VerifyAccessToken の場合、アクセス トークンが Authorization ヘッダーで署名なしトークンとして送信されることがポリシーで想定されます。つまり、接頭辞「Bearer」の後に 1 つの空白スペースが続きます。この要素を使用して、検証するアクセス トークンを含む変数の名前を指定し、デフォルトを変更できます。この要素を使用する場合、デフォルトではポリシー内で変数の内容の接頭辞は検索されません。ポリシーで接頭辞を検索するように指定する場合は、AccessTokenPrefix 要素も使用します。

例:

  • ポリシー構成が以下に該当する場合:

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.header.access_token</AccessToken>
  </OAuthV2>

    curl を使用してトークンを渡すには、次のコマンドを使用します。

      curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

  • ポリシー構成が以下に該当する場合:

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.queryparam.token</AccessToken>
  </OAuthV2>

    curl を使用してトークンを渡すには、次のコマンドを使用します。

      curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

ここで、API_ENDPOINT は Apigee システムで構成された API へのアクセスに使用されるドメインです。

デフォルト:

なし

プレゼンス:

省略可
型: 文字列
有効な値:

任意の変数名
使用するオペレーション:
  • VerifyAccessToken

<AccessTokenPrefix> 要素

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

デフォルトでは、Operation が VerifyAccessToken の場合、アクセス トークンが Authorization ヘッダーで署名なしトークンとして送信されることがポリシーで想定されます。つまり、接頭辞「Bearer」の後に 1 つの空白スペースが続きます。AccessToken 要素を使用して受信アクセス トークンの別の場所を指定している場合は、この要素 AccessTokenPrefix を使用して別の標準以外の接頭辞を指定することもできます。

たとえば、次のように指定するとします。

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

次に、ポリシーは token リクエスト ヘッダーからインバウンド アクセス トークンを抽出します。ヘッダーが「KEY」という単語で始まり、その後にスペースが続く場合、ポリシーによってこの接頭辞と残りの値をアクセス トークンと解釈します。指定された接頭辞がヘッダーに存在しない場合、ポリシーはエラーをスローします。

AccessToken 要素を指定していて、AccessTokenPrefix 要素を指定しない場合、ポリシーは AccessToken 要素内で指定された変数の値全体をアクセス トークンとして解釈します。

この要素は、AccessToken 要素も使用されている場合にのみ有効になります。

デフォルト:

なし

プレゼンス:

省略可
型: 文字列
有効な値:

文字列
使用するオペレーション:
  • VerifyAccessToken

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

JWT アクセス トークンの署名に使用される暗号化アルゴリズムを指定します。RSA（RS*）アルゴリズムは公開鍵 / 秘密鍵ペアを使用し、HMAC（HS*）アルゴリズムは共有シークレットを使用します。この要素は、GenerateJWTAccessToken、VerifyJWTAccessToken、RefreshJWTAccessToken のオペレーションに必要です。

デフォルト 該当なし
プレゼンス GenerateJWTAccessToken、VerifyJWTAccessToken、RefreshJWTAccessToken のオペレーションを使用する場合は必須です。
タイプ 文字列
有効な値 HS256、HS384、HS512、RS256、RS384、RS512

<AppEndUser> 要素

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

アプリ エンドユーザー ID を認可サーバーに送信する必要がある場合、この要素を使用すると、エンドユーザー ID をどこで探すかを Apigee に指示できます。たとえば、この ID をクエリ パラメータとして、または HTTP ヘッダーに含めて送信できます。

たとえば、request.queryparam.app_enduser は AppEndUser がクエリ パラメータとして存在する必要があることを示します（例: ?app_enduser=ntesla@theramin.com）。HTTP ヘッダーで AppEndUser を要求するには、この値を request.header.app_enduser に設定します。

この設定を指定すると、アプリ エンドユーザー ID をアクセス トークンに含めることができます。この機能は、エンドユーザー ID で OAuth 2.0 アクセス トークンを取得または取り消す場合に便利です。詳細については、エンドユーザー ID、アプリ ID、またはこの両方を使用して OAuth 2.0 アクセス トークンの取得と取り消しを可能にするをご覧ください。

デフォルト:

なし

プレゼンス:

省略可
型: 文字列
有効な値:

実行時にポリシーにアクセスできる任意のフロー変数
使用する権限付与タイプ:
  • authorization_code
  • implicit
  • password
  • client_credentials

<Attributes/Attribute>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

この要素は、アクセス トークンまたは認証コードにカスタム属性を追加する場合に使用します。たとえば、実行時に抽出と確認ができるユーザー ID またはセッション ID をアクセス トークンに埋め込む場合などです。

この要素を使用すると、フロー変数やリテラル文字列から値を指定できます。変数と文字列の両方を指定すると、フロー変数で指定された値が使用されます。変数を解決できない場合は、文字列がデフォルトとして使用されます。

この要素の詳しい使用方法については、トークンと認証コードのカスタマイズをご覧ください。

レスポンスでカスタム属性を表示または非表示にする

このポリシーの GenerateResponse 要素を true に設定すると、設定したカスタム属性を含む、トークン内の完全な JSON 表現が返されます。場合によっては、レスポンス内のカスタム属性の一部またはすべてを非表示にして、クライアント アプリに表示されないようにすることもできます。

デフォルトでは、カスタム属性がレスポンスで表示されます。非表示にする場合は、[display] パラメータを [false] に設定します。次に例を示します。

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

display 属性の値は保持されません。たとえば、レスポンスでカスタム属性が非表示になるように指定してアクセス トークンを生成するとしまう。display=false を設定すると、その目標を達成できます。しかし、更新トークンを使用して後から新しいアクセス トークンを生成すると、アクセス トークンの元のカスタム属性が更新トークンのレスポンスで表示されます。これは、Apigee がアクセス トークンの生成ポリシーで display 属性が最初に false に設定されたことを記憶していないためです。カスタム属性は単にアクセス トークンのメタデータの一部です。

認証コードにカスタム属性を追加した場合にも同じ動作が見られます。そのコードを使用してアクセス トークンを生成すると、それらのカスタム属性がアクセス トークンのレスポンスで表示されます。これも、ユーザーの意図する動作でないかもしれません。

このような場合にカスタム属性を非表示にするには、次の方法があります。

  • 更新トークン ポリシーのカスタム属性を明示的にリセットし、表示を false に設定します。この場合、GetOAuthV2Info ポリシーを使用して、元のアクセス トークンから元のカスタム値を取得する必要が生じることがあります。
  • 後処理の JavaScript ポリシーを使用して、レスポンスに表示しない任意のカスタム属性を手動で抽出します。

トークンと認証コードのカスタマイズもご覧ください。

デフォルト:

N/A

プレゼンス:

任意
有効な値:
  • name - 属性名
  • ref - 属性の値。フロー変数から取得できます。
  • display -（省略可）レスポンスにカスタム属性を表示するかどうかを指定します。true の場合、レスポンスにカスタム属性が表示されます（GenerateResponse も有効な場合）。false の場合、カスタム属性はレスポンスに含まれません。デフォルト値は true です。レスポンスでカスタム属性を表示または非表示にするをご覧ください。
使用する権限付与タイプ:
  • authorization_code
  • implicit
  • password
  • client_credentials
  • refresh_token
  • GenerateAuthorizationCode オペレーションでも使用できます。

<CacheExpiryInSeconds> 要素

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>

この要素はキャッシュに TTL を適用します。これにより、キャッシュされたアクセス トークンの有効期限の期間をカスタマイズできます。サポートされる値の範囲は 1～180 秒です。フロー変数とデフォルト変数を指定できます。このフロー変数の値は、指定したデフォルト値よりも優先されます。

この要素は VerifyAccessToken オペレーションでのみ使用できます。

デフォルト なし

この要素を省略した場合、キャッシュされたアクセス トークンのデフォルトの有効期限は 180 秒です。
プレゼンス 省略可
タイプ 整数
有効な値 ゼロ以外の正の整数。有効期限を秒単位で指定します。

属性

次の表に、<CacheExpiryInSeconds> 要素の属性を示します。

属性 説明 デフォルト プレゼンス
ref

秒単位で表されるキャッシュ有効期限の値を含むフロー変数の参照。

このフロー変数の値は、指定したデフォルト値よりも優先されます。

 なし 任意

<ClientId> 要素

<ClientId>request.formparam.client_id</ClientId>

場合によっては、クライアント アプリからクライアント ID を認可サーバーに送信する必要があります。この要素を使用すると、Apigee でクライアント ID を探す場所を指定できます。設定できる唯一の有効な場所は、デフォルトの場所であるフロー変数 request.formparam.client_id です。ClientId を他の変数に設定することはできません。OAuth 2.0 トークンの取得もご覧ください。

デフォルト:

request.formparam.client_id（x-www-form-urlencoded、リクエストの本文で指定）

プレゼンス:

省略可
型: 文字列
有効な値: フロー変数: request.formparam.client_id
使用する権限付与タイプ:
  • authorization_code
  • password
  • implicit
  • client_credentials

GenerateAuthorizationCode オペレーションでも使用できます。

<Code> 要素

<Code>request.queryparam.code</Code>

認可権限付与タイプのフローでは、クライアントが認証コードを認可サーバー（Apigee）に送信する必要があります。この要素を使用すると、認証コードをどこで探すかを Apigee に指示できます。たとえば、クエリ パラメータ、HTTP ヘッダー、フォーム パラメータ（デフォルト）として送信できます。

変数 request.queryparam.auth_code は、認証コードがクエリ パラメータとして存在する必要があることを示します（例: ?auth_code=AfGlvs9）。たとえば、HTTP ヘッダーで認証コードを要求するには、この値を request.header.auth_code に設定します。OAuth 2.0 トークンの取得もご覧ください。

デフォルト:

request.formparam.code（x-www-form-urlencoded、リクエストの本文で指定）

プレゼンス:

任意
型: 文字列
有効な値: 実行時にポリシーにアクセスできる任意のフロー変数
使用する権限付与タイプ: authorization_code

<ExpiresIn> 要素

<ExpiresIn>10000</ExpiresIn>

アクセス トークンと認証コードの有効期限をミリ秒単位で適用します（更新トークンの場合は、<RefreshTokenExpiresIn> を使用します）。有効期限の値は、システムが生成した値に <ExpiresIn> 値を加えた値です。<ExpiresIn> が -1 に設定されている場合、トークンまたはコードは OAuth アクセス トークンの最大有効期限に従って期限切れになります。<ExpiresIn> が指定されていない場合、システムレベルで構成したデフォルト値が適用されます。

ハードコードされたデフォルト値を使用するか、フロー変数を参照することで、実行時に有効期限を動的に設定することもできます。たとえば、トークン有効期限値を Key-Value マップに格納し、それを取得して変数に割り当て、ポリシーで参照できます。例: kvm.oauth.expires_in

Apigee では、以下のエンティティはアクセスされてから最低 180 秒間、キャッシュに保持されます。

  • OAuth アクセス トークン。OAuth v2 ポリシーの ExpiresIn 要素によって、アクセス トークンを 180 秒未満で期限切れにすることはできません。
  • Key Management Service（KMS）エンティティ（アプリ、デベロッパー、API プロダクト）。
  • OAuth トークンと KMS エンティティのカスタム属性。

次のスタンザでは、フロー変数とデフォルト値も指定しています。フロー変数の値は、指定されたデフォルト値よりも優先される点に注意してください。

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Apigee では、トークンの作成後にトークンを強制的に期限切れにする方法がありません。トークンを条件などに基づいて強制的に期限切れにする必要がある場合に可能な解決策については、こちらの Apigee コミュニティの投稿をご覧ください。

デフォルトでは、期限切れのアクセス トークンは、有効期限の 3 日後に自動的に Apigee システムからパージされます。アクセス トークンのパージもご覧ください。

デフォルト:

指定しない場合、システムレベルで構成したデフォルト値が適用されます。

プレゼンス:

省略可
型: 整数
有効な値:
  • ゼロでない任意の正の整数。有効期限をミリ秒単位で指定します。この要素の値はミリ秒単位ですが、トークンの expires_in プロパティと expires_in フロー変数で設定される値は秒単位で表されます。
  • -1 は、OAuth アクセス トークンの最大有効期限に従って期限切れになります。

    注: そのほかの負の整数またはゼロを指定すると、デプロイエラーが発生します。
使用する権限付与タイプ:
  • authorization_code
  • implicit
  • password
  • client_credentials
  • refresh_token

GenerateAuthorizationCode オペレーションでも使用します。

<ExternalAccessToken> 要素

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

外部アクセス トークン（Apigee によって生成されないアクセス トークン）を探す場所を Apigee に指示します。

変数 request.queryparam.external_access_token は、外部アクセス トークンがクエリ パラメータ（?external_access_token=12345678 など）として存在する必要があることを示します。たとえば、HTTP ヘッダーで外部アクセス トークンを要求するには、この値を request.header.external_access_token に設定します。サードパーティ OAuth トークンの使用もご覧ください。

<ExternalAuthorization> 要素

<ExternalAuthorization>true</ExternalAuthorization>

この要素が false であるか存在しない場合、Apigee は通常、Apigee 認証ストアに対して client_id と client_secret を検証します。この要素は、サードパーティの OAuth トークンを操作する場合に使用します。この要素の使用方法については、サードパーティ OAuth トークンの使用をご覧ください。

デフォルト:

false

プレゼンス:

省略可
型: ブール値
有効な値: true または false
使用する権限付与タイプ:
  • authorization_code
  • password
  • client_credentials

<ExternalAuthorizationCode> 要素

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

外部認証コード（Apigee で生成されない認証コード）を探す場所を Apigee に指示します。

変数 request.queryparam.external_auth_code は、外部認証コードがクエリ パラメータ（?external_auth_code=12345678 など）として存在する必要があることを示します。たとえば、HTTP ヘッダーで外部認証コードを要求するには、この値を request.header.external_auth_code に設定します。サードパーティ OAuth トークンの使用もご覧ください。

<ExternalRefreshToken> 要素

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

外部更新トークン（Apigee によって生成されない更新トークン）を探す場所を Apigee に指示します。

変数 request.queryparam.external_refresh_token は、外部更新トークンがクエリ パラメータ（?external_refresh_token=12345678 など）として存在する必要があることを示します。たとえば、HTTP ヘッダーで外部更新トークンを要求するには、この値を request.header.external_refresh_token に設定します。サードパーティ OAuth トークンの使用もご覧ください。

<GenerateResponse> 要素

<GenerateResponse enabled='true'/>

true に設定する場合、または enabled 属性を省略した場合、ポリシーはレスポンスを生成して返します。たとえば、GenerateAccessToken の場合、レスポンスは次のようになります。

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

false に設定した場合、または <GenerateResponse> 要素を省略した場合、レスポンスは送信されません。代わりに、ポリシーの機能に関連する値が一連のフロー変数に挿入されます。たとえば oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code というフロー変数に、新たに作成された認証コードが挿入されます。レスポンスで expires_in は秒単位で表現されます。

デフォルト:

true

プレゼンス:

省略可
型: 文字列
有効な値: true または false
使用する権限付与タイプ:
  • implicit
  • password
  • client_credentials
  • refresh_token
  • GenerateAuthorizationCode オペレーションでも使用できます。

<GenerateErrorResponse> 要素

<GenerateErrorResponse enabled='true'/>

true に設定すると、ContinueOnError 属性が true に設定されている場合、ポリシーはレスポンスを生成して返します。false（デフォルト）の場合、レスポンスは送信されません。代わりに、ポリシーの機能に関連する値が一連のフロー変数に挿入されます。

デフォルト:

false

プレゼンス:

省略可
型: 文字列
有効な値: true または false
使用する権限付与タイプ:
  • implicit
  • password
  • client_credentials
  • refresh_token
  • GenerateAuthorizationCode オペレーションでも使用できます。

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

渡される権限付与タイプ パラメータをリクエストのどこで探すかをポリシーに指示します。OAuth 2.0 仕様では、アクセス トークンや認証コードのリクエストには権限付与タイプを含めなければなりません。変数として設定できるは、ヘッダー、クエリ パラメータ、またはフォーム パラメータ（デフォルト）です。

たとえば、request.queryparam.grant_type はパスワードがクエリ パラメータ（?grant_type=password など）として存在する必要があることを示します。たとえば、HTTP ヘッダーで権限付与タイプを要求するには、この値を request.header.grant_type に設定します。OAuth 2.0 トークンの取得もご覧ください。

デフォルト:

request.formparam.grant_type（x-www-form-urlencoded、リクエストの本文で指定）

プレゼンス:

省略可
型: 文字列
有効な値: 上述の変数。
使用する権限付与タイプ:
  • authorization_code
  • password
  • implicit
  • client_credentials
  • refresh_token

<Operation> 要素

<Operation>GenerateAuthorizationCode</Operation>

ポリシーによって実行される OAuth 2.0 オペレーション。

デフォルト:

<Operation> が指定されていない場合、Apigee は <SupportedGrantTypes> のリストを確認します。リストに含まれる権限付与タイプのオペレーションのみ成功します。つまり、<SupportedGrantTypes> リストで <GrantType> を指定すると、<Operation> を省略できます。<Operation> と <SupportedGrantTypes> のどちらも指定されていない場合、デフォルトの権限付与タイプは Authorization_code です。つまり authorization_code 権限付与タイプのリクエストは成功しますが、他はすべて失敗します。

プレゼンス:

省略可
型: 文字列
有効な値:
  • GenerateAccessToken - アクセス トークンを生成します。OAuth 2.0 トークンの取得もご覧ください。
  • GenerateAccessTokenImplicitGrant - 暗黙的付与タイプのアクセス トークンを生成します。OAuth 2.0 トークンの取得もご覧ください。
  • GenerateAuthorizationCode - 認証コードを生成します。認証コード権限付与タイプとともに使用します。OAuth 2.0 トークンの取得もご覧ください。
  • RefreshAccessToken - 更新トークンを新しいアクセス トークンに交換します。OAuth 2.0 トークンの取得もご覧ください。
  • VerifyAccessToken - リクエストで送信されたアクセス トークンが有効であることを検証します。上記の VerifyAccessToken サンプルとアクセス トークンの検証をご覧ください。
  • InvalidateToken - アクセス トークンを取り消します。トークンが取り消された後、クライアントはそのトークンを使用して保護された API を呼び出すことはできません。アクセス トークンの承認と取り消しもご覧ください。
  • ValidateToken - 以前取り消されたアクセス トークンを元に戻すか、承認します。アクセス トークンの承認と取り消しもご覧ください。

追加の JWT アクセス トークン オペレーション

不透明な文字列トークンの代わりに JWT アクセス トークンを使用する場合は、次の操作で JWT トークンを生成および検証できます。詳しくは、JWT OAuth トークン オペレーションの使用をご覧ください。

<PassWord> 要素

<PassWord>request.queryparam.password</PassWord>

この要素はパスワード権限付与タイプでのみ使用されます。パスワード権限付与タイプでは、ユーザー認証情報（パスワードとユーザー名）を OAuthV2 ポリシーで使用できるようにする必要があります。<PassWord> 要素と <UserName> 要素は、Apigee でこれらの値を探す変数を指定するために使用されます。これらの要素が指定されていない場合、ポリシーは username と password という名前のフォーム パラメータで値を検出することを想定しています（これがデフォルトです）。値が見つからない場合、ポリシーはエラーを返します。<PassWord> 要素と <UserName> 要素を使用して、認証情報を含むフロー変数を参照できます。

たとえば、クエリ パラメータを使用してトークン リクエストでパスワードを渡し、<PassWord>request.queryparam.password</PassWord>. のような要素を設定できます。HTTP ヘッダーでパスワードを要求するには、この値を request.header.password に設定します。

OAuthV2 ポリシーは、これらの認証情報の値を使用して他に何も行いません。Apigee では、これらの値の存在のみを検証します。API デベロッパーは、トークン生成ポリシーの実行前に値のリクエストを取得し、ID プロバイダに送信する必要があります。

OAuth 2.0 トークンの取得もご覧ください。

デフォルト:

request.formparam.password（x-www-form-urlencoded、リクエストの本文で指定）

プレゼンス:

省略可
型: 文字列
有効な値: 実行時にポリシーで使用できる任意のフロー変数。
使用する権限付与タイプ: password

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

RSA アルゴリズムで JWT 形式のアクセス トークンの検証または署名に使用する秘密鍵を提供します。ref 属性を使用して、鍵をフロー変数に渡します。Algorithm 要素の値が RS256、RS384、RS512 のいずれかの場合にのみ使用します。詳しくは、JWT OAuth トークン オペレーションの使用をご覧ください。

デフォルト 該当なし
プレゼンス Algorithm 要素の値が HS256、HS384、HS512 のいずれかの場合は必須です。
タイプ 文字列
有効な値 PEM エンコードされた RSA 秘密鍵の値を表す文字列を含むフロー変数。

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

RSA アルゴリズムで署名された JWT 形式のアクセス トークンの署名を検証するために使用される公開鍵または公開証明書を指定します。ref 属性を使用して鍵または証明書をフロー変数に渡します。Algorithm 要素の値が RS256、RS384、RS512 のいずれかの場合にのみ使用します。

デフォルト 該当なし
プレゼンス RSA アルゴリズムで署名された JWT を検証するには、証明書、JWKS、Value 要素のいずれかを使用します。
タイプ 文字列
有効な値 フロー変数または文字列

<RedirectUri> 要素

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

リクエスト内で Apigee が redirect_uri パラメータを探す場所を指定します。

リダイレクト URI について

リダイレクト URI は、認証コードと暗黙的の権限付与タイプで使用されます。リダイレクト URI により、認証コード（認証コード権限付与タイプの場合）またはアクセス トークン（暗黙的権限付与タイプの場合）を送信する場所を認証サーバー（Apigee）に伝えます。このパラメータが必須の場合と省略可能な場合を理解しておく必要があります。また使用方法も確認する必要があります。

  • （必須）リクエストのクライアント キーに関連付けられているデベロッパー アプリにコールバック URL が登録されており、かつ、redirect_uri がリクエスト内に存在する場合、この 2 つは完全に一致する必要があります。一致しない場合は、エラーが返されます。Apigee でデベロッパー アプリを登録する方法とコールバック URL の指定については、アプリの登録と API キーの管理をご覧ください。

  • （省略可）コールバック URL が登録されており、redirect_uri がリクエスト内にない場合、Apigee は登録されたコールバック URL にリダイレクトします。
  • （必須）コールバック URL が登録されていない場合、redirect_uri は必須です。この場合、Apigee は任意の URL を受け入れることに注意してください。このケースではセキュリティ上の問題が発生する可能性があるため、信頼できるクライアント アプリでのみ使用してください。信頼できるクライアント アプリでない場合は、常にコールバック URL の登録を行うことをおすすめします。

このパラメータは、クエリ パラメータやヘッダーに含めて送信できます。変数 request.queryparam.redirect_uri は、RedirectUri が ?redirect_uri=login.myapp.com などのクエリ パラメータとして存在する必要があることを示します。たとえば、HTTP ヘッダーで RedirectUri 状態を要求するには、この値を request.header.redirect_uri に設定します。OAuth 2.0 トークンの取得もご覧ください。

デフォルト:

request.formparam.redirect_uri（x-www-form-urlencoded、リクエストの本文で指定）

プレゼンス:

省略可
型: 文字列
有効な値: 実行時にポリシーでアクセスできる任意のフロー変数
使用する権限付与タイプ:
  • authorization_code
  • implicit

GenerateAuthorizationCode オペレーションでも使用します。

<RefreshToken> 要素

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

更新トークンを使用してアクセス トークンをリクエストするときは、リクエストに更新トークンを含める必要があります。この要素を使用すると、Apigee が更新トークンを検索する場所を指定できます。たとえば、クエリ パラメータ、HTTP ヘッダー、フォーム パラメータ（デフォルト）として送信できます。

変数 request.queryparam.refreshtoken は、更新トークンがクエリ パラメータ（?refresh_token=login.myapp.com など）として存在する必要があることを示します。たとえば、HTTP ヘッダーで RefreshToken を要求するには、この値を request.header.refresh_token に設定します。OAuth 2.0 トークンの取得もご覧ください。

デフォルト:

request.formparam.refresh_token（x-www-form-urlencoded、リクエストの本文で指定）

プレゼンス:

省略可
型: 文字列
有効な値: 実行時にポリシーでアクセスできる任意のフロー変数
使用する権限付与タイプ:
  • refresh_token

<RefreshTokenExpiresIn> 要素

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

更新トークンの有効期限をミリ秒単位で適用します。有効期限の値は、システムが生成した値に <RefreshTokenExpiresIn> の値を加えたものです。<RefreshTokenExpiresIn> が -1 に設定されている場合、更新トークンは OAuth 更新トークンの有効期限に従って期限切れになります。<RefreshTokenExpiresIn> が指定されていない場合は、デフォルト値が適用されます。

ハードコードされたデフォルト値を使用するか、フロー変数を参照することで、実行時に有効期限を動的に設定することもできます。たとえば、トークン有効期限値を Key-Value マップに格納し、それを取得して変数に割り当て、ポリシーで参照できます。例: kvm.oauth.expires_in

次のスタンザでは、フロー変数とデフォルト値も指定しています。フロー変数の値は、指定されたデフォルト値よりも優先される点に注意してください。

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    86400000 <!--value in milliseconds-->
</RefreshTokenExpiresIn>

デフォルト:

259,200,000 ミリ秒（30 日） （2023 年 5 月 31 日有効）

プレゼンス:

省略可
型: 整数
有効な値:
  • ゼロでない任意の正の整数。有効期限をミリ秒単位で指定します。
  • -1 は、OAuth 更新トークンの最大有効期限に従って期限切れになります。

    注: そのほかの負の整数またはゼロを指定すると、デプロイエラーが発生します。
使用する権限付与タイプ:
  • authorization_code
  • password
  • refresh_token

<ResponseType> 要素

<ResponseType>request.queryparam.response_type</ResponseType>

この要素は、クライアント アプリがどの権限付与タイプを要求しているかを Apigee に通知します。これは、認証コード付与タイプや暗黙権限付与タイプでのみ使用します。

デフォルトでは、Apigee は response_type クエリ パラメータでレスポンス タイプの値を検索します。このデフォルトの動作をオーバーライドする場合は、<ResponseType> 要素を使用してレスポンス タイプの値を含むフロー変数を構成します。たとえば、この要素を request.header.response_type に設定した場合、Apigee はリクエスト ヘッダーで渡されるレスポンス タイプを探します。OAuth 2.0 トークンの取得もご覧ください。

デフォルト:

request.formparam.response_type（x-www-form-urlencoded、リクエストの本文で指定）

プレゼンス:

省略可。この要素はデフォルトの動作をオーバーライドする場合に使用します。
型: 文字列
有効な値: code（認証コード権限付与タイプ）または token（暗黙的権限付与タイプ）
使用する権限付与タイプ:
  • implicit
  • GenerateAuthorizationCode オペレーションでも使用します。

<ReuseRefreshToken> 要素

<ReuseRefreshToken>true</ReuseRefreshToken>

true に設定すると、既存の更新トークンは期限切れになるまで再利用されます。false の場合、有効な更新トークンが提示されると、Apigee によって新しい更新トークンが発行されます。

デフォルト:

false

プレゼンス:

任意
型: ブール値
有効な値:

true または false
併用する権限付与タイプ:
  • refresh_token

<RFCCompliantRequestResponse> 要素

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

true の場合、ポリシーは RFC6749 標準に準拠し、次のような準拠動作を有効にします。

  • エラーおよびエラー以外のレスポンスには、RFC2616（Hypertext Transfer Protocol-HTTP / 1.1）に準拠するために HTTP Cache-Control レスポンス ヘッダー フィールドが含まれます。同様に、トークン、クレデンシャル、またはその他の機密情報を含むレスポンスには no-store の値が、Pragma レスポンス ヘッダー フィールドには no-cache の値が含まれます。
  • expires_in プロパティは英数字の形式になります。整合性を維持するため、refresh_token_expires_in も英数字になります。
  • トークン生成の OAuthV2 レスポンスには、BearerToken ではなく RFC 準拠の Bearer ヘッダー フィールドが含まれます。
  • 更新トークンエラーの場合、レスポンス ペイロードのエラー メッセージは {"error" : "xxx", "error_description" :"yyy"} 形式になります。

デフォルト:

false: デフォルトでは、このポリシーは RFC に準拠していない特定の動作を許可します。詳しくは、RFC に準拠していない動作をご覧ください。RFC 準拠を有効にするには、この要素を true に設定します。

プレゼンス:

省略可
型: ブール値
有効な値: true または false
使用する権限付与タイプ: すべて

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

JWT 形式のアクセス トークンを HMAC アルゴリズムで検証または署名するために使用される秘密鍵を提供します。アルゴリズムが HS256、HS384、HS512 のいずれかである場合にのみ使用します。ref 属性を使用して、鍵をフロー変数に渡します。詳しくは、JWT OAuth トークン オペレーションの使用をご覧ください。

Apigee は、HS256 / HS384 / HS512 アルゴリズムに対して最小限の鍵強度を適用します。鍵の最小長は、HS256 では 32 バイト、HS384 では 48 バイト、HS512 では 64 バイトです。強度の低い鍵を使用すると実行時エラーが発生します。

デフォルト 該当なし
プレゼンス HMAC アルゴリズムでは必須。
タイプ 文字列
有効な値 フロー変数

<Scope> 要素

<Scope>request.queryparam.scope</Scope>

この要素が GenerateAccessToken ポリシーか GenerateAuthorizationCode ポリシーのいずれかに存在する場合、トークンやコード権限を付与するスコープを指定するために使用されます。これらの値は通常、クライアント アプリからのリクエストでポリシーに渡されます。この要素がフロー変数を使用するように構成して、リクエストでスコープを渡す方法を選択できます。次の request.queryparam.scope は、スコープがクエリ パラメータとして存在する必要があることを示します（例: ?scope=READ）。たとえば、HTTP ヘッダーでスコープを要求するには、この値を request.header.scope に設定します。

この要素が「VerifyAccessToken」ポリシー内にある場合、これは、ポリシーが適用するスコープを指定するために使用されています。このタイプのポリシーでは、値は「ハードコードされた」スコープ名である必要があります。変数は使用できません。次に例を示します。

<Scope>A B</Scope>

OAuth2 スコープの使用と OAuth 2.0 トークンの取得もご覧ください。

デフォルト:

スコープなし

プレゼンス:

省略可
型: 文字列
有効な値:

Generate* ポリシーで使用する場合はフロー変数。

VerifyAccessToken で使用する場合はスコープ名（文字列）のスペース区切りのリスト。
使用する権限付与タイプ:
  • authorization_code
  • implicit
  • password
  • client_credentials
  • GenerateAuthorizationCode オペレーションと VerifyAccessToken オペレーションでも使用できます。

<State> 要素

<State>request.queryparam.state</State>

クライアント アプリから認可サーバーに状態情報を送信する必要がある場合、この要素を使用すると、状態値をどこで探すかを Apigee に指示できます。たとえば、クエリ パラメータとして、または HTTP ヘッダーで送信できます。状態値は通常、CSRF 攻撃を防ぐセキュリティ対策として使用されます。

たとえば、request.queryparam.state は状態がクエリ パラメータとして存在する必要があることを示します（例: ?state=HjoiuKJH32）。たとえば、HTTP ヘッダーで状態を要求するには、この値を request.header.state に設定します。OAuth 2.0 トークンの取得もご覧ください。

デフォルト:

状態なし

プレゼンス:

省略可
型: 文字列
有効な値: 実行時にポリシーにアクセスできる任意のフロー変数
使用する権限付与タイプ:
  • すべて
  • GenerateAuthorizationCode オペレーションでも使用できます

<StoreToken> 要素

 <StoreToken>true</StoreToken>

<ExternalAuthorization> 要素が true の場合、この要素を true に設定します。<StoreToken> 要素は、外部アクセス トークンを保存するように Apigee に指示します。それ以外の場合、外部アクセス トークンは維持されません。

デフォルト:

false

プレゼンス:

省略可
型: ブール値
有効な値: true または false
使用する権限付与タイプ:
  • authorization_code
  • password
  • client_credentials

<SupportedGrantTypes> / <GrantType> 要素

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Apigee の OAuth トークン エンドポイントでサポートされる権限付与タイプを指定します。1 つのエンドポイントで、複数の権限付与タイプがサポートされます（つまり、複数の権限付与タイプのアクセス トークンを配布するように、1 つのエンドポイントを構成できます）。エンドポイントの詳細については、OAuth エンドポイントについてをご覧ください。権限付与タイプは、grant_type パラメータのトークン リクエストで渡されます。

サポートされている権限付与タイプが指定されていない場合、許可される権限タイプは authorization_code と implicit のみです。<GrantType> 要素もご覧ください（これは、渡される grant_type パラメータをクライアント リクエストのどこで探すかを Apigee に指示するために使用する上位要素です。Apigee は、サポートされている権限付与タイプの 1 つと grant_type パラメータの値が一致することを確認します）。

デフォルト:

authorization _code と implicit

プレゼンス:

必須
型: 文字列
有効な値:
  • client_credentials
  • authorization_code
  • password
  • implicit

<Tokens> / <Token> 要素

ValidateToken オペレーションと InvalidateToken オペレーションで使用します。アクセス トークンの承認と取り消しもご覧ください。<Token> 要素によって、取り消すトークンがどこに含まれているかを定義するフロー変数を識別します。たとえば、access_token という名前のクエリ パラメータとしてアクセス トークンを送信する必要がある場合は、request.queryparam.access_token を使用します。

<UserName> 要素

<UserName>request.queryparam.user_name</UserName>

この要素はパスワード権限付与タイプでのみ使用されます。パスワード権限付与タイプでは、ユーザー認証情報（パスワードとユーザー名）を OAuthV2 ポリシーで使用できるようにする必要があります。<PassWord> 要素と <UserName> 要素は、Apigee でこれらの値を探す変数を指定するために使用されます。これらの要素が指定されていない場合、ポリシーは username と password という名前のフォーム パラメータで値を検出することを想定しています（これがデフォルトです）。値が見つからない場合、ポリシーはエラーを返します。<PassWord> 要素と <UserName> 要素を使用して、認証情報を含むフロー変数を参照できます。

たとえば、クエリ パラメータでユーザー名を渡し、次のように <UserName> 要素を <UserName>request.queryparam.username</UserName>. に設定できます。HTTP ヘッダーでユーザー名を要求するには、この値を request.header.username に設定します。

OAuthV2 ポリシーは、これらの認証情報の値を使用して他に何も行いません。Apigee では、これらの値の存在のみを検証します。API デベロッパーは、トークン生成ポリシーの実行前に値のリクエストを取得し、ID プロバイダに送信する必要があります。

OAuth 2.0 トークンの取得もご覧ください。

デフォルト:

request.formparam.username（x-www-form-urlencoded、リクエストの本文で指定）

プレゼンス:

省略可
型: 文字列
有効な値: 任意の変数設定。
使用する権限付与タイプ: password

アクセス トークンの検証

API プロキシにトークン エンドポイントが設定されると、対応する OAuthV2 ポリシー（VerifyAccessToken オペレーションを指定）が、保護されたリソースを公開するフローに追加されます。

たとえば、API へのリクエストがすべて認証されるようにするには、次のポリシーでアクセス トークンの検証を行います。

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

保護されている API リソースにこのポリシーが接続されます。API へのリクエストがすべての検証されるようにするには、このポリシーを次のように ProxyEndpoint リクエストの PreFlow に接続します。

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

次の省略可能な要素を使用すると、VerifyAccessToken オペレーションのデフォルト設定をオーバーライドできます。

名前 説明
スコープ

スペース区切りのスコープのリスト。リストされたスコープの少なくとも 1 つがアクセス トークン内に存在する場合、検証が成功します。たとえば、次のポリシーでは、アクセス トークンに少なくとも 1 つのスコープが含まれていることを確認しています。READ または WRITE が存在する場合、検証は成功します。


<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>
AccessToken アクセス トークンが格納されていると想定される変数。例: request.queryparam.accesstokenデフォルトでは、アクセス トークンは OAuth 2.0 仕様に従って、アプリによって Authorization HTTP ヘッダーに提示されます。この設定は、アクセス トークンがクエリ パラメータのような標準的でない場所で使用するか、Authorization 以外の名前を持つ HTTP ヘッダーで提示されることが想定される場合に使用します。

アクセス トークンの検証と OAuth 2.0 トークンの取得もご覧ください。

リクエスト変数の場所の指定

ポリシーは、権限付与タイプごとに、リクエスト メッセージ内の場所や必要な情報を推測します。この推測は、OAuth 2.0 仕様に基づいています。アプリが OAuth 2.0 仕様から外れる必要がある場合は、各パラメータについて想定される場所を指定できます。たとえば、認証コードを処理するときに、認証コードの場所、クライアント ID、リダイレクト URI、スコープを指定できます。これらは、HTTP ヘッダー、クエリ パラメータ、またはフォーム パラメータとして指定できます。

次の例では、必要な認証コード パラメータの場所を HTTP ヘッダーとして指定する方法を示しています。

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

また、クライアント アプリ ベースをサポートする必要がある場合、ヘッダーとクエリ パラメータを組み合わせ、一致させることもできます。

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

パラメータごとに構成できる場所は 1 つのみです。

フロー変数

この表で定義されたフロー変数は、それぞれの OAuth ポリシーが実行されるときに設定されます。したがって、API プロキシフローで実行されている他のポリシーやアプリケーションで使用できます。

VerifyAccessToken オペレーション

VerifyAccessToken オペレーションが実行されると、多くのフロー変数がプロキシの実行コンテキストに設定されます。これらの変数は、アクセス トークン、デベロッパー アプリ、デベロッパーに関連するプロパティを提供します。AssignMessage ポリシーや JavaScript ポリシーなどを使用してこれらの変数を読み取り、必要に応じて後続のフローで使用できます。これらの変数はデバッグにも役立ちます。

トークン固有の変数

変数 説明
organization_name プロキシが実行されている組織の名前。
developer.id 登録されたクライアント アプリに関連付けられているデベロッパーと AppGroup のいずれかの ID。
developer.app.name 登録されたクライアント アプリに関連付けられているデベロッパーまたは AppGroup アプリの名前。
client_id 登録されたクライアント アプリのクライアント ID。
grant_type リクエストに関連付けられている権限付与タイプ。VerifyJWTAccessToken 操作ではサポートされていません。
token_type リクエストに関連付けられているトークンタイプ。
access_token 検証中のアクセス トークン。
accesstoken.{custom_attribute} アクセス トークンの名前付きカスタム属性。
issued_at Unix エポックタイム（ミリ秒単位）で表されたアクセス トークンの発行日付。
expires_in アクセス トークンの有効期限。秒単位で表されます。ExpiresIn 要素の有効期限はミリ秒単位で設定されますが、トークンのレスポンスとフロー変数では、値が秒単位で表されます。
status アクセス トークンのステータス（approved や revoked など）。
scope アクセス トークンに関連付けられているスコープ（存在する場合）。
apiproduct.<custom_attribute_name> 登録されたクライアント アプリに関連付けられている API プロダクトの名前付きカスタム属性。
apiproduct.name 登録されたクライアント アプリに関連付けられている API プロダクトの名前。
revoke_reason

（Apigee ハイブリッドのみ）アクセス トークンが取り消される理由を示します。VerifyJWTAccessToken 操作ではサポートされていません。

値は、REVOKED_BY_APP、REVOKED_BY_ENDUSER、REVOKED_BY_APP_ENDUSER、TOKEN_REVOKED に指定できます。

アプリ固有の変数

これらの変数は、トークンに関連付けられているデベロッパー アプリに関連します。

変数 説明
app.name
app.id
app.accessType
app.callbackUrl
app.status approved または revoked
app.scopes
app.appFamily
app.apiproducts
app.appParentStatus
app.appType 例: Developer
app.appParentId
app.created_by
app.created_at
app.last_modified_at
app.last_modified_by
app.{custom_attributes} 登録されたクライアント アプリの名前付きカスタム属性。

AppGroup 固有の変数

トークンの AppGroup に関する情報を含む次のフロー変数は、ポリシーによって設定されます。これらの AppGroup 属性は、verifyapikey.{policy_name}.app.appType が「AppGroup」の場合にのみ入力されます。

変数 説明
appgroup.displayName AppGroup の表示名。
appgroup.name AppGroup の名前。
appgroup.id AppGroup ID。
appOwnerStatus アプリのオーナーのステータス（「active」、「inactive」、「login_lock」）。
created_at AppGroup 作成時の日付 / 時刻スタンプ。
created_by AppGroup を作成したデベロッパーのメールアドレス。
last_modified_at AppGroup が最後に変更された日付 / 時刻スタンプ。
last_modified_by AppGroup を最後に変更したデベロッパーのメールアドレス。
{appgroup_custom_attributes} 任意のカスタム AppGroup 属性。カスタム属性の名前を指定します。

デベロッパー固有の変数

app.appType が「Developer」である場合、デベロッパー属性が事前入力されます。

変数 説明
デベロッパー固有の変数
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status active または inactive
developer.apps
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes} デベロッパーの名前付きカスタム属性。

GenerateAuthorizationCode オペレーション

これらの変数は、GenerateAuthorizationCode オペレーションが正常に実行されたときに設定されます。

接頭辞: oauthv2authcode.{policy_name}.{variable_name}

例: oauthv2authcode.GenerateCodePolicy.code

変数 説明
code ポリシーが実行されるときに生成される認証コード。
redirect_uri 登録されたクライアント アプリに関連付けられているリダイレクト URI。
scope クライアント リクエストで渡される省略可能な OAuth スコープ。
client_id クライアント リクエストで渡されるクライアント ID。

GenerateAccessToken オペレーションと RefreshAccessToken オペレーション

これらの変数は、GenerateAccessToken オペレーションと RefreshAccessToken オペレーションが正常に実行されたときに設定されます。更新トークン変数は、クライアント認証情報の権限付与タイプのフローには適用されません。

接頭辞: oauthv2accesstoken.{policy_name}.{variable_name}

例: oauthv2accesstoken.GenerateTokenPolicy.access_token

変数名 説明
access_token 生成されたアクセス トークン。
client_id このトークンに関連付けられているデベロッパー アプリのクライアント ID。
expires_in トークンの有効期限の値。詳細については、<ExpiresIn> 要素をご覧ください。レスポンスで、expires_in は秒単位で表されます。
scope トークン用に構成された、使用可能なスコープのリスト。OAuth2 スコープの操作をご覧ください。
status approved または revoked のいずれか。
token_type BearerToken に設定されています。
developer.email トークンに関連付けられているデベロッパー アプリを所有する、登録済みのデベロッパーのメールアドレス。
organization_name プロキシが実行される組織。
api_product_list トークンに対応するデベロッパー アプリに関連付けられているプロダクトのリスト。
refresh_count
refresh_token 生成された更新トークン。権限付与タイプがクライアント認証情報の場合、更新トークンは生成されない点に注意してください。
refresh_token_expires_in 更新トークンの有効期間（秒単位）。
refresh_token_issued_at この時間値は、対応する 32 ビット タイムスタンプの数値の文字列表現です。たとえば、「Wed, 21 Aug 2013 19:16:47 UTC」はタイムスタンプ値 1377112607413 に相当します。
refresh_token_status approved または revoked のいずれか。

GenerateAccessTokenImplicitGrant

これらの変数は、GenerateAccessTokenImplicit オペレーションが暗黙権限付与タイプのフローに対して正常に実行されたときに設定されます。

接頭辞: oauthv2accesstoken.{policy_name}.{variable_name}

例: oauthv2accesstoken.RefreshTokenPolicy.access_token

変数 説明
oauthv2accesstoken.access_token ポリシーが実行されるときに生成されるアクセス トークン。
oauthv2accesstoken.{policy_name}.expires_in トークンの有効期限（秒単位）。詳細については、<ExpiresIn> 要素をご覧ください。

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因 オペレーションによるスロー
steps.oauth.v2.access_token_expired 401 アクセス トークンの期限が切れています。

VerifyAccessToken
InvalidateToken
steps.oauth.v2.access_token_not_approved 401 アクセス トークンは取り消されています。 VerifyAccessToken
steps.oauth.v2.apiresource_doesnot_exist 401 リクエストされたリソースが、アクセス トークンに関連付けられた API プロダクトに存在していません。 VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken 500 ポリシーでは、<AccessToken> 要素で指定された変数にアクセス トークンがあることを想定していますが、この変数を解決できませんでした。 GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode 500 ポリシーでは、<Code> 要素で指定された変数に認証コードがあることを想定していますが、この変数を解決できませんでした。 GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId 500 ポリシーでは、<ClientId> 要素で指定された変数にクライアント ID があることを想定していますが、この変数を解決できませんでした。 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken 500 ポリシーでは、<RefreshToken> 要素で指定された変数に更新トークンがあることを想定していますが、この変数を解決できませんでした。 RefreshAccessToken
steps.oauth.v2.FailedToResolveToken 500 ポリシーでは、<Tokens> 要素で指定された変数にトークンがあることを想定していますが、この変数を解決できませんでした。

ValidateToken
InvalidateToken
steps.oauth.v2.InsufficientScope 403 リクエストで提供されたアクセス トークンのスコープが、アクセス トークン検証ポリシーに指定されているスコープと一致しません。スコープの詳細については、OAuth2 スコープの操作をご覧ください。 VerifyAccessToken
steps.oauth.v2.invalid_access_token 401 クライアントから送信されたアクセス トークンが無効です。 VerifyAccessToken
steps.oauth.v2.invalid_client 401

このエラー名は、ポリシーの <GenerateResponse> プロパティが true に設定され、リクエストで送信されたクライアント ID が無効な場合に返されます。使用しているプロキシに関連付けられたデベロッパー アプリに正しいクライアント キーとシークレットの値を使用していることを確認してください。通常、これらの値は Base64 エンコードの Basic Authorization ヘッダーとして送信されます。

 GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.invalid_request 400 このエラー名は、複数の異なる種類のエラーに使用されます。通常は、リクエストで送信されたパラメータが欠落しているか、正しくない場合に使用されます。<GenerateResponse> が false に設定されている場合、後述の障害変数を使用してエラーの詳細（障害名、原因など）を取得してください。 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 認証ヘッダーに必須の単語 Bearer がありません。例: Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNo\
ApiProductMatchFound		 401

現在実行中の API プロキシまたはオペレーションが、アクセス トークンに関連付けられたプロダクト内にありません。

ヒント: アクセス トークンに関連付けられたプロダクトが適切に構成されていることを確認してください。たとえば、リソースパスでワイルドカードを使用する場合は、ワイルドカードが正確に使用されていることを確認します。詳しくは、API プロダクトの管理をご覧ください。

このエラーの原因について詳しくは、Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error もご覧ください。

 VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

このエラー名は、ポリシーの <GenerateResponse> プロパティが false に設定され、リクエストで送信されたクライアント ID が無効な場合に返されます。使用しているプロキシに関連付けられたデベロッパー アプリに正しいクライアント キーとシークレットの値を使用していることを確認してください。通常、これらの値は Base64 エンコードの Basic Authorization ヘッダーとして送信されます。

GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidParameter 500 ポリシーでは、アクセス トークンまたは認証コードのいずれかを指定する必要があります。両方は指定できません。 GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType 500 <Tokens>/<Token> 要素でトークンタイプ（たとえば refreshtoken）を指定する必要があります。クライアントが誤ったタイプを渡すと、このエラーがスローされます。 ValidateToken
InvalidateToken
steps.oauth.v2.MissingParameter 500 レスポンス タイプが token ですが、権限付与タイプが指定されていません。 GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType 500

クライアントで指定された権限付与タイプが、ポリシーでサポートされていません（<SupportedGrantTypes> 要素のリストにありません）。

 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

JWT トークン固有のランタイム エラー

JWT 認証トークンのランタイム エラーコードと説明は、OAuth2 フローのコンテキストによって異なります。

JWT トークンの生成フローと更新フローのエラーコード

JWT トークンを生成または更新する OAuth2 フローの場合、エラー レスポンスは RFC6749 で指定されているエラー レスポンスに従います。詳しくは、セクション 5.2 エラー レスポンスをご覧ください。

トークン検証フローのエラーコード

次の表に示すエラーコードは、VerifyAccessToken オペレーションにのみ適用されます。

障害コード HTTP ステータス 原因 オペレーションによるスロー
oauth.v2.JWTSigningFailed 401 ポリシーで JWT に署名を設定できなかった場合。

GenerateJWTAccessToken
oauth.v2.InvalidValueForJWTAlgorithm 401 これは、JWT アクセス トークンにアルゴリズムが存在しない場合、または値がサポートされていない場合に発生します。

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.InsufficientKeyLength 401 JWT の生成では、HS384 または HS512 アルゴリズムの鍵が最小サイズよりも小さい場合。

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.JWTAlgorithmMismatch 401 Generate ポリシーで指定されたアルゴリズムが、Verify ポリシーで想定されているアルゴリズムと一致しない場合。指定されたアルゴリズムが一致している必要があります。

VerifyJWTAccessToken
oauth.v2.JWTDecodingFailed 401 ポリシーで JWT をデコードできなかった場合。JWT が破損している可能性があります。

VerifyJWTAccessToken
oauth.v2.MissingMandatoryClaimsInJWT 401 Jwt アクセス トークンに必要なクレームがない場合。

VerifyJWTAccessToken
oauth.v2.InvalidJWTSignature 401 これは、JWT アクセス トークンの署名が検証できなかったか、署名が無効である場合に発生します。

VerifyJWTAccessToken
oauth.v2.InvalidTypeInJWTHeader 401 JWT の型が at+Jwt でない場合に発生します。

VerifyJWTAccessToken

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名 原因
InvalidValueForExpiresIn

<ExpiresIn> 要素の場合、有効な値は正の整数と -1 です。
InvalidValueForRefreshTokenExpiresIn <RefreshTokenExpiresIn> 要素の場合、有効な値は正の整数と -1 です。
InvalidGrantType <SupportedGrantTypes> 要素に無効な権限付与タイプが指定されています。有効な付与タイプのリストについては、ポリシー リファレンスをご覧ください。
ExpiresInNotApplicableForOperation <Operations> 要素に指定されたオペレーションで有効期限がサポートされていることを確認してください。たとえば、VerifyToken オペレーションでは有効期限はサポートされません。
RefreshTokenExpiresInNotApplicableForOperation <Operations> 要素に指定されたオペレーションで、更新トークンの有効期限がサポートされていることを確認してください。たとえば、VerifyToken オペレーションではサポートされていません。
GrantTypesNotApplicableForOperation <SupportedGrantTypes> に指定された付与タイプが、指定したオペレーションでサポートされていることを確認してください。
OperationRequired

<Operation> 要素を使用して、このポリシーのオペレーションを指定する必要があります。
InvalidOperation

<Operation> 要素を使用して、このポリシーで有効なオペレーションを指定する必要があります。
TokenValueRequired <Tokens> 要素にトークン <Token> 値を指定する必要があります。

JWT トークン固有のデプロイエラー

このデプロイエラーは、JWT トークン オペレーションを使用するポリシーに固有のエラーです。

エラー名 原因
InvalidValueForAlgorithm <Algorithm> 要素で指定されたアルゴリズムが、使用可能なアルゴリズムのリストに含まれていないか、存在しません。
MissingKeyConfiguration 必須の <SecretKey>、<PrivateKey>、<PublicKey> 要素がありません（どの要素がないかは、使用するアルゴリズムによって異なります）。
EmptyValueElementForKeyConfiguration 必須の子要素 <Value> が <PrivateKey>、<PublicKey>、または <SecretKey> 要素で定義されていません。
InvalidKeyConfiguration <PrivateKey> 要素が RSA ファミリー アルゴリズムで使用されていないか、<SecretKey> 要素が HS ファミリー アルゴリズムで使用されていません。
EmptyRefAttributeForKeyconfiguration <PrivateKey>、<PublicKey>、または <SecretKey> 要素の子要素 <Value> の ref 属性が空です。
InvalidVariableNameForKey <PrivateKey>、<PublicKey>、または <SecretKey> 要素の子要素 <Value> の ref 属性で指定されたフロー変数名に、private 接頭辞がありません。

障害変数

次の変数は、このポリシーでランタイム エラーが発生したときに設定されます。

変数 説明 例
fault.name="fault_name" fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 fault.name = "invalid_request"
oauthV2.policy_name.failed policy_name は、障害が発生したポリシーのユーザー指定の名前です。 oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name policy_name は、障害が発生したポリシーのユーザー指定の名前です。 oauthV2.GenerateAccesstoken.fault.name = invalid_request
oauthV2.policy_name.fault.cause policy_name は、障害が発生したポリシーのユーザー指定の名前です。 oauthV2.GenerateAccesstoken.cause = Required param : grant_type

エラー レスポンスの例

<GenerateResponse> 要素が true の場合、これらのレスポンスがクライアントに返されます。

<GenerateResponse> が true の場合、ポリシーはトークンとコードを生成するオペレーションに対して、次の形式のエラーを返します。一覧については、OAuth HTTP エラー レスポンス リファレンスをご覧ください。

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

<GenerateResponse> が true の場合、ポリシーは確認と検証のオペレーションに対して、次の形式のエラーを返します。一覧については、OAuth HTTP エラー レスポンス リファレンスをご覧ください。

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

障害ルールの例

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

ストレージ内のトークンのハッシュ化

Apigee ハイブリッドまたは Apigee X を使用している場合、デフォルトでは、OAuthV2 アクセス トークンと更新トークンがランタイム Cassandra データベースに保存されるときにハッシュ化されます。ハッシュ化により、データベースが不正使用されたときにトークンの使用を防ぐことができます。

デフォルトの OAuth 構成の操作

Apigee における各組織（無料トライアル版の組織を含む）は、OAuth トークン エンドポイント付きでプロビジョニングされています。エンドポイントは、oauth という API プロキシのポリシーを使用して事前構成されています。Apigee でアカウントを作成するとすぐに、トークン エンドポイントの使用を開始できます。詳しくは、OAuth エンドポイントについてをご覧ください。

アクセス トークンのパージ

デフォルトでは、OAuth2 トークンは、アクセス トークンと更新トークン（存在する場合）の両方が期限切れになった 3 日（259,200 秒）後に Apigee システムからパージされます。

RFC を遵守していない動作

デフォルトでは、OAuthV2 ポリシーは GenerateAccessToken オペレーションで、トークンのレスポンスを返します。レスポンスには、RFC 準拠ではない特定のプロパティが含まれます。次の表に、OAuthV2 ポリシーによって返される非準拠プロパティと、対応する準拠プロパティを示します。

OAuthV2 は以下を返します。 RFC 準拠のプロパティ:
"token_type":"BearerToken" "token_type":"Bearer"
"expires_in":"3600" "expires_in":3600

（準拠する値は文字列ではなく数値です）

また、grant_type = refresh_token が以下の場合、期限切れの更新トークンのエラー レスポンスは次のとおりです。

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

ただし、RFC 準拠のレスポンスは次のとおりです。

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

関連トピック