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 リソースのヘルプページを参照できます。

https://apigee.com/edge に移動してログインします。
サイドナビゲーションバーの上部にあるユーザー名をクリックしてユーザープロフィールメニューを表示し、リストから組織を選択して、該当する組織に切り替えます。
ランディングページで [API Proxies] をクリックし、API プロキシのリストを表示します。
[+ Proxy] をクリックします。
[Build a Proxy] ウィザードで [Reverse proxy (most common)] を選択し、[Next] をクリックします。

プロキシを次のように構成します。

フィールド	操作内容
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`」と入力します。

[Next] をクリックします。

[Security] ページで次の操作を行います。

フィールド	操作内容
Authorization	以下のオプションを選択します。 API Key Publish API Product これらのオプションはとても便利です。2 つのポリシーが API プロキシに自動的に追加され、API キーの生成に必要な API プロダクトが作成されます。

フィールド

操作内容

Authorization

以下のオプションを選択します。

API Key
Publish API Product

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

[Virtual Hosts] ページで、[Next] をクリックします。
[Build] ページで、test デプロイ環境が選択されていることを確認し、[Build and Deploy] をクリックします。
[Summary] ページで、新しい API プロキシと API プロダクトが正常に作成され、テスト環境にデプロイされたことを示す確認情報が表示されます。
[View the helloworld_apikey proxy in the editor] をクリックして、API プロキシの [Overview] ページを表示します。

ポリシーの表示

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

API 呼び出しの試行

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

成功

ウェブブラウザで、以下のアドレスにアクセスします。これは API プロキシでリクエスト転送先として構成されているターゲットサービスですが、ここでは直接呼び出しを行います。
```
http://mocktarget.apigee.net
```
次の正常なレスポンスが返されます。Hello, Guest!
失敗

次に、以下のように 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 トラフィックに関するより詳細なレポートを行うことができます。

デベロッパーを作成する

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

メニューで [Publish] > [Developers] を選択します。
注: [Develop] 画面がまだ表示されている場合は、[DEVELOP] で "<" をクリックしてメニューを表示し、[Publish] > [Developers] を選択します。
[+ Developer] をクリックします。

[New Developer] ウィンドウで次のように入力します。

フィールド	入力
First Name	`Keyser`
Last Name	`Soze`
Username	`keyser`
Email	`keyser@example.com`

[Create] をクリックします。

アプリを登録する

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

[Publish] > [Apps] を選択します。
[+ App] をクリックします。

[New Developer App] ウィンドウで以下を入力します。

フィールド	操作内容
Name と Display Name	「`keyser_app`」と入力します。
Company / Developer	[`Developer`] を選択します。
Developer	[`Keyser Soze (keyser@example.com)`] を選択します。
Callback URL と Notes	空白のままにします。

[Credentials] セクションでをクリックして、認証情報を指定します。
[Add credential] ポップアップで [Never]、[OK] の順に選択します。このアプリの認証情報に有効期限は設定されません。
[Products] で [Add product] をクリックします。
[helloworld_apikey-Product] を選択します。
[Add] をクリックします。
[App Details] セクションの右上にある [Create] をクリックして、入力内容を保存します。

API キーを取得する

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

[Apps] ページ（[Publish] > [Apps]）で [keyser_app] をクリックします。
[keyers_app] ページで、[Credentials] セクションの [Key] の横にある [Show] をクリックします。キーが [helloworld_apikey Product] と関連付けられていることを確認します。
コンシューマキーを選択してコピーします。次のステップでこれを使用します。

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

API プロキシを編集します。[Develop] > [API Proxies] > [helloworld_apikey] の順に選択して、[Develop] ビューに移動します。
[Verify API Key] ポリシーを選択し、ポリシー XML を修正して、queryparam ではなく header 内を検索するようにポリシーに指示します。
```
<APIKey ref="request.header.x-apikey"/>
```
[Save] をクリックして API プロキシを保存し、変更をデプロイします。
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 キーは、フォームパラメータとして渡すこともできます。これを行う場合、Verify API Key ポリシーを次のように構成します。

<APIKey ref="request.formparam.{api_key_goes_here}"/>