
概要
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 |
ポリシーの内部名。 必要に応じて、管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗した場合にエラーを返すには、 ポリシーが失敗してもフロー実行を続行するには、 |
false | 省略可 |
enabled |
ポリシーを適用するには ポリシーを無効にするには |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
name
属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。
<DisplayName>Policy Display Name</DisplayName>
デフォルト: |
なし この要素を省略した場合、ポリシーの |
要否: | 省略可 |
型: | 文字列 |
<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"
デフォルト: |
なし |
要否: |
省略可 |
型: | 文字列 |
併用するオペレーション: |
|
<AccessTokenPrefix> 要素
<AccessTokenPrefix>Bearer</AccessTokenPrefix>
デフォルトで、VerifyAccessToken は、アクセス トークンが Authorization ヘッダーでベアラー トークンとして送信されることを想定しています。例:
-H "Authorization: Bearer Rft3dqrs56Blirls56a"
現時点で、サポートされている接頭辞は Bearer のみです。
デフォルト: |
Bearer |
要否: |
省略可 |
型: | 文字列 |
有効な値: |
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
を他の変数に設定することはできません。アクセス トークンと認可コードのリクエストもご覧ください。
デフォルト: |
request.formparam.client_id(x-www-form-urlencoded、リクエストの本文で指定) |
要否: |
省略可 |
型: | 文字列 |
有効な値: | フロー変数: request.formparam.client_id |
併用する権限付与タイプ: |
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
プロパティによって設定されます。このプロパティを設定するには:
message-processor.properties
ファイルをエディタで開きます。ファイルが存在しない場合は作成します。vi /opt/apigee/customer/application/message-processor.properties
- 必要なプロパティを設定します。
conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000
- プロパティ ファイルの所有者を「apigee」ユーザーにします。
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- Message Processor を再起動します。
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
デフォルト: |
指定しない場合、システムレベルで構成されたデフォルト値がシステムによって適用されます。 |
要否: |
省略可 |
型: | 整数 |
有効な値: |
|
併用する権限付与タイプ: |
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 |
併用する権限付与タイプ: |
|
<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 |
併用する権限付与タイプ: |
|
<GenerateErrorResponse> 要素
<GenerateErrorResponse enabled='true'/>
true
に設定すると、ContinueOnError 属性が true に設定されている場合、ポリシーはレスポンスを生成して返します。false
(デフォルト)の場合、レスポンスは送信されません。代わりにポリシーの機能に関連する値が、一連のフロー変数に代入されます。
デフォルト: |
false |
要否: |
省略可 |
型: | 文字列 |
有効な値: | 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
に設定します。アクセス トークンと認可コードのリクエストもご覧ください。
デフォルト: |
request.formparam.grant_type(x-www-form-urlencoded、リクエストの本文で指定) |
要否: |
省略可 |
型: | 文字列 |
有効な値: | 上述の変数。 |
併用する権限付与タイプ: |
|
<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 プロバイダに送信する必要があります。
アクセス トークンと認可コードのリクエストもご覧ください。
デフォルト: |
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、リクエストの本文で指定) |
要否: |
省略可 |
型: | 文字列 |
有効な値: | 実行時にポリシーでアクセスできる任意のフロー変数 |
併用する権限付与タイプ: |
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、リクエストの本文で指定) |
要否: |
省略可 |
型: | 文字列 |
有効な値: | 実行時にポリシーでアクセスできる任意のフロー変数 |
併用する権限付与タイプ: |
|
<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
プロパティによって設定されます。このプロパティを設定するには:
message-processor.properties
ファイルをエディタで開きます。ファイルが存在しない場合は作成します。vi /opt/apigee/customer/application/message-processor.properties
- 必要なプロパティを設定します。
conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000
- プロパティ ファイルの所有者を「apigee」ユーザーにします。
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- Message Processor を再起動します。
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
デフォルト: |
指定しない場合、システムレベルで構成されたデフォルト値がシステムによって適用されます。 |
要否: |
省略可 |
型: | 整数 |
有効な値: |
|
併用する権限付与タイプ: |
|
"refresh_token_expires_in" : "0"
のように表示されます。<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 (暗黙的権限付与タイプ) |
併用する権限付与タイプ: |
|
<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 スコープの操作とアクセス トークンと認可コードのリクエストもご覧ください。
デフォルト: |
スコープなし |
要否: |
省略可 |
型: | 文字列 |
有効な値: |
Generate* ポリシーで使用する場合、フロー変数。 VerifyAccessToken で使用する場合、スコープ名(文字列)のスペース区切りのリスト。 |
併用する権限付与タイプ: |
|
<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 に指示します。それ以外の場合、外部アクセス トークンは維持されません。
デフォルト: |
false |
要否: |
省略可 |
型: | ブール値 |
有効な値: | true または false |
併用する権限付与タイプ: |
|
<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
パラメータの値が一致することを確認します)。
デフォルト: |
authorization _code および implicit |
要否: |
必須 |
型: | 文字列 |
有効な値: |
|
<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 プロバイダに送信する必要があります。
アクセス トークンと認可コードのリクエストもご覧ください。
デフォルト: |
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 ポリシーなどを使用してこれらの変数を読み取り、必要に応じて後続のフローで使用できます。これらの変数は、デバッグの目的にも役立ちます。
proxy.pathsuffix
から派生したもの)で構成されている場合、API プロダクト変数は自動的に設定されます。flow.resource.name 変数を明示的に設定する必要はありません。API プロダクトに有効な環境と API プロキシが構成されていない場合は、フロー内で API プロダクト変数が設定されるように flow.resource.name
を明示的に設定します。プロダクト構成の詳細については、Edge 管理 API での API の公開をご覧ください。
トークン固有の変数
変数 | 説明 |
---|---|
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 ハイブリッドのみ)アクセス トークンが取り消される理由を示します。 値は、 |
アプリ固有の変数
これらの変数は、トークンに関連付けられているデベロッパー アプリに関連します。
変数 | 説明 |
---|---|
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> 要素をご覧ください。 |
エラー リファレンス
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.
Fault code | HTTP status | Cause | Thrown by operations |
---|---|---|---|
steps.oauth.v2.access_token_expired |
401 | The access token is expired. |
VerifyAccessToken |
steps.oauth.v2.access_token_not_approved |
401 | The access token was revoked. | VerifyAccessToken |
steps.oauth.v2.apiresource_doesnot_exist |
401 | The requested resource does not exist any of the API products associated with the access token. | VerifyAccessToken |
steps.oauth.v2.FailedToResolveAccessToken |
500 | The policy expected to find an access token in a variable specified in the
<AccessToken> element, but the variable could not be resolved. |
GenerateAccessToken |
steps.oauth.v2.FailedToResolveAuthorizationCode |
500 | The policy expected to find an authorization code in a variable specified in the
<Code> element, but the variable could not be resolved. |
GenerateAuthorizationCode |
steps.oauth.v2.FailedToResolveClientId |
500 | The policy expected to find the Client ID in a variable specified in the
<ClientId> element, but the variable could not be resolved. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.FailedToResolveRefreshToken |
500 | The policy expected to find a refresh token in a variable specified in the
<RefreshToken> element, but the variable could not be resolved. |
RefreshAccessToken |
steps.oauth.v2.FailedToResolveToken |
500 | The policy expected to find a token in a variable specified in the
<Tokens> element, but the variable could not be resolved. |
ValidateToken |
steps.oauth.v2.InsufficientScope |
403 | The access token presented in the request has a scope that does not match the scope specified in the verify access token policy. To learn about scope, see Working with OAuth2 scopes. | VerifyAccessToken |
steps.oauth.v2.invalid_access_token |
401 | The access token sent from the client is invalid. | VerifyAccessToken |
steps.oauth.v2.invalid_client |
401 |
This error name is returned when the Note: It is recommended that you change existing fault rule
conditions to catch both the |
GenerateAccessToken RefreshAccessToken |
steps.oauth.v2.invalid_request |
400 | This error name is used for multiple different kinds of errors, typically for missing
or incorrect parameters sent in the request. If <GenerateResponse> is
set to false , use fault variables (described below) to retrieve details about
the error, such as the fault name and cause. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.InvalidAccessToken |
401 | The authorization header does not have the word "Bearer", which is required. For
example: Authorization: Bearer your_access_token |
VerifyAccessToken |
steps.oauth.v2.InvalidAPICallAsNo\ |
401 |
The API proxy is not in the Product associated with the access token. Tips: Be sure that the product associated with the access token is configured correctly. For example, if you use wildcards in resource paths, be sure the wildcards are being used correctly. See Create API products for details. See also this Apigee Community post for more guidance on causes for this error. |
VerifyAccessToken |
steps.oauth.v2.InvalidClientIdentifier |
500 |
This error name is returned when the |
GenerateAccessToken |
steps.oauth.v2.InvalidParameter |
500 | The policy must specify either an access token or an authorization code, but not both. | GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.InvalidTokenType |
500 | The <Tokens>/<Token> element requires you to specify the token
type (for example, refreshtoken ). If the client passes the wrong type, this
error is thrown. |
ValidateToken InvalidateToken |
steps.oauth.v2.MissingParameter |
500 | The response type is token , but no grant types are specified. |
GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
The client specified a grant type that is unsupported by the policy (not listed in the <SupportedGrantTypes> element). Note: There is currently a bug where unsupported grant type errors are not thrown correctly. If an unsupported grant type error occurs, the proxy does not enter the Error Flow, as expected. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause |
---|---|
InvalidValueForExpiresIn |
For the |
InvalidValueForRefreshTokenExpiresIn |
For the <RefreshTokenExpiresIn> element, valid values are positive
integers and -1 . |
InvalidGrantType |
An invalid grant type is specified in the <SupportedGrantTypes>
element. See the policy reference for a list of valid types. |
ExpiresInNotApplicableForOperation |
Be sure that the operations specified in the <Operations> element support expiration. For example, the VerifyToken operation does not. |
RefreshTokenExpiresInNotApplicableForOperation |
Be sure that the operations specified in the <Operations> element support refresh token expiration. For example, the VerifyToken operation does not. |
GrantTypesNotApplicableForOperation |
Be sure that the grant types specified in <SupportedGrantTypes> are supported for the specified operation. |
OperationRequired |
You must specify an operation in this policy using the Note: If the |
InvalidOperation |
You must specify a valid operation in this policy using the
Note: If the |
TokenValueRequired |
You must specify a token <Token> value in the
<Tokens> element. |
Fault variables
These variables are set when this policy triggers an error at runtime.
<GenerateResponse>
is set to
false
. If <GenerateResponse>
is
true
, the policy returns a response to the client immediately if an error occurs --
the error flow is skipped and these variables are not populated. For more information, see
What you need to
know about policy errors.Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name = "invalid_request" |
oauthV2.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GenerateAccesstoken.failed = true |
oauthV2.policy_name.fault.name |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GenerateAccesstoken.fault.name = invalid_request
Note: For the VerifyAccessToken operation, the fault name includes this suffix: |
oauthV2.policy_name.fault.cause |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GenerateAccesstoken.cause = Required param : grant_type |
Example error response
These responses are sent back to the client if the <GenerateResponse>
element is true.
errorcode
part of the error response. Do not rely on the text in the
faultstring
, because it could change.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 以降のバージョンでのパージ設定の更新
注: これらの設定が適用された後に生成されるトークンのみが影響を受けます。この設定は、以前に生成されたトークンには適用されません。
- このファイルを開いて編集します。
/opt/apigee/customer/application/message-processor.properties
- 次のプロパティを追加して、期限切れのトークンをパージするまでに待機する秒数を設定します。
conf_keymanagement_oauth.access.token.purge.after.seconds=<number of seconds>
- Message Processor を再起動します。例:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
<ExpiresIn>
属性と <RefreshTokenExpiresIn>
属性を使用してトークンの有効期限を設定できます。Edge Private Cloud 4.15.07 でのパージ設定の更新
注: これらの設定が適用された後に生成されるトークンのみが影響を受けます。この設定は、以前に生成されたトークンには適用されません。
-
OAuthV2 ポリシーで
<ExpiresIn>
属性と<RefreshTokenExpiresIn>
属性に正の値を設定します。値はミリ秒単位です。アクセス トークンが期限切れにならない場合(値が -1)、パージされません。例:<ExpiresIn>1000</ExpiresIn> <RefreshTokenExpiresIn>10000</RefreshTokenExpiresIn>
-
プロキシを再デプロイします。
-
次の API を使用して、組織のトークン パージ プロパティを更新します。
POST https://<host-name>/v1/organizations/<org-name>
ペイロード:
<Organization name="AutomationOrganization"> <Description>Desc</Description> <Properties> <Property name="keymanagement.oauth20.access.token.purge">true</Property> <Property name="keymanagement.oauth20.access.token.purge.after.seconds">120</Property> </Properties> </Organization>
-
Message Processor を再起動します。例:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
上記の API は、AutomationOrganization という組織のトークン パージ プロパティを true に設定します。この場合、アクセス トークンは、トークンとリフレッシュ トークンの両方が期限切れになってから 120 秒後にデータベースからパージされます。
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"}