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>

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

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

verifyapikey.{policy_name}

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

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

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>

<APIKey> 要素

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

属性

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

例

これらの例では、キーはパラメータと 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>

属性

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

スキーマ

フロー変数

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

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

• 全般
• アプリ
• デベロッパー
• Analytics
• 収益化

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

一般的なフロー変数

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

verifyapikey.{policy_name}

例: verifyapikey.{policy_name}.client_id

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

アプリフロー変数

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

verifyapikey.{policy_name}.app

例:

verifyapikey.{policy_name}.app.name

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

AppGroup フロー変数

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

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

verifyapikey.{policy_name}.appgroup

次に例を示します。

verifyapikey.{policy_name}.appgroup.name

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

デベロッパー フロー変数

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

verifyapikey.{policy_name}.developer

例:

verifyapikey.{policy_name}.developer.id

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

Analytics 変数

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

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

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

収益化フロー変数

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

エラー リファレンス

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

ランタイム エラー

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

デプロイエラー

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

障害変数

ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

エラー レスポンスの例

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