注: このプロダクトの一部の機能はベータ版です。ハイブリッド インストール オプションは一般提供です。ベータ版プログラムに参加するには、Apigee の担当者にお問い合わせください。

API キーを要求して API を保護する

ラボの内容

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

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

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

アプリで API にリクエストを行うとき、有効なキーを提供する必要があります。ランタイム時に、Verify API Key ポリシーで、提供された API キーが確認されます。

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

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

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

必要なもの

  • Apigee アカウント。Apigee アカウントをまだお持ちでない場合は、Apigee Sales にお問い合わせください。
  • API 呼び出しを行うウェブブラウザ。
  • (追加のクレジット セクションの場合は不要)コマンドラインから API 呼び出しを行うためにマシンにインストールされた curl

API プロキシの作成

「mocktarget」について

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

http://mocktarget.apigee.net

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

  1. Apigee UI にアクセスしてログインします。
  2. サイド ナビゲーション バーの上部にあるユーザー名をクリックして、ユーザー プロファイル メニューを表示し、リストから組織を選択して、目的の組織に切り替えます。
    ユーザー プロファイル メニューで組織を選択
  3. ランディング ページで [API Proxies] をクリックし、API プロキシのリストを表示します。

    Apigee 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 の一部です。

    Existing API

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

    API プロキシへのリクエストに応じて Apigee が呼び出すターゲット URL を定義します。

    説明 hello world protected by API key」と入力します。
  7. [次へ] をクリックします。
  8. [Security] ページで次の操作を行います。
    フィールド 操作内容
    認可 次の項目をオンにします。
    • API キー
    • Publish API Product

    これらのオプションは非常に便利です。これらのオプションでは、2 つのポリシーを API プロキシに自動的に追加し、API キーの生成に必要な API プロダクトを作成します。

  9. [Virtual Hosts] ページで、[Next] をクリックします。
  10. [Build] ページで、test デプロイ環境が選択されていることを確認し、[Build and Deploy] をクリックします。
  11. [Summary] ページで、新しい API プロキシと 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 ポリシーです。これにより、API キーが渡されることがなくなり、不必要に漏洩することはなくなります。
  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} は実際の Apigee 組織名に置き換えてください。

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

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

    これはつまり、有効な API キーを(クエリ パラメータとして)渡していないということです。

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

API プロダクトについて

このチュートリアルでは詳しく説明しませんが、Apigee の API プロダクトは、その他の素晴らしい機能に加えて、デベロッパー向け(より正確に言えば、アプリ デベロッパーが Apigee に登録するため)に API キーを生成します。

興味があれば、API プロキシの生成時に自動的に作成された API プロダクトをご覧ください。[DEVELOP] の ["<"] をクリックしてメニューを表示し、UI で [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
    Soze
    ユーザー名 keyser
    メール keyser@example.com
  4. [作成] をクリックします。

アプリを登録する

デベロッパー アプリを登録するには:

  1. [Publish] > [Apps] を選択します。
  2. [+ App] をクリックします。
  3. [New Developer App] ウィンドウに次の情報を入力します。
    フィールド 操作内容
    NameDisplay Name keyser_app」と入力します。
    Company / Developer Developer を選択します。
    デベロッパー Keyser Soze (keyser@example.com) を選択します。
    Callback URLNotes 空白のままにします。
  4. [Credentials] セクションで をクリックし、認証情報を指定します。
  5. [Add credential] ポップアップで [Never] を選択して、[OK] を選択します。 このアプリの認証情報に有効期限はありません。
  6. このアプリの認証情報に有効期限はありません。
  7. [Products] で [Add product] をクリックします。
  8. [helloworld_apikey-Product] を選択します。
  9. [Add] をクリックします。
  10. [App Details] セクションの右側にある [Create] をクリックして作業を保存します。

API キーを取得する

API キーを取得するには:

  1. [Apps] ページ([Publish] > [Apps])で [keyser_app] をクリックします。
  2. [keyser_app] ページで、[Credentials] セクションの [Key] の横にある [Show] をクリックします。キーが「helloworld_apikeyProduct」に関連付けられていることに注意してください。

  3. コンシューマ キーを選択してコピーします。これは次のステップで必要になります。

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

API キーを取得したら、それを使用して API プロキシを呼び出すことができます。ウェブブラウザで次のように入力します。{org-name} を Apigee 組織名に置き換え、以下に示すように 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] ポリシーを選択し、queryparam ではなく header を検索するようにポリシーに指示するようにポリシーの XML を修正します。

    <APIKey ref="request.header.x-apikey"/>
    
  3. 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 の保護は、ストーリーの一部にすぎません。多くの場合、API の保護には OAuth などの追加のセキュリティが含まれます。その他のセキュリティ機能については、以下のトピックをご覧ください。

  • OAuth - OAuth とは簡単に言うと、認証情報(ユーザー名とパスワードなど)をアクセス トークンと交換するオープン プロトコルです。アクセス トークンとは、元の認証情報を損なうことなくアプリ間でもメッセージ パイプラインを介して渡すことができる、長いランダムな文字列です。アクセス トークンの有効期間は短いため、常に新しいトークンが生成されます。
  • この続きは、Apigee ドキュメントの「Secure」セクションをご覧ください。