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 プロキシのリストを表示します。

  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 プロダクトが正常に作成され、test 環境にデプロイされたことを示す確認情報が表示されます。
  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 で [Publish] > [API Products] > [helloworld_apikey-Product] を選択します。

[Key Approval Type] が [Automatic] になっていることに注意してください。これは、手動でキーを承認した後でキーをデベロッパーに与えるのではなく、デベロッパーがアプリを登録すると自動的に API キーがデベロッパーに与えられることを意味します。

次に進みます。

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

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

デベロッパーの作成

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

  1. メニューで [Publish] > [Developers] を選択します。
  2. [+ Developer] をクリックします。
  3. [New Developer] ウィンドウで次のように入力します。
    フィールド 入力
    First Name Keyser
    Last Name Soze
    Username keyser
    Email keyser@example.com
  4. [Save] をクリックします。

アプリの登録

アプリを登録するには、次の手順に従います。

  1. [Publish > Apps] を選択します。
  2. [+ App] をクリックします。
  3. [New Developer App] ウィンドウで以下を入力します。
    項目 操作内容
    [Name] と [Display Name] keyser_app」と入力します。
    [Developer] Keyser Soze (keyser@example.com) を選択します。
    [Callback URL] と [Notes] 空白のままにします。
  4. [Credentials] セクションで をクリックして、認証情報を指定します。
  5. [Add credential] ポップアップで [Never] を選択して、[OK] を選択します。このアプリの認証情報に有効期限は設定されません。
  6. [Products] で [Add product] をクリックします。
  7. [helloworld_apikey-Product] を選択します。
  8. [Add] をクリックします。

API キーの取得

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

  1. [Apps] ページ([Publish] > [Apps])で [keyser_app] をクリックします。
  2. [keyser_app] ページで [Consumer Key] 列の [Show] をクリックします。キーが [helloworld_apikey Product] と関連付けられていることを確認します。[Hide] をクリックしてキーを非表示にします。
  3. コンシューマ キーを選択してコピーします。次のステップでこれを使用します。

キーを使用した API の呼び出し

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

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

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 呼び出しを実行し、x-apikey というヘッダーとして API キーを渡します。組織名を置き換えることを忘れないでください。

        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 ドキュメントの安全性に関するセクションをご覧ください。