VerifyAPIKey ポリシー

概要

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 ポリシーを使用して、myKey というクエリ パラメータから requestAPIKey.key を入力できます。

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

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

verifyapikey.{policy_name}

この例では、Verify API Key ポリシーの名前は「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 キーは認証トークンとして使用することも、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

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

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

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

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false 省略可
enabled

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

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

true 省略可
async

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

false 非推奨

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

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

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます

要否: 省略可
型: 文字列

<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 キーに適用されると、Edge は一連のフロー変数を代入します。こうした変数は、フローの後半で実行されるポリシーやコードに使用できるほか、アプリ名、キーの認可に使用する 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 アプリの callback 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 も呼び出すことができません。組織管理者は、管理 API を使用してデベロッパー アプリのステータスを変更できます。デベロッパー アプリの承認と失効をご覧ください。
oauth.v2.FailedToResolveAPIKey 401 このポリシーは、ポリシーの <APIKey> 要素に指定された変数に API キーが格納されていることを前提としています。このエラーは、予期した変数が存在せず、解決できない場合に発生します。
oauth.v2.InvalidApiKey 401 Edge が受信した API キーが無効です。Edge がデータベースでキーを検索するときに、リクエストで送信されたキーと完全に一致している必要があります。API がすでに実行されている場合は、キーが再生成されていないことを確認します。キーが再生成されている場合、古いキーを使用すると、このエラーが発生します。詳細については、アプリの登録と API キーの管理をご覧ください。
oauth.v2.InvalidApiKeyForGivenResource 401 Edge が有効な 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>
    

関連トピック