VerifyAPIKey ポリシー

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

Apigee Edge のドキュメントを表示する。

概要

Verify API Key ポリシーによって、ランタイムに API キーを検証でき、承認済みの API キーを持つアプリのみが API にアクセスできるようになります。このポリシーを有効にすることにより、API キーが有効で失効していないことを確認できるほか、API プロダクトに関連する特定のリソースの利用を承認されていることを確認できます。

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

Verify API Key ポリシーを使用する API プロキシの構築方法を示すチュートリアルについては、API キーを要求して API を保護するをご覧ください。

サンプル

クエリ パラメータのキー

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

この例では、ポリシーは request.queryparam.apikey というフロー変数で API キーを見つけることを想定しています。変数 request.queryparam.{name} は、クライアント リクエストで渡されたクエリ パラメータの値が入力される標準の Apigee フロー変数です。

次の 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} は、クライアント リクエストで渡されたヘッダーの値が入力される標準の Apigee フロー変数です。

次の 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 ポリシーを実行すると、Apigee は自動的に一連のフロー変数に値を入力します。これらの変数を使用すると、アプリ名、アプリ ID、アプリを登録したデベロッパーまたは会社に関する情報などにアクセスできます。上記の例では、Verify API Key ポリシーを実行した後に、Assign Message ポリシーを使用して、デベロッパーのファースト ネーム、ラストネーム、メールアドレスにアクセスします。

これらの変数にはすべて、次の接頭辞が付けられます。

verifyapikey.{policy_name}

この例では、Verify API キーのポリシー名は「verify-api-key」です。したがって、変数 verifyapikey.verify-api-key.developer.firstName. にアクセスして、リクエストを行うデベロッパーのファースト ネームを参照します。

Apigee について学ぶ

Verify API Key ポリシーの概要

デベロッパーが Apigee にアプリを登録すると、Apigee はコンシューマのキーとシークレットのペアを自動的に生成します。アプリのコンシューマのキーとシークレットのペアを Apigee UI で表示したり、Apigee API からアクセスしたりできます。

アプリ登録時に、デベロッパーはアプリに関連付ける 1 つ以上の API プロダクトを選択します。ここで API プロダクトは、API プロキシを介してアクセスできるリソースのコレクションです。次に、デベロッパーは、リクエストのたびにその一環として API キー（コンシューマ キー）を、アプリに関連付けられている API プロダクトの API に渡します。詳しくはパブリッシャーの概要をご覧ください。

API キーは認証トークンとして使用することも、OAuth アクセス トークンを取得するために使用することもできます。OAuth では、API キーは「クライアント ID」と呼びます。これらの名前は同じ意味で使用できます。詳しくは、OAuth ホームをご覧ください。

Verify API Key ポリシーを実行すると、Apigee は自動的に一連のフロー変数を設定します。詳しくは、下記のフロー変数をご覧ください。

要素リファレンス

このポリシーで構成できる要素と属性は次のとおりです。

<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"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</VerifyAPIKey>

<VerifyAPIKey> 属性

次の例は、<VerifyAPIKey> タグの属性を示しています。

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

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

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

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

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

 なし 必須
continueOnError

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

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

 false 省略可
enabled

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

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

 true 省略可
async

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

 false 非推奨

<DisplayName> 要素

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

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

なし

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

<APIKey> 要素

この要素は、API キーを含むフロー変数を指定します。通常、クライアントはクエリ パラメータ、HTTP ヘッダーまたはフォーム パラメータに API キーを送信します。たとえば、キーが x-apikey というヘッダーで送信された場合、そのキーは変数 request.header.x-apikey に格納されます。

デフォルト なし
要否 必須
型 文字列

属性

次の表に、<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>

<CacheExpiryInSeconds> 要素

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

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
デフォルト なし

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

属性

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

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

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

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

 なし 任意

スキーマ

フロー変数

Verify API Key ポリシーが有効な API キーに適用されると、Apigee は一連のフロー変数を設定します。これらの変数は、フローの後半で実行されるポリシーやコードで使用できます。多くの場合、アプリ名、鍵の承認に使用される API プロダクト、API キーのカスタム属性などの API キーの属性に基づいて、カスタム処理の実行に使用されます。

ポリシーには、下記のような異なるタイプのフロー変数が設定されます。

  • 全般
  • アプリ
  • デベロッパー
  • アナリティクス
  • 収益化

フロー変数のタイプごとに接頭辞が異なります。すべての変数は、配列として具体的に示されているものを除いてスカラーです。

一般的なフロー変数

次の表に、Verify API Key ポリシーにより入力された一般的なフロー変数を示します。これらの変数にはすべて、次の接頭辞が付けられます。

verifyapikey.{policy_name}

例: verifyapikey.{policy_name}.client_id

使用可能な変数は次のとおりです。

変数 説明
client_id リクエスト側のアプリから提供されたコンシューマ キー（API キーまたはアプリキーとも呼ばれます）。
client_secret コンシューマ キーに関連付けられたコンシューマ シークレット。
redirection_uris リクエスト内のリダイレクト URI。
developer.app.id

リクエストを行うデベロッパーまたは AppGroup アプリの ID。
developer.app.name リクエストを行っているデベロッパーまたは AppGroup アプリのアプリ名。
developer.id

リクエストしているアプリの所有者として登録されているデベロッパーまたは AppGroup の 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 プロダクトの設定手順については、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 アプリタイプが「Developer」であること。
appParentId 親アプリの ID。
created_at アプリの作成時の日付 / 時刻スタンプ。
created_by アプリを作成したデベロッパーのメールアドレス。
last_modified_at アプリの最終更新時の日付 / 時刻スタンプ。
last_modified_by アプリの最終更新をしたデベロッパーのメールアドレス。
{app_custom_attributes} 任意のカスタムアプリ属性。カスタム属性の名前を指定します。

AppGroup フロー変数

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

これらの変数にはすべて、次の接頭辞が付けられます。

verifyapikey.{policy_name}.appgroup。

次に例を示します。

verifyapikey.{policy_name}.appgroup.name

使用可能な変数は次のとおりです。

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

デベロッパー フロー変数

デベロッパーに関する情報を含む以下のフロー変数は、ポリシーにより入力されます。これらの変数にはすべて、次の接頭辞が付けられます。

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} 任意のカスタム デベロッパー属性。カスタム属性の名前を指定します。

アナリティクス変数

有効な API キーに Verify API Key ポリシーが適用されると、次の変数が Analytics に自動的に入力されます。これらの変数は、Verify API Key ポリシーと OAuth ポリシーによってのみ入力されます。

変数と値は、アナリティクス レポートを作成するためのディメンションとして使用して、デベロッパーやアプリの消費パターンを可視化できます。

  • apiproduct.name
  • developer.app.name
  • client_id
  • developer.id

収益化フロー変数

ユーザーの認証後、VerifyAPIKey ポリシーで公開済みのすべての料金プランを確認し、有効化と有効期限に基づいて有効な料金プランを判別します。有効な公開済みの料金プランが見つかった場合、次のフロー変数が設定されます。

変数 説明
mint.mintng_is_apiproduct_monetized 有効な公開済みの料金プランが見つかった場合は true。
mint.mintng_rate_plan_id 料金プラン ID。
mint.rateplan_end_time_ms 料金プランの有効期限。例: 1619433556408
mint.rateplan_start_time_ms 料金プランの有効化日時。例: 1618433956209

エラー リファレンス

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码 HTTP 状态 原因
keymanagement.service.consumer_key_missing_api_product_association 400

应用凭据缺少 API 产品关联。请将密钥的应用与 API 产品相关联。请注意，这适用于所有应用类型，例如开发者应用和 AppGroup 应用。
keymanagement.service.DeveloperStatusNotActive 401

创建具有您所用 API 密钥的开发者应用的开发者具有无效状态。将应用开发者的状态设置为无效时，将停用该开发者创建的所有开发者应用。具有适当权限的管理员用户（例如组织管理员）可以通过以下方式更改开发者的状态：
keymanagement.service.invalid_client-app_not_approved 401 与 API 密钥关联的开发者应用已被撤消。撤消的应用无法访问任何 API 产品，也无法调用由 Apigee 管理的任何 API。组织管理员可以使用 Apigee API 更改开发者应用的状态。请参阅生成密钥对或更新开发者应用状态。
oauth.v2.FailedToResolveAPIKey 401 该政策要求在政策的 <APIKey> 元素中指定的变量中找到 API 密钥。 当预期变量不存在（无法解析）时，会发生此错误。
oauth.v2.InvalidApiKey 401 Apigee 已收到 API 密钥，但该密钥无效。当 Apigee 在其数据库中查找密钥时，它必须与请求中发送的密钥完全匹配。如果 API 之前有效，请确保未重新生成密钥。如果重新生成密钥，且您尝试使用旧密钥，则会看到此错误。如需了解详情，请参阅通过注册应用来控制对 API 的访问权限。
oauth.v2.InvalidApiKeyForGivenResource 401 Apigee 已收到 API 密钥，且该密钥有效；但是，它与通过产品与 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>