API キーのリクエストによる API の保護

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

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

動画: API の保護の概要をご紹介しているこちらの短い動画をご覧ください。

学習内容

このチュートリアルでは、以下の手順を説明します。

  • API キーを必要とする API プロキシを作成する。
  • API プロダクト、デベロッパー、デベロッパー アプリを作成する。
  • API キーを使用して API を呼び出す。

API を不正なアクセスから保護することが重要です。これを行う方法の一つに、API キーを使用する方法があります。

API キーを確認するように構成された API プロキシに対してアプリからリクエストを行うと、そのアプリは有効なキーの提供を求められます。ランタイム時に、Verify API Key ポリシーにより、提供された API キーについて、以下のことが確認されます。

  • API キーが有効であること
  • API キーが失効していないこと
  • API キーが、リクエストされたリソースを公開する API プロダクトの API キーと一致していること

そのキーが有効な場合は、リクエストが許可されます。キーが無効な場合は、リクエストが承認エラーになります。

API プロキシを作成する

  1. Apigee UI にアクセスしてログインします。
  2. UI の左上にあるプルダウン メニューから組織を選択します。
  3. [Develop] > [API Proxies] をクリックして、API プロキシのリストを表示します。

  4. [CREATE NEW] をクリックします。
    プロキシの作成ボタン
  5. [Build a Proxy] ウィザードで、[Reverse proxy (most common)] を選択します。
  6. プロキシを次のように構成します。
    フィールド 操作
    Proxy Name helloworld_apikey を入力します。
    Project Base Path

    /helloapikey に変更します。

    [Project Base Path] は、API プロキシに対してリクエストを行うために使用される URL の一部です。

    Description hello world protected by API key を入力します。
    Target (Existing API)

    http://mocktarget.apigee.net を入力します。

    これにより、API プロキシへのリクエストに応じて Apigee が呼び出すターゲット URL が定義されます。このターゲットは、Hello, Guest! という簡単なレスポンスを返すだけです。

  7. [Next] をクリックします。
  8. [Common policies] ページで、[API Key] を選択します。このオプションでは、API プロキシに 2 つのポリシーが自動的に追加され、API キーの生成に必要な API プロダクトが作成されます。
  9. [Next] をクリックします。
  10. [Summary] ページで、デプロイ環境が選択されていることを確認し、[Create and deploy] をクリックします。
  11. [Edit proxy] をクリックして、API プロキシの [Overview] ページを表示します。

ポリシーを表示する

  1. API プロキシ エディタで [Develop] タブをクリックします。API プロキシのリクエスト フローに次の 2 つのポリシーが追加されていることを確認します。
    • Verify API Key - API 呼び出しを調べて、(クエリ パラメータとして送信される)有効な API キーが存在することを確認します。
    • Remove Query Param apikey – 不必要に回覧されて外部にさらされないように、検査後の API キーを削除する Assign Message ポリシー。
  2. フロービューの [Verify API Key] ポリシー アイコンをクリックし、下部のコードビューでポリシーの XML 構成を確認します。<APIKey> 要素により、呼び出しの際に API キーを検索する場所がポリシーに指示されます。デフォルトでは、次のように HTTP リクエストで apikey というクエリ パラメータとしてキーが検索されます。

    <APIKey ref="request.queryparam.apikey" />
    

    apikey という名前にする必要はありません。API キーを含む任意のプロパティを指定できます。

API 呼び出しの試行

このステップでは、ターゲット サービスに対して直接 API 呼び出しを行い、それが成功すること、次に API プロキシに対する呼び出しを行い、失敗することを確認し、ポリシーによりどのように保護されるかを確認できます。

  1. 成功

    ウェブブラウザで、以下のアドレスにアクセスします。これは API プロキシでリクエスト転送先として構成されているターゲット サービスですが、ここでは直接呼び出しを行います。

    http://mocktarget.apigee.net
    

    次の正常なレスポンスが返されます。Hello, Guest!

  2. 失敗

    今度は API プロキシを呼び出してみます。

    curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey

    ここで、YOUR ENV_GROUP_HOSTNAME は環境グループのホスト名です。環境グループのホスト名を探すをご覧ください。

    Verify API Key ポリシーを使用しない場合、この呼び出しでは前の呼び出しと同じレスポンスが返されます。しかしこの場合は、次のエラー レスポンスが返されます。

    {"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
    

    これは、有効な API キーが(クエリ パラメータとして)正しく渡されなかったことを意味します。

次のステップでは、必要な API キーを取得します。

API プロダクトの追加

Apigee UI を使用して API プロダクトを追加するには、次の手順を実施します。

  1. [Publish] > [API Products] を選択します。
  2. [+Create] をクリックします。
  3. [Product details] に、API プロダクトの詳細を入力します。
    フィールド 説明
    Name API プロダクトの内部名。名前には特殊文字を使用しないでください。
    注: API プロダクトの作成後は、この名前を編集できません。
    Display name API プロダクトの表示名。表示名は UI で使用され、いつでも編集できます。指定しない場合、[Name] の値が使用されます。このフィールドには [Name] の値が自動的に入力されます。入力された値を編集または削除できます。表示名には特殊文字を含めることができます。
    Description API プロダクトの説明。
    Environment API プロダクトでのアクセス許可の対象となる環境。たとえば、testprod です。
    Access [Public] を選択します。
    Automatically approve access requests この API プロダクトに対する任意のアプリからのキーリクエストの自動承認を有効にします。
    Quota このチュートリアルでは無視します。
    Allowed OAuth Scopes このチュートリアルでは無視します。
  4. [Operations] セクションで、[+Add an Operation] をクリックします。
  5. [API Proxy] フィールドで、作成した API プロキシを選択します。
  6. [Path] フィールドに「/」と入力します。他のフィールドは無視します。
  7. [Save] をクリックして、オペレーションを保存します。
  8. [Save] をクリックして、API プロダクトを保存します。

デベロッパーとアプリを組織に追加する

次に、デベロッパーが API の使用登録を行うためのワークフローをシミュレートします。デベロッパーは API を呼び出す 1 つ以上のアプリを所有し、各アプリにはそれぞれ一意の API キーが割り当てられます。これにより、API プロバイダは API へのアクセスをより細かく制御したり、アプリによる API トラフィックに関するより詳細なレポートを作成したりできます。

デベロッパーを作成する

デベロッパーを作成するには、次の手順を実施します。

  1. メニューで [Publish] > [Developers] を選択します。
    : [Develop] 画面がまだ表示されている場合は、[DEVELOP] で "<" をクリックしてメニューを表示し、[Publish] > [Developers] を選択します。
  2. [+ Developer] をクリックします。
  3. [New Developer] ウィンドウに次の情報を入力します。
    フィールド 入力
    First Name Keyser
    Last Name Soze
    Username keyser
    Email keyser@example.com
  4. [Create] をクリックします。

アプリを登録する

アプリを登録するには、次の手順を実施します。

  1. [Publish] > [Apps] を選択します。
  2. [+ App] をクリックします。
  3. [New Developer App] ウィンドウに次の情報を入力します。
    フィールド 操作
    NameDisplay Name keyser_app を入力します。
    Developer Keyser Soze (keyser@example.com) を選択します
    Callback URLNotes 空白のまま
  4. [Credentials] セクションで、[Never] を選択します。このアプリの認証情報に有効期限はありません。
  5. [Add Product] をクリックします。
  6. 作成したプロダクトを選択します。
  7. [Create] をクリックします。

API キーを取得する

API キーを取得するには、次の手順にを実施します。

  1. [Apps] ページ([Publish] > [Apps])で [keyser_app] をクリックします。
  2. [keyser_app] ページで、[Credentials] セクションの [Key] の横にある [Show] をクリックします。キーが、作成したプロダクトに関連付けられていることを確認します。
  3. キーを選択してコピーします。これを次のステップで使用します。

キーを使用して API を呼び出す

API キーを取得したら、それを使って API プロキシを呼び出すことができます。次のように、クエリ パラメータとして API キーを貼り付けます。クエリ パラメータに余分なスペースが含まれていないことを確認してください。

curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=your_api_key

これで、API プロキシを呼び出すと、Hello, Guest! というレスポンスが返されます。

これで完了です。有効な API キーを呼び出しに含めるように要求することで、API プロキシが作成され、保護されました。

クエリ パラメータとして API キーを渡すことは通常はおすすめしません。代わりに HTTP ヘッダーで渡してください

ベスト プラクティス: HTTP ヘッダーでキーを渡す

このステップでは、x-apikey というヘッダーで API キーを検索するようにプロキシを修正します。

  1. API プロキシを編集します。[Develop] > [API Proxies] > [helloworld_apikey] の順に選択して、[Develop] ビューに移動します。
  2. [Verify API Key] ポリシーを選択し、ポリシー XML を修正して、queryparam ではなく header 内を検索するようにポリシーに指示します。

    <APIKey ref="request.header.x-apikey"/>
    
  3. API プロキシを保存し、[Deploy] を使用してデプロイします。
  4. cURL を使用して以下の API 呼び出しを行い、API キーを x-apikey というヘッダーとして渡します。組織名を置き換えることを忘れないでください。

    curl -v -H "x-apikey: {api_key_goes_here}" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

完全に変更するには、クエリ パラメータではなくヘッダーを削除するよう Assign Message ポリシーを構成する必要があります。次に例を示します。

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>

関連トピック

API プロダクトとキーに関連するトピックをご紹介します。

多くの場合、API 保護には OAuth などの追加のセキュリティが含まれます。OAuth は、認証情報(ユーザー名とパスワードなど)をアクセス トークンと交換するオープン プロトコルです。アクセス トークンとは、元の認証情報の安全性を損なうことなく、メッセージ パイプライン(アプリ間も含む)で渡すことができる長いランダムな文字列です。

セキュリティ関連のトピックの概要については、プロキシの保護をご覧ください。