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

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

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

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

学習内容

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

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

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

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

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

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

API プロキシを作成する

Cloud コンソールの Apigee

  1. Google Cloud コンソールで、[プロキシ開発] > [API プロキシ] ページに移動します。

    [API プロキシ] に移動

  2. [Google Cloud] ペインのプロジェクト選択ツールで組織を選択します。組織名は Google Cloud プロジェクト名と同じです。
  3. [+ 作成] をクリックします。
  4. [Create a proxy] ペインで、[Proxy template] の [Reverse proxy (Most common)] を選択します。リバース プロキシは、受信トラフィックをバックエンド サービスに転送する処理を行います。
  5. プロキシを次のように構成します。
    名前 値
    Proxy Name helloworld_apikey
    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! という簡単なレスポンスを返すだけです。
  6. [次へ] をクリックします。
  7. Deploy（省略可）。 これらのフィールドは空白のままにします。
  8. [作成] をクリックします。
  9. Apigee によって新しいプロキシが作成され、[Proxy summary] ペインにプロキシの詳細が表示されます。

従来の UI

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

ポリシーを表示する

Cloud コンソールの Apigee

  1. helloworld_apikey プロキシの [Proxy summary] ペインで、[Develop] タブをクリックします。
  2. [Policies] セクションで、 [Add policy] をクリックします。
  3. [Create policy] ペインの [Security] で、[Verify API Key] を選択します。
  4. [Verify API Key] ペインで、[Name] セクションと [Display name] セクションの必須項目に次の値を使用して入力します。
    • 名前: ポリシー名を入力します。例: VerifyAPIKey
    • 表示名: UI で使用するポリシー名を入力します。例: Verify API Key
  5. [作成] をクリックします。
  6. [] をクリックして別のポリシーを追加します。
  7. [Create policy] ペインの [Mediation] で、[Assign Message] を選択します。
  8. [Assign Message] ペインで、[Name] セクションと [Display name] セクションの必須項目に次の値を使用して入力します。
    • 名前: ポリシー名を入力します。例: AssignMessage
    • 表示名: UI で使用するポリシー名を入力します。例: Assign Message
  9. [作成] をクリックします。
  10. 次の XML コードの <APIKey> 要素は、受信リクエスト内の API キーの場所を指定します。デフォルトでは、ポリシーは HTTP リクエストの apikey という名前のクエリ パラメータからキーを取得します。
    <APIKey ref="request.queryparam.apikey" />

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

  11. Assign Message ポリシーの内容を次のように更新します。 
    12. <AssignMessage async="false" continueOnError="false" enabled="true" name="remove-query-param-apikey">
    <DisplayName>Remove Query Param apikey</DisplayName>
    <Remove>
        <QueryParams>
            <QueryParam name="apikey"/>
        </QueryParams>
    </Remove>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>
  12. VerifyApiKey ポリシーと Remove Query Param apikey ポリシーを追加します。
    1. [Proxy endpoints] メニューで、[Preflow] をクリックします。
    2. ビジュアル エディタの [Request] ペインで、 [Add policy step] をクリックします。
    3. [Add policy step pane] ペインで、[Verify API Key] を選択します。
    4. [追加] をクリックします。
    5. ビジュアル エディタの [Request] ペインで、 [Add policy step] をクリックします。
    6. [Add policy step] ペインで、[Remove Query Param apikey] を選択します。
    7. [Add] をクリックします。
  13. [Save] をクリックします。
  14. 環境に API プロキシをデプロイします。
    1. [Deploy] をクリックします。
    2. リビジョンと環境を選択します。
    3. [Deploy] をクリックします。
  15. API の呼び出しを試すの説明に沿って API を呼び出し、変更内容をテストします。

従来の UI

  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 プロダクトを追加する

Cloud コンソールの Apigee

Apigee UI を使用して API プロダクトを追加するには:

  1. Google Cloud コンソールで、[配布] > [API プロダクト] ページに移動します。

    [API プロダクト] に移動

  2. [+ 作成] をクリックします。
  3. [Product details] に、API プロダクトの詳細を入力します。
    フィールド 説明
    名前 API プロダクトの内部名。名前には特殊文字を使用しないでください。
    注: API プロダクトの作成後に、この名前を編集することはできません。
    Display name API プロダクトの表示名。表示名は UI で使用され、いつでも編集できます。指定しない場合、[Name] の値が使用されます。このフィールドには [Name] の値が自動的に入力されます。入力された値を編集または削除できます。表示名には特殊文字を含めることができます。
    Description API プロダクトの説明。
    Environment API プロダクトでのアクセス許可の対象となる環境。たとえば、test や、prod です。
    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 プロダクトを作成するをご覧ください。

従来の UI

Apigee UI を使用して API プロダクトを追加するには:

  1. [Publish] > [API Products] を選択します。
  2. [+ 作成] をクリックします。
  3. [Product details] に、API プロダクトの詳細を入力します。
    フィールド 説明
    名前 API プロダクトの内部名。名前には特殊文字を使用しないでください。
    注: API プロダクトの作成後は、この名前を編集できません。
    Display name API プロダクトの表示名。表示名は UI で使用され、いつでも編集できます。指定しない場合、[Name] の値が使用されます。このフィールドには [Name] の値が自動的に入力されます。入力された値を編集または削除できます。表示名には特殊文字を含めることができます。
    Description API プロダクトの説明。
    Environment API プロダクトでのアクセス許可の対象となる環境。たとえば、test や prod などです。
    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 トラフィックに関するより詳細なレポートを作成したりできます。

デベロッパーを作成する

Cloud コンソールの Apigee

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

  1. Google Cloud コンソールで、[配布] > [デベロッパー] ページに移動します。

    [デベロッパー] に移動

  2. [+ 作成] をクリックします。
  3. [Add Developer] ウィンドウで、次のように入力します。
    フィールド 値
    名 Keyser
    Last Name Soze
    Email keyser@example.com
    Username keyser
  4. [追加] をクリックします。

デベロッパーの作成の詳細については、アプリ デベロッパーの登録をご覧ください。

従来の UI

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

  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. [作成] をクリックします。

アプリを登録する

Cloud コンソールの Apigee

  1. Google Cloud コンソールで、[配布] > [アプリ] ページに移動します。

    [アプリ] に移動

  2. [+ 作成] をクリックします。
  3. [アプリを作成] ウィンドウで、次のように入力します。
    フィールド 値
    アプリ名 「keyser_app」と入力します。
    表示名 「keyser_app」と入力します。
    Developer [Keyser Soze (keyser@example.com)] を選択します。
    Callback URL 空白のまま
    注 空白のまま
  4. [認証情報] セクションで、[認証情報を追加] をクリックします。
  5. [なし] を選択します。このアプリの認証情報に有効期限はありません。
  6. [商品を追加] をクリックします。
  7. 作成したプロダクトを選択します。
  8. [追加] をクリックします。
  9. [作成] をクリックします。

アプリの登録について詳しくは、アプリの登録をご覧ください。

従来の UI

デベロッパー アプリを登録するには、次の手順に従います。

  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] セクションで、[Never] を選択します。このアプリの認証情報に有効期限はありません。
  5. [Add Product] をクリックします。
  6. 作成したプロダクトを選択します。
  7. [作成] をクリックします。

API キーを取得する

Cloud コンソールの Apigee

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

  1. Google Cloud コンソールで、[配布] > [アプリ] ページに移動します。

    [アプリ] に移動

  2. アプリのリストから必要なアプリを選択します。
  3. [アプリを表示] ページの [認証情報] で、[キー] フィールドの横にある [] をクリックします。キーが、作成したプロダクトに関連付けられていることを確認します。
  4. [コピー] をクリックします。 このキーは次のステップで使用します。

従来の UI

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 キーを検索するようにプロキシを修正します。

Cloud コンソールの Apigee

  1. Google Cloud コンソールで、[プロキシ開発] > [API プロキシ] ページに移動します。

    2. [API プロキシ] に移動

  2. プロキシのリストから、必要なプロキシを選択します。
  3. [Proxy details] ページで、[Develop] をクリックします。
  4. ポリシーの XML を修正して、queryparam ではなくヘッダーを検索するようにポリシーに指示します。
    5. <APIKey ref="request.header.x-apikey"/>
  5. [Save] をクリックして変更を保存します。
  6. [Deploy] をクリックします。
  7. リビジョンと環境を選択します。
  8. [Deploy] をクリックします。

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

    curl -v -H "x-apikey: YOUR_API_KEY" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

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

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

従来の UI

  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 は、認証情報（ユーザー名とパスワードなど）をアクセス トークンと交換するオープン プロトコルです。アクセス トークンとは、元の認証情報の安全性を損なうことなく、メッセージ パイプライン（アプリ間も含む）で渡すことができる長いランダムな文字列です。

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