Azure API Management のサブスクリプション
適用対象: すべての API Management レベル
Azure API Management での "サブスクリプション" は、API コンシューマーが API Management インスタンスを通じて公開された API にアクセスするための最も一般的な方法です。 この記事では、この概念の概要について説明します。
Note
API Management でサブスクリプション キーを使用して API を呼び出す特定の目的のために、API Management サブスクリプションが使用されます。 これは、Azure サブスクリプションと同じではありません。
サブスクリプションとは
API Management を通じて API を公開することで、サブスクリプション キーを用いて API アクセスを簡単に保護できます。 公開された API を使用する必要がある開発者は、これらの API を呼び出すときに、有効なサブスクリプション キーを HTTP 要求に含める必要があります。 有効なサブスクリプション キーがない場合、呼び出しは次のようになります。
- API Management ゲートウェイによって直ちに拒否されます。
- バックエンド サービスに転送されません。
API にアクセスするには、開発者にサブスクリプションとサブスクリプション キーが必要です。 サブスクリプションは、基本的にサブスクリプション キーのペアの名前付きコンテナーです。
さらに、次の点も考慮する必要があります。
- 開発者は、API 発行元の承認なしにサブスクリプションを取得できます。
- API の公開元は、API コンシューマー用のサブスクリプションを直接作成することもできます。
ヒント
API Management では、API へのアクセスをセキュリティで保護するための他のメカニズムもサポートしています。たとえば、以下があります。
サブスクリプション キーを管理する
定期的なキーの再生成は、一般的なセキュリティ対策です。 サブスクリプション キーを必要とする Azure サービスと同様に、API Management でもキーをペアで生成します。 サービスを利用する各アプリケーションは、キー A からキー B に切り替え、最小限の中断で鍵 A を再生成できます。その逆も同様です。
特定のキーを再生成する代わりに設定するには、Azure API Management サブスクリプション - Azure REST API の作成または更新を呼び出します。 具体的には、HTTP 要求本文で properties.primaryKey や properties.secondaryKey を設定する必要があります。
Note
- API Management には、有効期限の設定やキーの自動ローテーションなど、サブスクリプション キーのライフサイクルを管理するための組み込み機能は用意されていません。 Azure PowerShell や Azure SDK などのツールを使用して、これらのプロセスを自動化するワークフローを開発できます。
- API への時間制限付きアクセスを強制するために、API 発行元はサブスクリプション キーを含むポリシーを使用したり、トークンベースの認証などの組み込みの有効期限を提供するメカニズムを使用したりできます。
サブスクリプションの範囲
サブスクリプションは、製品、すべての API、または個々の API というさまざまな範囲に関連付けることができます。
製品のサブスクリプション
従来、API Management のサブスクリプションは、常に 1 つの 製品のスコープに関連付けられていました。 開発者 :
- 開発者ポータルで製品の一覧を確認していました。
- 使用する製品のサブスクリプション要求を送信します。
- これらのサブスクリプションのキー (自動的に承認または API 発行元によって承認) を使用して、製品内のすべての API にアクセスします。
現時点では、製品をスコープとするサブスクリプションは、開発者ポータルのユーザー プロファイル セクションにのみ表示されます。
すべての API または個々の API のサブスクリプション
次のいずれかへのアクセスを許可するキーを作成することもできます。
- 1 つの API、または
- API Management インスタンス内のすべての API。
このような場合、最初に、製品を作成してそれに API を追加する必要はありません。
すべてのアクセス許可を持つサブスクリプション
各 API Management インスタンスには、すべての API へのアクセスを許可する組み込み済みのオールアクセス サブスクリプションが付属しています。 このサービス スコープのサブスクリプションを使用すると、サービス所有者は、テスト コンソール内での API のテストとデバッグを単純な方法で実行できます。
警告
すべてのアクセス許可を持つサブスクリプションを使用すると、API Management インスタンス内のすべての API へのアクセスが可能になります。これは、承認されたユーザーのみが使用する必要があります。 このサブスクリプションを定期的な API アクセスに使用したり、クライアント アプリにすべてのアクセス許可を持つサブスクリプションのキーを埋め込んだりしないでください。
Note
API スコープ サブスクリプション、すべての API のサブスクリプション、または組み込みのすべてのアクセス許可を持つサブスクリプションを使っている場合、製品スコープで構成されたポリシーは、そのサブスクリプションからの要求には適用されません。
スタンドアロン サブスクリプション
API Management では、開発者アカウントに関連付けられない "スタンドアロン" サブスクリプションも許可されます。 この機能は、サブスクリプションを共有する複数の開発者やチームと同様のシナリオで役立ちます。
所有者を割り当てずにサブスクリプションを作成すると、サブスクリプションはスタンドアロン サブスクリプションになります。 開発者とチームの残りの部分にスタンドアロン サブスクリプション キーへのアクセスを許可するには、次のいずれかを実行します。
- サブスクリプション キーを手動で共有します。
- カスタム システムを使用して、サブスクリプション キーをチームで使用できます。
Azure portal でサブスクリプションを作成して管理する
API の公開元は、Azure portal で直接サブスクリプションを作成できます。
ポータルで作成すると、サブスクリプションはアクティブ状態になります。つまり、サブスクライバーは、有効なサブスクリプション キーを使用して関連する API を呼び出すことができます。 サブスクリプションの状態は、必要に応じて変更できます。 たとえば、任意のサブスクリプション (組み込み済みのオールアクセス サブスクリプションを含め) を中断、キャンセル、または削除して、API アクセスを防ぐことができます。
サブスクリプション キーを使用する
サブスクライバーは、次の 2 つの方法のいずれかで API Management サブスクリプション キーを使用できます。
Ocp-Apim-Subscription-Key HTTP ヘッダーを要求に追加し、有効なサブスクリプション キーの値を渡します。
subscription-key クエリ パラメーターと有効な値を URL に含めます。 このクエリ パラメーターは、ヘッダーが存在しない場合にのみチェックされます。
ヒント
Ocp-Apim-Subscription-Key はサブスクリプション キー ヘッダーの既定の名前であり、subscription-key はクエリ パラメーターの既定の名前です。 必要に応じて、各 API の設定でこれらの名前を変更できます。 たとえば、ポータル内の API の [設定] タブでこれらの名前を更新します。
Note
要求ヘッダーまたはクエリ パラメータに含まれているとき、サブスクリプション キーは既定でバックエンドに渡され、バックエンド監視ログまたはその他のシステムで公開される可能性があります。 これが機密データと考えられる場合は、サブスクリプション キー ヘッダー (set-header) またはクエリ パラメータ (set-query-parameter) を削除するように、inbound セクションの最後のポリシーを構成できます。
API または製品アクセスのサブスクリプション要件を有効または無効にする
API を作成する際、既定では API アクセスにサブスクリプション キーが必要です。 同様に、製品を作成する場合、既定では、製品に追加する API にアクセスするためにサブスクリプション キーが必要です。 シナリオによっては、API 公開元は、サブスクリプションを必要としない製品または特定の API を公開することがあります。 公開元は特定の API への、セキュリティで保護されていない (匿名) アクセスを有効にできますが、クライアント アクセスをセキュリティで保護するために別のメカニズムを構成することが推奨されています。
注意事項
サブスクリプションを必要としない製品または API を構成する場合は注意が必要です。 この構成では制限が過度に緩められ、API が特定の API セキュリティの脅威に対してより脆弱になるおそれがあります。
Note
オープン製品の [Requires subscription] (サブスクリプションが必要) 設定は無効になっています。つまり、ユーザーはサブスクリプションに登録する必要がありません。 このため、開発者ポータルの [製品] ページにオープン製品は表示されません。
サブスクリプション要件は、API または製品の作成時、または後日無効にすることができます。
ポータルを使用してサブスクリプション要件を無効にするには:
- 製品の要件の無効化 - 製品の [設定] ページで [Requires subscription] (サブスクリプションを要求する) を無効にします
- API の要件の無効化 - API の [設定] ページで [Subscription required] (サブスクリプションが必要) を無効にします。
サブスクリプション要件を無効にすると、選択した 1 つまたは複数の API にサブスクリプション キーなしでアクセスできます。
API Management でサブスクリプション キーを使用して、または使用しないで要求を処理する方法
サブスクリプション キーを使用した API 要求
API Management では、サブスクリプション キーを持つクライアントから API 要求を受信すると、次のルールに従ってその要求が処理されます。
まず、アクティブなサブスクリプションに関連付けられた有効なキー (次のいずれか) かどうかを確認します。
- API にスコープ指定されたサブスクリプション
- API に割り当てられている製品にスコープ指定されたサブスクリプション
- すべての API にスコープ指定されたサブスクリプション
- サービス スコープ サブスクリプション (組み込みのすべてのアクセス サブスクリプション)
適切なスコープでアクティブなサブスクリプションの有効なキーが指定されている場合は、アクセスが許可されます。 ポリシーは、そのスコープでのポリシー定義の構成に応じて適用されます。
キーが有効でなくても、その API を含む製品が存在し、サブスクリプションが必要ない場合 (オープンな製品)、キーを無視し、サブスクリプション キーのない API 要求として処理します (以下を参照)。
それ以外の場合、アクセスは拒否されます (401 アクセス拒否エラー)。
サブスクリプション キーを使用しない API 要求
API Management では、サブスクリプション キーのないクライアントから API 要求を受信すると、次のルールに従ってその要求を処理します。
- まず、API を含むがサブスクリプションを必要としない製品 ("オープンな" 製品) が存在するかどうかを確認します。 そのオープンな製品が存在する場合は、そのオープンな製品用に構成された API、ポリシー、アクセス規則のコンテキストで要求を処理します。 API は、最大 1 つのオープンな製品に関連付けることができます。
- API を含むオープンな製品が見つからない場合は、API にサブスクリプションが必要かどうかを確認します。 サブスクリプションが必要ない場合は、その API と操作のコンテキストで要求を処理します。
- 構成済みの製品または API が見つからない場合、アクセスは拒否されます (401 アクセス拒否エラー)。
概要テーブル
次の表は、シナリオごとに、サブスクリプション キーの有無にかかわらず、ゲートウェイが API 要求を処理する方法をまとめたものです。 意図しない匿名 API アクセスが可能になる可能性のある構成に注目してください。
| API に割り当てられているすべての製品でサブスクリプションが必要 | API にサブスクリプションが必要 | サブスクリプション キーを使用した API 呼び出し | サブスクリプション キーを使用しない API 呼び出し | 一般的なシナリオ |
|---|---|---|---|---|
| ✔️ | ✔️ | アクセス許可 • 製品スコープ キー • API スコープ キー • すべての API スコープ キー • サービス スコープ キー アクセスが拒否されました: • 該当する製品または API にスコープ指定されていないその他のキー |
アクセスが拒否されました | 製品スコープまたは API スコープのサブスクリプションを使用した保護された API アクセス |
| ✔️ | ❌ | アクセス許可 • 製品スコープ キー • API スコープ キー • すべての API スコープ キー • サービス スコープ キー • 該当する製品または API にスコープ指定されていないその他のキー |
アクセス許可 (API コンテキスト) | • 製品スコープのサブスクリプションを使用した保護された API アクセス • API への匿名アクセス 匿名アクセスを想定していない場合は、認証と認可を強制するように API レベルのポリシーを構成します。 |
| ❌1 | ✔️ | アクセス許可 • 製品スコープ キー • API スコープ キー • すべての API スコープ キー • サービス スコープ キー アクセスが拒否されました: • 該当する製品または API にスコープ指定されていないその他のキー |
アクセス許可 (オープンな製品のコンテキスト) | • API スコープ サブスクリプションを使用した保護された API アクセス • API への匿名アクセス 匿名アクセスを想定していない場合は、認証と認可を強制するように製品ポリシーを構成します。 |
| ❌1 | ❌ | アクセス許可 • 製品スコープ キー • API スコープ キー • すべての API スコープ キー • サービス スコープ キー • 該当する製品または API にスコープ指定されていないその他のキー |
アクセス許可 (オープンな製品のコンテキスト) | API への匿名アクセス。 匿名アクセスを想定していない場合は、認証と認可を強制するように製品ポリシーを構成します。 |
1 API に関連付けられているオープンな製品が存在します。
考慮事項
- 製品が公開されているかどうかを問わず、製品コンテキストでの API アクセスは同じです。 製品の公開を解除すると、開発者ポータルで非表示になりますが、新規または既存のサブスクリプション キーが無効になるわけではありません。
- API でサブスクリプション認証が必要ない場合、サブスクリプション キーを含むすべての API 要求は、サブスクリプション キーのない要求と同様に扱われます。 サブスクリプション キーは無視されます。
- API アクセスの "コンテキスト" とは、特定のスコープ (API や製品など) で適用されるポリシーとアクセス制御を意味します。
次の手順
API Management の詳細情報: