OAuthV2 ポリシー

概要

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

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

サンプル

VerifyAccessToken

VerifyAccessToken

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

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

注: OAuth 2.0 署名なしトークンのみがサポートされます。メッセージ認証コード(MAC)トークンはサポートされません。

例:

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

デフォルトでは、Edge は Bearer 接頭辞がある Authorization ヘッダー内のアクセス トークンを受け入れます。このデフォルトは、<AccessToken> 要素で変更できます。

GenerateAccessToken

アクセス トークンの生成

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

GenerateAuthorizationCode

認可コードの生成

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

RefreshAccessToken

アクセス トークンの更新

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

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

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

レスポンス フローでアクセス トークンを生成する必要が生じることがあります。たとえば、バックエンド サービスで行われたカスタム検証に対するレスポンスで、これを行う場合があります。この例のユースケースにはアクセス トークンとリフレッシュ トークンの両方が必要で、暗黙権限付与タイプは認められません。このような場合、パスワード権限付与タイプを使用してトークンを生成します。次に示すように、これを成功させるコツは 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 ヘッダーには、client_id:client_secret でつなぎ、Base64 エンコードした基本アクセス スキームを含める必要があります。

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

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

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

属性 説明 デフォルト 要否
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>

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

<AccessToken>request.header.access_token</AccessToken> が指定されている例:

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"
<AccessToken>request.queryparam.access_token</AccessToken> が指定されている例:

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

デフォルト:

なし

要否:

省略可

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

<AccessTokenPrefix> 要素

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

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

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

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

デフォルト:

Bearer

要否:

省略可

型: 文字列
有効な値:

Bearer

併用するオペレーション:
  • VerifyAccessToken

<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 アクセス トークンの取得と取り消しを可能にするをご覧ください。

デフォルト:

なし

要否:

省略可

型: 文字列
有効な値:

実行時にポリシーにアクセスできる任意のフロー変数

併用する権限付与タイプ:
  • 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 またはセッション識別子をアクセス トークンに埋め込む場合などです。

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

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

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

このポリシーの 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 ポリシーを使用して、レスポンスに表示しないカスタム属性を手動で抽出します。

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

デフォルト:

N/A

要否:

省略可

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

<ClientId> 要素

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

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

デフォルト:

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 Edge)に送信する必要があります。この要素を使用すると、認可コードをどこで探すかを Edge に指示できます。たとえば、クエリ パラメータ、HTTP ヘッダー、フォーム パラメータ(デフォルト)として送信できます。

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

デフォルト:

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

要否:

省略可

型: 文字列
有効な値: 実行時にポリシーにアクセスできる任意のフロー変数
併用する権限付与タイプ: authorization_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

デフォルト:

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

要否:

省略可

型: 整数
有効な値:
  • ゼロでない任意の正の整数。有効期限をミリ秒単位で指定します。この要素の値はミリ秒単位ですが、トークンの expires_in プロパティと expires_in フロー変数で設定される値は秒単位で表されます。
  • 無限の有効期限を示す、-1

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

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

<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 トークンの使用をご覧ください。

デフォルト:

false

要否:

省略可

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

<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 は秒単位で表現されます。

デフォルト:

false

要否:

省略可

型: 文字列
有効な値: 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 は Password がクエリ パラメータとして存在する必要があることを示します(例: ?grant_type=password)。たとえば、HTTP ヘッダーで権限付与タイプを要求するには、この値を request.header.grant_type に設定します。アクセス トークンと認可コードのリクエストもご覧ください。

デフォルト:

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

要否:

省略可

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

<Operation> 要素

<Operation>GenerateAuthorizationCode</Operation>

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

デフォルト:

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

要否:

省略可

型: 文字列
有効な値:

<PassWord> 要素

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

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

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

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

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

デフォルト:

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

要否:

省略可

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

<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 に設定します。アクセス トークンと認可コードのリクエストもご覧ください。

デフォルト:

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

要否:

省略可

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

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

<RefreshToken> 要素

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

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

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

デフォルト:

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

要否:

省略可

型: 文字列
有効な値: 実行時にポリシーでアクセスできる任意のフロー変数
併用する権限付与タイプ:
  • 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

デフォルト:

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

要否:

省略可

型: 整数
有効な値:
  • ゼロでない任意の正の整数。有効期限をミリ秒単位で指定します。
  • 無限の有効期限を示す、-1

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

<ResponseType> 要素

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

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

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

デフォルト:

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

要否:

省略可。この要素はデフォルトの動作をオーバーライドする場合に使用します。

型: 文字列
有効な値: code(認可コード権限付与タイプ)または token(暗黙的権限付与タイプ)
併用する権限付与タイプ:
  • implicit
  • GenerateAuthorizationCode オペレーションでも使用します。

<ReuseRefreshToken> 要素

<ReuseRefreshToken>true</ReuseRefreshToken>

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

デフォルト:

false

要否:

省略可

型: ブール値
有効な値:

true または false

併用する権限付与タイプ:
  • refresh_token

<Scope> 要素

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

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

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

<Scope>A B</Scope>

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

デフォルト:

スコープなし

要否:

省略可

型: 文字列
有効な値:

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

VerifyAccessToken で使用する場合、スコープ名(文字列)のスペース区切りのリスト。

併用する権限付与タイプ:
  • authorization_code
  • implicit
  • password
  • client_credentials
  • GenerateAuthorizationCode オペレーションと VerifyAccessToken オペレーションでも使用できます。

<State> 要素

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

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

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

デフォルト:

状態なし

要否:

省略可

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

<StoreToken> 要素

 <StoreToken>true</StoreToken>

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

デフォルト:

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

サポートされている権限付与タイプが指定されていない場合、許可される権限タイプは authorization_codeimplicit のみです。<GrantType> 要素もご覧ください(これは、渡される grant_type パラメータをクライアント リクエストのどこで探すかを Apigee Edge に指示するために使用する上位要素です。Edge は、サポートされている権限付与タイプの 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> 要素は、Edge がこれらの値を見つけることができる変数を指定するために使用されます。これらの要素が指定されていない場合、ポリシーは usernamepassword という名前のフォーム パラメータ内の値を検索します(デフォルト)。値が見つからない場合、ポリシーはエラーを返します。<PassWord> 要素と <UserName> 要素を使用して、認証情報を含むフロー変数を参照できます。

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

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

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

デフォルト:

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

要否:

省略可

型: 文字列
有効な値: 任意の変数設定
併用する権限付与タイプ: パスワード

アクセス トークンの検証

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 オペレーションのデフォルト設定をオーバーライドできます。

名前 説明
Scope

スペース区切りのスコープのリスト。リストされたスコープのうち少なくとも 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 仕様から外れる必要がある場合は、各パラメータについて想定される場所を指定できます。たとえば認可コードを処理するとき、認可コードの場所、クライアント 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 登録されたクライアント アプリに関連付けられているデベロッパーの ID。
developer.app.name 登録されたクライアント アプリに関連付けられているデベロッパーの名前。
client_id 登録されたクライアント アプリのクライアント ID。
grant_type リクエストに関連付けられている権限付与タイプ。
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 ハイブリッドのみ)アクセス トークンが取り消される理由を示します。

値は、REVOKED_BY_APPREVOKED_BY_ENDUSERREVOKED_BY_APP_ENDUSERTOKEN_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} 登録されたクライアント アプリの名前付きカスタム属性。

デベロッパー固有の変数

app.appType が「Company」の場合カンパニー属性が設定され、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} デベロッパーの名前付きカスタム属性。

カンパニー固有の変数

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

変数 説明
company.id
company.displayName
company.apps
company.appOwnerStatus
company.created_by
company.created_at
company.last_modified_at
company.last_modified_by
company.{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> 要素をご覧ください。

エラー リファレンス

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

ランタイム エラー

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

障害コード 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 ヘッダーとして送信されます。

注: 既存の障害ルールの条件を変更して、invalid_clientInvalidClientIdentifier の両方の名前を取得することをおすすめします。詳細と例については、16.09.21 リリースノートをご覧ください。

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\
steps.oauth.v2.ApiProductMatchFound
401

アクセス トークンに関連付けられたプロダクトに API プロキシがありません。

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

このエラーの原因について詳しくは、こちらの Apigee コミュニティの投稿をご覧ください。

VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

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

注: このような状況では、このエラーは以前は invalid_client と呼ばれていました。既存の障害ルールの条件を変更して、invalid_clientInvalidClientIdentifier の両方の名前を取得することをおすすめします。詳細と例については、16.09.21 リリースノートをご覧ください。

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

デプロイエラー

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

エラー名 原因
InvalidValueForExpiresIn

<ExpiresIn> 要素の場合、有効な値は正の整数と -1 です。

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

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

注: <Operation> 要素がない場合、UI はスキーマ検証エラーをスローします。

InvalidOperation

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

注: <Operation> 要素が無効な場合、UI はスキーマ検証エラーをスローします。

TokenValueRequired <Tokens> 要素にトークン <Token> 値を指定する必要があります。

障害変数

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

変数 説明
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

: VerifyAccessToken オペレーションでは、障害名に次の接尾辞が含まれます: keymanagement.service
例: keymanagement.service.invalid_access_token

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>

ポリシー スキーマ

各ポリシータイプは 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 ポリシーによって返される非準拠プロパティと、対応する準拠プロパティを示します。

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

関連トピック