VerifyAPIKey ポリシー

概要

Verify API Key ポリシーを使用すると、ランタイムに API キーを検証し、承認された API キーを持つアプリのみが 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 ポリシーについて

デベロッパーが 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">

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

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

スキーマ

フロー変数

Verify API Key ポリシーが有効な API キーに適用されると、一連のフロー変数が入力されます。こうした変数は、フローの後半で実行されるポリシーやコードに使用できるほか、アプリ名、キーの認可に使用する API プロダクト、API キーのカスタム属性などの API キーの属性に基づいてカスタム処理を実行するためによく使用されます。

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

• 全般
• アプリ
• デベロッパー
• 会社
• Analytics

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

一般的なフロー変数

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

verifyapikey.{policy_name}

例: verifyapikey.{policy_name}.client_id

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

アプリフロー変数

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

verifyapikey.{policy_name}.app

例:

verifyapikey.{policy_name}.app.name

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

デベロッパー フロー変数

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

verifyapikey.{policy_name}.developer

例:

verifyapikey.{policy_name}.developer.id

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

会社のフロー変数

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

verifyapikey.{policy_name}.company

例:

verifyapikey.{policy_name}.company.name

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

Analytics 変数

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

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

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

エラー リファレンス

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

ランタイム エラー

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

デプロイエラー

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

障害変数

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

エラー レスポンスの例

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

関連トピック