API キーの要求による API の保護

演習内容

このチュートリアルでは、次のことを学習します。

  • API キーを必要とする API プロキシの作成
  • デベロッパーの追加とアプリの登録
  • API キーを使用した API の呼び出し

不正アクセスから API を保護することは重要です。保護するための 1 つの方法は、API キー（「公開鍵」、「コンシューマ キー」、「アプリキー」とも呼ばれる）を使用することです。

アプリでは、API にリクエストを行うときに、有効なキーを提供する必要があります。Verify API Key ポリシーでは実行時に、提供された API キーに関して次の点を確認します。

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

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

このチュートリアルで作成する API プロキシでは、アクセス時に有効な API キーを必要とします。

必要なもの

  • Apigee Edge アカウント。まだお持ちでない場合は、Apigee Edge アカウントの作成の手順に沿って登録できます。
  • API 呼び出しを行うウェブブラウザ。
  • cURL（追加講習のセクションでは不要）。コマンドラインから API 呼び出しを行うために、マシンにインストールされている必要があります。

API プロキシの作成

mocktarget について

mocktarget サービスは Apigee でホストされており、単純なデータを返します。API キーやアクセス トークンは必要ありません。実際に、ウェブブラウザでアクセスできます。次をクリックして、試してみましょう。

http://mocktarget.apigee.net

ターゲットは Hello, Guest! を返します。/help リソースを使用すると、利用可能なその他の API リソースのヘルプページを参照できます。

  1. https://apigee.com/edge に移動してログインします。
  2. サイド ナビゲーション バーの上部にあるユーザー名をクリックしてユーザー プロフィール メニューを表示し、リストから組織を選択して、該当する組織に切り替えます。
    ユーザー プロフィール メニューで組織を選択

  3. ランディング ページで [API Proxies] をクリックし、API プロキシのリストを表示します。

    Edge API メニュー
  4. [+ Proxy] をクリックします。
    [Create proxy] ボタン
  5. [Build a Proxy] ウィザードで [Reverse proxy (most common)] を選択し、[Next] をクリックします。
  6. プロキシを次のように構成します。
    フィールド 操作内容
    Proxy Name 「helloworld_apikey」と入力します。
    Project Base Path

    /helloapikey に変更します。

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

    注: API のバージョニングに関する Apigee の推奨事項については、『Web API Design: The Missing Link』電子書籍の「Versioning」をご覧ください。
    Existing API

    「http://mocktarget.apigee.net」と入力します。

    ここでは、API プロキシへのリクエストで Apigee Edge によって呼び出されるターゲット URL を定義します。
    Description 「hello world protected by API key」と入力します。
  7. [Next] をクリックします。
  8. [Security] ページで次の操作を行います。
    フィールド 操作内容
    Authorization 以下のオプションを選択します。
    • API Key
    • Publish API Product

    これらのオプションはとても便利です。2 つのポリシーが API プロキシに自動的に追加され、API キーの生成に必要な API プロダクトが作成されます。
  9. [Virtual Hosts] ページで、[Next] をクリックします。
  10. [Build] ページで、test デプロイ環境が選択されていることを確認し、[Build and Deploy] をクリックします。
  11. [Summary] ページで、新しい API プロキシと API プロダクトが正常に作成され、テスト環境にデプロイされたことを示す確認情報が表示されます。
  12. [View the helloworld_apikey proxy in the editor] をクリックして、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 プロキシを呼び出してみます。

    http://{org-name}-test.apigee.net/helloapikey

    {org-name} は実際の Edge 組織の名前に置き換えてください。

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

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

    これは、有効な API キーが（クエリ パラメータとして）渡されなかったことを意味します。実際、渡されませんでした。

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

API プロダクトについて

このチュートリアルでは詳しく説明しませんが、Edge の便利な機能の 1 つである API プロダクトによって、デベロッパー用（正確に言うとデベロッパーが Edge に登録するアプリ用）の API キーがされます。

興味がある方は、API プロキシの生成時に自動的に作成された API プロダクトを確認できます。UI の [DEVELOP] で "<" をクリックしてメニューを表示し、[Publish] > [API Products] > [helloworld_apikey-Product] の順に選択します。

[Key Approval Type] が [Automatic] になっていることに注意してください。これは、手動でキーを承認した後でキーをデベロッパーに与えるのではなく、デベロッパーがアプリを登録すると自動的に 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] ウィンドウで以下を入力します。
    フィールド 操作内容
    Name と Display Name 「keyser_app」と入力します。
    Company / Developer [Developer] を選択します。
    Developer [Keyser Soze (keyser@example.com)] を選択します。
    Callback URL と Notes 空白のままにします。
  4. [Credentials] セクションで をクリックして、認証情報を指定します。
  5. [Add credential] ポップアップで [Never]、[OK] の順に選択します。このアプリの認証情報に有効期限は設定されません。
    6. このアプリの認証情報に有効期限は設定されません。
  6. [Products] で [Add product] をクリックします。
  7. [helloworld_apikey-Product] を選択します。
  8. [Add] をクリックします。
  9. [App Details] セクションの右上にある [Create] をクリックして、入力内容を保存します。

API キーを取得する

API キーを取得するには、次の手順に従います。

  1. [Apps] ページ（[Publish] > [Apps]）で [keyser_app] をクリックします。
  2. [keyers_app] ページで、[Credentials] セクションの [Key] の横にある [Show] をクリックします。キーが [helloworld_apikey Product] と関連付けられていることを確認します。

  3. コンシューマ キーを選択してコピーします。次のステップでこれを使用します。

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

API キーを用意できたので、これを使用して API プロキシを呼び出すことができます。ウェブブラウザに次のように入力します。{org-name} は実際の Edge 組織名に置き換え、クエリ パラメータとして API キーを貼り付けます。クエリ パラメータに余分なスペースが含まれていないことを確認してください。

http://{org-name}-test.apigee.net/helloapikey?apikey={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. [Save] をクリックして API プロキシを保存し、変更をデプロイします。

  4. cURL を使用して以下の API 呼び出しを行い、API キーを x-apikey というヘッダーとして渡します。組織名を置き換えることを忘れないでください。

    curl -v -H "x-apikey: {api_key_goes_here}" http://{org-name}-test.apigee.net/helloapikey

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

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

関連トピック

以下に、このチュートリアルに直接関係するいくつかのトピックを示します。

厳密には、API キーの使用は API 保護の 1 つの側面にすぎません。通常、API 保護には OAuth などの追加のセキュリティが使用されます。以下に、その他のセキュリティ機能について説明するいくつかのトピックをご紹介します。

  • OAuth – OAuth は、簡単に言えば、アクセス トークンの認証情報（ユーザー名やパスワードなど）を交換するオープン プロトコルです。アクセス トークンとは、元の認証情報の安全性を損なうことなく、メッセージ パイプラインで（アプリ間も含む）渡すことができる長いランダムな文字列です。多くの場合、アクセス トークンの有効期間は短く設定され、新しいトークンが生成され続けます。
  • この続きは、Apigee Edge ドキュメントの安全性に関するセクションをご覧ください。