OAuthV2 ポリシー

概要

OAuthV2 は、OAuth 2.0 権限付与タイプ オペレーション向けのマルチファセット ポリシーです。これは Apigee Edge で OAuth 2.0 エンドポイントを構成するための主要なポリシーです。

ヒント: Apigee Edge での OAuth の詳細については、OAuth ホームページをご覧ください。リソース、サンプル、動画などへのリンクを提供します。このポリシーが実際のアプリケーションで使用される様子を示すわかりやすいデモについては、GitHub の高度な OAuth サンプルをご覧ください。

サンプル

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

<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>

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

Basic 認証情報をエンコードするもご覧ください。

要素リファレンス

このポリシー リファレンスでは、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">

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

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

<DisplayName>Policy Display Name</DisplayName>

<AccessToken> 要素

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

デフォルトでは、VerifyAccessToken はアクセス トークンが Authorization ヘッダーで送信されることを想定しています。この要素を使用すると、デフォルトを変更できます。たとえば、request.queryparam.access_token はアクセス トークンが access_token という名前のクエリ パラメータとして存在する必要があることを示します。

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

<AccessTokenPrefix> 要素

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

デフォルトで、VerifyAccessToken は、アクセス トークンが Authorization ヘッダーでベアラー トークンとして送信されることを想定しています。例:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

現時点で、サポートされている接頭辞は Bearer のみです。

<AppEndUser> 要素

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

アプリ エンドユーザー ID を認可サーバーに送信する必要がある場合、この要素を使用すると、エンドユーザー ID をどこで探すかを Edge に指示できます。この 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 アクセス トークンの取得と取り消しを可能にするをご覧ください。

<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 またはセッション識別子をアクセス トークンに埋め込む場合などです。

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

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

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

このポリシーの 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 を設定すると、その目標を達成できます。しかし、リフレッシュ トークンを使用して後から新しいアクセス トークンを生成すると、アクセス トークンの元のカスタム属性がリフレッシュ トークンのレスポンスで表示されます。これは、Edge がアクセス トークンの生成ポリシーで display 属性が最初に false に設定されたことを覚えていないためです。カスタム属性は単にアクセス トークンのメタデータの一部です。

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

このような場合にカスタム属性を非表示にする選択肢は、次のとおりです。

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

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

<ClientId> 要素

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

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

<Code> 要素

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

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

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

<ExpiresIn> 要素

<ExpiresIn>10000</ExpiresIn>

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

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

Apigee Edge for Public Cloud を使用すると、次に示すエンティティにアクセスした場合、Edge はアクセスしたエンティティを少なくとも 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>

Edge では、トークンの作成後にトークンの有効期限を強制する方法をサポートしていません。トークンの期限切れを（たとえば条件に基づいて）強制する必要がある場合、こちらの Apigee コミュニティの記事で可能な解決策を紹介していますのでご覧ください。

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

Private Cloud: Edge for Private Cloud インストール済み環境の場合、デフォルト値は conf_keymanagement_oauth_auth_code_expiry_time_in_millis プロパティによって設定されます。このプロパティを設定するには:

1. message-processor.properties ファイルをエディタで開きます。ファイルが存在しない場合は作成します。

   vi /opt/apigee/customer/application/message-processor.properties

2. 必要なプロパティを設定します。

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. プロパティ ファイルの所有者を「apigee」ユーザーにします。

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Message Processor を再起動します。

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

<ExternalAccessToken> 要素

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

外部アクセス トークン（Apigee Edge で生成しないアクセス トークン）をどこで探すかを Apigee Edge に指示します。

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

<ExternalAuthorization> 要素

<ExternalAuthorization>true</ExternalAuthorization>

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

<ExternalAuthorizationCode> 要素

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

外部認可コード（Apigee Edge で生成しない認可コード）をどこで探すかを Apigee Edge に指示します。

変数 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 Edge で生成しないリフレッシュ トークン）をどこで探すかを Apigee Edge に指示します。

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

<GenerateResponse> 要素

<GenerateResponse enabled='true'/>

true に設定すると、ポリシーはレスポンスを生成して返します。たとえば 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 の場合、レスポンスは送信されません。代わりに、ポリシーの機能に関連する値が一連のフロー変数に代入されます。たとえば oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code というフロー変数に、新たに作成され認可コードが代入されます。レスポンスで expires_in は秒単位で表現されます。

<GenerateErrorResponse> 要素

<GenerateErrorResponse enabled='true'/>

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

<GrantType>

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

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

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

<Operation> 要素

<Operation>GenerateAuthorizationCode</Operation>

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

<PassWord> 要素

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

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

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

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

アクセス トークンと認可コードのリクエストもご覧ください。

<RedirectUri> 要素

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

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

リダイレクト URI について

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

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

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

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

<RefreshToken> 要素

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

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

変数 request.queryparam.refreshtoken は、リフレッシュ トークンがクエリ パラメータとして存在する必要があることを示します（例: ?refresh_token=login.myapp.com）。たとえば、HTTP ヘッダーで RefreshToken を要求するには、この値を request.header.refresh_token に設定します。アクセス トークンと認可コードのリクエストもご覧ください。

<RefreshTokenExpiresIn> 要素

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

リフレッシュ トークンの有効期限を、ミリ秒単位で適用します。有効期限の値は、システムが生成した値に <RefreshTokenExpiresIn> の値を加えたものです。<RefreshTokenExpiresIn> が -1 に設定されている場合、リフレッシュ トークンには無期限の有効期限が設定されます。<RefreshTokenExpiresIn> を指定しない場合、システムレベルで構成されたデフォルト値がシステムによって適用されます。デフォルトのシステム設定の詳細については、Apigee サポートにお問い合わせください。

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

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

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

Private Cloud: Edge for Private Cloud インストール済み環境の場合、デフォルト値は conf_keymanagement_oauth_refresh_token_expiry_time_in_millis プロパティによって設定されます。このプロパティを設定するには:

1. message-processor.properties ファイルをエディタで開きます。ファイルが存在しない場合は作成します。

   vi /opt/apigee/customer/application/message-processor.properties

2. 必要なプロパティを設定します。

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. プロパティ ファイルの所有者を「apigee」ユーザーにします。

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Message Processor を再起動します。

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

<ResponseType> 要素

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

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

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

<ReuseRefreshToken> 要素

<ReuseRefreshToken>true</ReuseRefreshToken>

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

<Scope> 要素

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

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

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

<Scope>A B</Scope>

OAuth2 スコープの操作とアクセス トークンと認可コードのリクエストもご覧ください。

<State> 要素

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

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

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

<StoreToken> 要素

 <StoreToken>true</StoreToken>

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

<SupportedGrantTypes> / <GrantType> 要素

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

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

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

<Tokens> / <Token> 要素

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

<UserName> 要素

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

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

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

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

アクセス トークンと認可コードのリクエストもご覧ください。

アクセス トークンの検証

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

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

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

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

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

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

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

アクセス トークンの検証とアクセス トークンと認可コードのリクエストもご覧ください。

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

ポリシーは、権限付与タイプごとに、リクエスト メッセージ内の場所や必要な情報を推測します。この推測は、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 ポリシーなどを使用してこれらの変数を読み取り、必要に応じて後続のフローで使用できます。これらの変数は、デバッグの目的にも役立ちます。

トークン固有の変数

アプリ固有の変数

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

デベロッパー固有の変数

app.appType が「Company」の場合カンパニー属性が設定され、app.appType が「Developer」の場合デベロッパー属性が設定されます。

カンパニー固有の変数

app.appType が「Company」の場合カンパニー属性が設定され、app.appType が「Developer」の場合デベロッパー属性が設定されます。

GenerateAuthorizationCode オペレーション

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

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

例: oauthv2authcode.GenerateCodePolicy.code

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

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

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

例: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

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

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

例: oauthv2accesstoken.RefreshTokenPolicy.access_token

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime.

Example error response

These responses are sent back to the client if the <GenerateResponse> element is true.

If <GenerateResponse> is true, the policy returns errors in this format for operations that generate tokens and codes. For a complete list, see see OAuth HTTP error response reference.

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

If <GenerateResponse> is true, the policy returns errors in this format for verify and validate operations. For a complete list, see see OAuth HTTP error response reference.

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

Example fault rule

<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>

ポリシー スキーマ

各ポリシータイプは XML スキーマ（.xsd）によって定義されます。ポリシー スキーマは GitHub から入手できます。

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

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

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

デフォルトでは、OAuth2 トークンは、アクセス トークンとリフレッシュ トークン（存在する場合）の両方が期限切れになった 3 日（259,200 秒）後に Apigee Edge システムからパージされます。場合によっては、このデフォルトを変更できます。たとえば、多数のトークンが生成されている場合に、パージ時間を短くしてディスク領域を節約できます。

Edge for Private Cloud を使用している場合は、このセクションで説明するように組織プロパティを設定することによって、このデフォルトを変更できます（期限切れのトークンの 3 日後のパージは、Edge for Private Cloud バージョン 4.19.01 以降に適用されます。それ以前のバージョンでは、デフォルトのパージ間隔は 180 日です）。

Edge for Private Cloud 4.16.01 以降のバージョンでのパージ設定の更新

注: これらの設定が適用された後に生成されるトークンのみが影響を受けます。この設定は、以前に生成されたトークンには適用されません。

Edge Private Cloud 4.15.07 でのパージ設定の更新

注: これらの設定が適用された後に生成されるトークンのみが影響を受けます。この設定は、以前に生成されたトークンには適用されません。

RFC に準拠していない動作

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

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

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

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

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

関連トピック

• OAuth 2.0 の概要