概要
Verify API Key ポリシーを使用すると、ランタイムに API キーを検証し、承認された API キーを持つアプリのみが API にアクセスできるようになります。このポリシーにより、API キーが有効で、失効しておらず、API プロダクトに関連付けられた特定のリソースの消費が承認されていることが保証されます。
サンプル
クエリ パラメータのキー
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.apikey" /> </VerifyAPIKey>
この例では、ポリシーは request.queryparam.apikey
というフロー変数で API キーを見つけることを想定しています。変数 request.queryparam.{name}
は、クライアント リクエストで渡されたクエリ パラメータの値が入力される標準の Edge フロー変数です。
次の curl
コマンドでは、クエリ パラメータで API キーを渡します。
curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls
ヘッダー内のキー
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey" /> </VerifyAPIKey>
この例では、ポリシーは request.header.x-apikey
というフロー変数で API キーを見つけることを想定しています。変数 request.header.{name}
は、クライアント リクエストで渡されたヘッダーの値が入力される標準の Edge フロー変数です。
次の cURL は、ヘッダーで API キーを渡す方法を示しています。
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
変数内のキー
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="requestAPIKey.key"/> </VerifyAPIKey>
このポリシーは、キーを含む任意の変数を参照できます。この例のポリシーは、requestAPIKey.key という名前の変数から API キーを抽出します。
その変数の入力の方法は自分で決めることが可能です。たとえば、次のように、Extract Variables ポリシーを使用して requestAPIKey.key を myKey という名前のクエリ パラメータから入力できます。
<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar"> <Source>request</Source> <QueryParam name="myKey"> <Pattern ignoreCase="true">{key}</Pattern> </QueryParam> <VariablePrefix>requestAPIKey</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
アクセス ポリシーフロー変数
<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars"> <AssignVariable> <Name>devFirstName</Name> <Ref>verifyapikey.verify-api-key.developer.firstName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devLastName</Name> <Ref>verifyapikey.verify-api-key.developer.lastName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devEmail</Name> <Ref>verifyapikey.verify-api-key.developer.email</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
有効な API キーの Verify API Key ポリシーを実行すると、自動的に一連のフロー変数が入力されます。これらの変数を使用すると、アプリ名、アプリ ID、アプリを登録したデベロッパーまたは会社に関する情報などにアクセスできます。上記の例では、Verify API Key ポリシーを実行した後に、Assign Message ポリシーを使用して、デベロッパーの姓名とメールアドレスにアクセスします。
これらの変数にはすべて、次の接頭辞が付けられます。
verifyapikey.{policy_name}
この例では、Verify API キーのポリシー名は「verify-api-key」です。そのため、変数 verifyapikey.verify-api-key.developer.firstName.
にアクセスして、リクエストを行うデベロッパーの名前を参照します。
Edge の詳細
Verify API Key ポリシーについて
デベロッパーが Edge にアプリを登録すると、Edge は自動的にコンシューマ キーとシークレットのペアを生成します。アプリのコンシューマ キーとシークレットのペアを Edge UI で表示したり、Edge API からアクセスしたりできます。
アプリを登録する際に、デベロッパーはアプリに関連付ける API プロダクトを 1 つ以上選択します。API プロダクトとは、API プロキシを介してアクセスできるリソースのコレクションのことです。次に、デベロッパーは、リクエストを行うたびに API キー(コンシューマ キー)を、アプリに関連付けられている API プロダクトの API に渡します。詳しくは、公開の概要をご覧ください。
API キーは認証トークンとして使用することも、OAuth アクセス トークンを取得するために使用することもできます。OAuth では、API キーは「クライアント ID」と呼びます。これらの名前は同じ意味で使用できます。詳しくは、OAuth ホームをご覧ください。
Verify API Key ポリシーを実行すると、Edge は自動的に一連のフロー変数を入力します。詳しくは、下記のフロー変数をご覧ください。
要素リファレンス
このポリシーで構成できる要素と属性は次のとおりです。
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1"> <DisplayName>Custom label used in UI</DisplayName> <APIKey ref="variable_containing_api_key"/> </VerifyAPIKey>
<VerifyAPIKey> 属性
次の例は、<VerifyAPIKey>
タグの属性を示しています。
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
次の表に、すべてのポリシーの親要素に共通する属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
name |
ポリシーの内部名。 管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗した場合にエラーを返すには、 ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
管理 UI プロキシ エディタで name
属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。
<DisplayName>Policy Display Name</DisplayName>
デフォルト |
なし この要素を省略した場合、ポリシーの |
---|---|
要否 | 省略可 |
タイプ | 文字列 |
<APIKey> 要素
この要素は、API キーを含むフロー変数を指定します。通常、クライアントはクエリ パラメータ、HTTP ヘッダーまたはフォーム パラメータに API キーを送信します。たとえば、キーが x-apikey
というヘッダーで送信された場合、そのキーは変数 request.header.x-apikey
に格納されます。
デフォルト | なし |
---|---|
要否 | 必須 |
型 | String |
属性
次の表に、<APIKey>
要素の属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
ref |
API キーを含む変数の参照。ポリシーごとに 1 つの場所のみ利用できます。 |
なし | 必須 |
例
これらの例では、キーはパラメータと x-apikey
というヘッダーで渡されます。
クエリ パラメータの場合:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.x-apikey"/> </VerifyAPIKey>
HTTP ヘッダーの場合:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey"/> </VerifyAPIKey>
HTTP フォーム パラメータの場合:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.formparam.x-apikey"/> </VerifyAPIKey>
スキーマ
フロー変数
Verify API Key ポリシーが有効な API キーに適用されると、一連のフロー変数が入力されます。こうした変数は、フローの後半で実行されるポリシーやコードに使用できるほか、アプリ名、キーの認可に使用する API プロダクト、API キーのカスタム属性などの API キーの属性に基づいてカスタム処理を実行するためによく使用されます。
ポリシーには、下記のような異なるタイプのフロー変数が設定されます。
- 全般
- アプリ
- デベロッパー
- 会社
- Analytics
フロー変数のタイプごとに接頭辞が異なります。すべての変数は、配列として具体的に示されているものを除いてスカラーです。
一般的なフロー変数
次の表に、Verify API Key ポリシーにより入力された一般的なフロー変数を示します。これらの変数にはすべて、次の接頭辞が付けられます。
verifyapikey.{policy_name}
例: verifyapikey.{policy_name}.client_id
使用可能な変数は次のとおりです。
変数 | 説明 |
---|---|
client_id |
リクエスト側のアプリから提供されたコンシューマ キー(API キーまたはアプリキーとも呼ばれます)。 |
client_secret |
コンシューマ キーに関連付けられたコンシューマ シークレット。 |
redirection_uris |
リクエスト内のリダイレクト URI。 |
developer.app.id |
リクエストを行うデベロッパー アプリの ID。 |
developer.app.name |
リクエストを行うデベロッパー アプリのアプリ名。 |
developer.id |
リクエスト側のアプリの所有者として登録されているデベロッパーの ID。 |
developer.{custom_attrib_name} |
アプリキー プロファイルから派生したカスタム属性。 |
DisplayName |
ポリシーの <DisplayName> 属性の値。 |
failed |
API キーの検証に失敗した場合は「true」に設定します。 |
{custom_app_attrib} |
アプリ プロファイルから派生したカスタム属性。カスタム属性の名前を指定します。 |
apiproduct.name* |
リクエストを検証するために使用する API プロダクトの名前。 |
apiproduct.{custom_attrib_name}* |
API プロダクトのプロファイルから派生したカスタム属性。 |
apiproduct.developer.quota.limit* |
API プロダクトに設定されている割り当て制限(ある場合)。 |
apiproduct.developer.quota.interval* |
API プロダクトに設定されている割り当て間隔(ある場合)。 |
apiproduct.developer.quota.timeunit* |
API プロダクトに設定されている割り当て時間の単位(ある場合)。 |
* API プロダクトが、有効な環境、プロキシ、リソース(proxy.pathsuffix から派生したもの)で構成されている場合、API プロダクト変数は自動的に設定されます。API プロダクトの設定手順については、Edge 管理 API での API の公開をご覧ください。 |
アプリフロー変数
アプリに関する情報を含む以下のフロー変数は、ポリシーにより入力されます。これらの変数にはすべて、次の接頭辞が付けられます。
verifyapikey.{policy_name}.app
例:
verifyapikey.{policy_name}.app.name
使用可能な変数は次のとおりです。
変数 | 説明 |
---|---|
name |
アプリの名前。 |
id |
アプリの ID。 |
accessType |
Apigee では使用しません。 |
callbackUrl |
アプリのコールバック URL。通常は OAuth に対してのみ使用されます。 |
DisplayName |
アプリの表示名。 |
status |
「approved」や「revoked」などのアプリのステータス。 |
apiproducts |
アプリと関連付けられた API プロダクトのリストを含む配列。 |
appFamily |
アプリを含むアプリファミリ、または「デフォルト」。 |
appParentStatus |
アプリの親のステータス(「active」や「inactive」など)。 |
appType |
アプリタイプ(「Company」または「Developer」)。 |
appParentId |
親アプリの ID。 |
created_at |
アプリの作成時の日付 / 時刻スタンプ。 |
created_by |
アプリを作成したデベロッパーのメールアドレス。 |
last_modified_at |
アプリの最終更新時の日付 / 時刻スタンプ。 |
last_modified_by |
アプリの最終更新をしたデベロッパーのメールアドレス。 |
{app_custom_attributes} |
任意のカスタムアプリ属性。カスタム属性の名前を指定します。 |
デベロッパー フロー変数
デベロッパーに関する情報を含む以下のフロー変数は、ポリシーにより入力されます。これらの変数にはすべて、次の接頭辞が付けられます。
verifyapikey.{policy_name}.developer
例:
verifyapikey.{policy_name}.developer.id
使用可能な変数は次のとおりです。
変数 | 説明 |
---|---|
id |
{org_name}@@@{developer_id} を返します。 |
userName |
デベロッパーのユーザー名。 |
firstName |
デベロッパーの名前。 |
lastName |
デベロッパーの姓。 |
email |
デベロッパーのメールアドレス。 |
status |
デベロッパーのステータス(active、inactive、または login_lock)。 |
apps |
デベロッパーに関連付けられたアプリの配列。 |
created_at |
デベロッパーの作成時の日付 / 時刻スタンプ。 |
created_by |
デベロッパーを作成したユーザーのメールアドレス。 |
last_modified_at |
デベロッパーが最後に変更された日付 / 時刻スタンプ。 |
last_modified_by |
デベロッパーを変更したユーザーのメールアドレス。 |
{developer_custom_attributes} |
任意のカスタム デベロッパー属性。カスタム属性の名前を指定します。 |
Company |
デベロッパーに関連付けられている会社の名前(ある場合)。 |
会社のフロー変数
会社に関する情報を含む以下のフロー変数は、ポリシーにより事前入力されます。これらの変数にはすべて、次の接頭辞が付けられます。
verifyapikey.{policy_name}.company
例:
verifyapikey.{policy_name}.company.name
使用可能な変数は次のとおりです。
変数 | 説明 |
---|---|
name |
会社名。 |
displayName |
会社の表示名。 |
id |
会社 ID。 |
apps |
会社のアプリのリストを含む配列。 |
appOwnerStatus |
アプリオーナーのステータス(active、inactive、または login_lock)。
|
created_at |
会社の作成時の日付 / 時刻スタンプ。 |
created_by |
会社を作成したユーザーのメールアドレス。 |
last_modified_at |
会社が最後に変更された日付 / 時刻スタンプ。 |
last_modified_by |
会社を最後に変更したユーザーのメールアドレス。 |
{company_custom_attributes} |
任意のカスタム会社属性。カスタム属性の名前を指定します。 |
Analytics 変数
有効な API キーに Verify API Key ポリシーが適用されると、次の変数が Analytics に自動的に入力されます。これらの変数は、Verify API Key ポリシーと OAuth ポリシーによってのみ入力されます。
変数と値は、アナリティクス レポートを作成するためのディメンションとして使用して、デベロッパーやアプリの消費パターンを可視化できます。
- apiproduct.name
- developer.app.name
- client_id
- developer.id
エラー リファレンス
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Edge によって設定される障害変数について説明します。 これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
障害コード | HTTP ステータス | 原因 |
---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | 使用している API キーを持つデベロッパー アプリに関連付けられている会社に、 非アクティブ ステータスです。会社のステータスが非アクティブに設定されると、 その会社に関連するデベロッパーやアプリ。組織管理者は会社のステータスを変更できます 管理 API を使用します。ステータスの設定 会社です。 |
keymanagement.service.DeveloperStatusNotActive |
401 |
お客様が使用している API キーを持つデベロッパー アプリを作成したデベロッパーが非アクティブなステータスです。アプリ デベロッパーのステータスが非アクティブに設定されると、このデベロッパーが作成したすべてのデベロッパー アプリも無効になります。適切な権限のある管理ユーザー(組織管理者など)は、次の方法でデベロッパーのステータスを変更できます。
|
keymanagement.service.invalid_client-app_not_approved |
401 | API キーに関連付けられたデベロッパー アプリが取り消されています。取り消されたアプリは、 すべての API プロダクトにアクセスでき、Apigee Edge が管理する API を呼び出すことはできません。組織管理者は Management API を使用したデベロッパー アプリのステータスの変更。<ph type="x-smartling-placeholder"></ph>をご覧ください。 デベロッパー アプリの承認または取り消しをご覧ください。 |
oauth.v2.FailedToResolveAPIKey |
401 | ポリシーは、ポリシーの <APIKey> 要素で指定された変数の中で API キーを見つけることを想定しています。 このエラーは、想定した変数が存在しない(解決できない)ときに発生します。 |
oauth.v2.InvalidApiKey |
401 | Edge が API キーを受信しましたが、キーが無効です。Edge が鍵をルックアップして、 リクエストで送信されたものと完全に一致する必要があります。以前に機能していた API の場合は、キーが再生成されていないことを確認してください。キーが再生成されている場合に古いキーを使用しようとすると、このエラーが表示されます。詳しくは、アプリの登録と API の管理をご覧ください。 あります。 |
oauth.v2.InvalidApiKeyForGivenResource |
401 | API キーが Edge で受信され、かつ有効である。ただし、 プロダクトを通じて API プロキシに関連付けられたデベロッパー アプリの承認済みキー。 |
デプロイエラー
以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。
エラー名 | 原因 |
---|---|
SpecifyValueOrRefApiKey |
<APIKey> 要素に値とキーが指定されていません。 |
障害変数
ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。
変数 | 説明 | 例 |
---|---|---|
fault.name="fault_name" |
fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name は、障害が発生したポリシーのユーザー指定の名前です。 | oauthV2.VK-VerifyAPIKey.failed = true |
エラー レスポンスの例
{ "fault":{ "faultstring":"Invalid ApiKey", "detail":{ "errorcode":"oauth.v2.InvalidApiKey" } } }
{ "fault":{ "detail":{ "errorcode":"keymanagement.service.DeveloperStatusNotActive" }, "faultstring":"Developer Status is not Active" } }
障害ルールの例
<FaultRule name="FailedToResolveAPIKey"> <Step> <Name>AM-FailedToResolveAPIKey</Name> </Step> <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition> </FaultRule>