サブスクリプション キーを使って API を呼び出す
API を発行するときに、ゲートウェイを介してその API にアクセスできるユーザーをある程度制御したいことがよくあります。 サブスクリプション キーは、API へのアクセスを制限する方法の 1 つです。
ここでは、サブスクリプション キーを使って、API をセキュリティで保護する方法を学習します。
サブスクリプションとキー
サブスクリプション キーを使って、自分の API を保護することができます。
Note
API Management の運用環境では、不正使用から API を保護するために、サブスクリプション キーと他のメカニズム (証明書認証や OAuth 2.0 認可など) を組み合わせるのが一般的です。 これらはこのモジュールの範囲外です。
サブスクリプション キーは自動生成される一意の文字列です。これはクライアント要求のヘッダーを介して、または URL のクエリ文字列として渡されます。 このキーはサブスクリプションと直接関連し、さまざまな領域にスコープを指定できます。これにより、アクセス許可とポリシーをきめ細かく制御できます。 主なサブスクリプションのスコープは次のとおりです。
- すべての API
- 単一の API
- 製品
保護された API を呼び出すアプリケーションでは、要求にキーを含める必要があります。
これらのサブスクリプション キーはいつでも再生成できます。 たとえば、認可していないユーザーとキーが共有されている疑いがある場合は、サブスクリプション キーを再生成します。
すべてのサブスクリプションには 2 つのキーがあります。プライマリとセカンダリです。 2 つのキーがあることで、必要に応じてキーを再生成しやすくなります。 たとえば、主キーを変更しつつダウンタイムを回避したい場合は、アプリ内でセカンダリ キーを使います。
サブスクリプションが有効になっている成果物の場合、その成果物内の API を呼び出すときにキーを指定する必要があります。 開発者は、サブスクリプション要求を送信することでキーを取得できます。 このプロセスは、API Management ワークフローの中核です。
注意
新しいユーザーを作成し、API にアクセスできるように各自のサブスクリプション キーを付与することは、API Management ワークフローの中核ですが、このモジュールの範囲外です。
サブスクリプション キーを使用して API を呼び出す
アプリケーションからサブスクリプションによって保護されている API エンドポイントへの呼び出しを行う場合は、すべての HTTP 要求に有効なキーを含める必要があります。 キーは、要求ヘッダー内で、または URL のクエリ文字列として渡すことができます。
既定のヘッダー名は Ocp-Apim-Subscription-Key で、既定のクエリ文字列は subscription-key です。
API 呼び出しをテストするには、開発者ポータル (お使いのサービス レベルで使用できる場合)、curl などのコマンドライン ツール、または Postman などの他のツールを使用できます。
curl コマンドを使って要求ヘッダーでキーを渡す GET 要求の例を次に示します。
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
URL 内でクエリ文字列としてキーを渡す curl コマンドの例を次に示します。
curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>
ヘッダーまたは URL のクエリ文字列でキーが渡されない場合、API ゲートウェイから 401 アクセス拒否応答を受け取ります。