API センターで API へのアクセスを承認する設定を構成できます。 これらの設定:
- API キーまたは OAuth 2.0 承認を使用して API 認証を有効にする
- インベントリ内の特定の API バージョンに特定の認証方法を関連付ける
- アクセス ポリシーを使用して、指定されたユーザーまたはグループによる API バージョンへの認証を管理する
- 承認されたユーザーが API センター ポータルで直接 API をテストできるようにする
注
この機能は現在プレビュー段階です。
[前提条件]
Azure サブスクリプション内の API センター。 まだ作成していない場合は、「クイック スタート: API センターを作成する」を参照してください。
API センターに少なくとも 1 つの API を登録します。 詳細については、「 チュートリアル: API インベントリに API を登録する」を参照してください。
API の環境とデプロイを構成します。 詳細については、「 チュートリアル: API の環境とデプロイを追加する」を参照してください。
API センター ポータルを設定します。 詳細については、「 API センター ポータルのセットアップ」を参照してください。
API キーまたは OAuth 2.0 クライアント シークレットを格納するための Azure キー コンテナー。 キー コンテナーを作成する手順については、「 キー コンテナーの作成」を参照してください。 キー コンテナーでは、Azure ロールベースのアクセス制御 (RBAC) アクセス許可モデルを使用する必要があります。
(Microsoft Entra ID を使用した OAuth 2.0 承認の場合)Azure サブスクリプションに関連付けられている Microsoft Entra テナントでアプリ登録を作成するためのアクセス許可。
オプション 1: API キー認証の設定を構成する
API キー認証をサポートする API の場合は、次の手順に従って API センターで設定を構成します。
1. Azure Key Vault に API キーを格納する
API キーを安全に管理するには、それを Azure Key Vault に格納し、API センターのマネージド ID を使用してキー コンテナーにアクセスします。
API キーをシークレットとしてキー コンテナーに格納するには、「 Key Vault でのシークレットの設定と取得」を参照してください。
API センターでマネージド ID を有効にする
このシナリオでは、API センターは マネージド ID を 使用してキー コンテナーにアクセスします。 ニーズに応じて、1 つのシステム割り当て、または 1 つ以上のユーザー割り当てのマネージド ID を有効にします。
次の例は、Azure portal を使用してシステム割り当てマネージド ID を有効にする方法を示しています。 大まかに言うと、構成手順はユーザー割り当てマネージド ID の場合も同様です。
- ポータルで、API Center に移動します。
- 左側のメニューの [セキュリティ] で、[マネージド ID] を選択します。
- [システム割り当て済み] を選択し、状態を [オン] に設定します。
- 保存 を選択します。
マネージド ID に Key Vault シークレット ユーザー ロールを割り当てる
API センターのマネージド ID に、 キー コンテナーの Key Vault シークレット ユーザー ロールを割り当てます。 次の手順では、Azure portal を使います。
- ポータルで、キー コンテナーに移動します。
- 左側のメニューで [アクセス制御 (IAM)] を選択します。
- [ロールの割り当ての追加] を選択します。
-
[ロールの割り当ての追加] ペインで、次のように値を設定します。
- [ロール] タブで [キー コンテナー シークレット ユーザー] を選択します。
- [メンバー] タブの [アクセスの割り当て] で、[マネージド ID]、[>を選択します。
- [マネージド ID の選択] ページ上で、前のセクション内で追加した API Center のシステム割り当てマネージド ID を選択します。 [選択] をクリックします。
- [レビュー + 割り当て] をもう一度選択します
2. API センターに API キー構成を追加する
ポータルで、API Center に移動します。
左側のメニューの [ガバナンス] で、[承認 (プレビュー)]>[+ 構成の追加] を選択します。
[ 構成の追加] ページで、値を次のように設定します。
設定 説明 タイトル 承認の名前を入力します。 説明 必要に応じて、承認の説明を入力します。 セキュリティ スキーム [API キー] を選択します。 API キーの場所 API 要求でのキーの表示方法を選択します。 使用可能な値は 、Header (要求ヘッダー) と Query (クエリ パラメーター) です。 API キー パラメーター名 API キーを含む HTTP ヘッダーまたはクエリ パラメーターの名前を入力します。 例: x-api-keyAPI キー Key Vault シークレットの参照 [ 選択 ] をクリックし、保存したサブスクリプション、キー コンテナー、シークレットを選択します。 例: https://<key-vault-name>.vault.azure.net/secrets/<secret-name>を選択してを作成します。
オプション 2: OAuth 2.0 承認の設定を構成する
OAuth 2.0 承認をサポートする API の場合は、次の手順に従って API センターで認証設定を構成します。 次の OAuth 2.0 承認フローのいずれかまたは両方の設定を構成できます。
- PKCE を使用した承認コード フロー (Code Exchange の証明キー) - このフローは、API センター ポータルなどのブラウザーでユーザーを認証する場合に推奨されます。
- クライアント資格情報フロー - このフローは、データにアクセスするために特定のユーザーのアクセス許可を必要としないアプリケーションに推奨されます。
1. OAuth 2.0 アプリを作成する
OAuth 2.0 承認の場合は、Azure サブスクリプションに関連付けられている Microsoft Entra テナントなどの ID プロバイダーにアプリ登録を作成します。 正確な作成手順は、使用する ID プロバイダーによって異なります。
次の例は、Microsoft Entra ID でアプリ登録を作成する方法を示しています。
- テナントで十分なアクセス許可を持つアカウントで Azure portal にサインインします。
- Microsoft Entra ID>+ New registration に移動します。
- [ アプリケーションの登録 ] ページで、アプリケーション登録設定を入力します。
- [ 名前] に、アプリのわかりやすい名前を入力します。
- [サポートされているアカウントの種類] で、シナリオに合ったオプション (この組織のディレクトリ内のアカウントのみ (シングル テナント) など) を選択します。
- (承認コード フローの場合) [リダイレクト URI] で、[ シングルページ アプリケーション (SPA)] を選択し、URI を設定します。 次の形式で、API センター ポータルのデプロイの URI を入力します。
https://<service-name>.portal.<___location>.azure-api-center.ms.<service name>と<___location>を API センターの名前とデプロイ先の場所に置き換えます(例:https://myapicenter.portal.eastus.azure-api-center.ms - 登録 を選択します。
- 左側のメニューの [ 管理] で[ 証明書とシークレット] を選択し、[ + 新しいクライアント シークレット] を選択します。
- [Description]\(説明\) を入力します。
- [有効期限] のオプションを選択します。
- [] を選択し、[] を追加します。
- ページを離れる前に、クライアント シークレットの 値 をコピーします。 これは、次のセクションで必要になります。
- 必要に応じて、アプリの登録に API スコープを追加します。 詳細については、「 Web API を公開するようにアプリケーションを構成する」を参照してください。
API センターで OAuth 2.0 承認を構成する場合は、アプリ登録から次の値が必要になります。
- アプリ登録の [概要] ページのアプリケーション (クライアント) ID と、前にコピーしたクライアント シークレット。
- アプリ登録の [概要>Endpoints ] ページの次のエンドポイント URL:
- OAuth2.0 承認エンドポイント (v2) - Microsoft Entra ID の承認エンドポイント
- OAuth 2.0 トークン エンドポイント (v2) - Microsoft Entra ID のトークン エンドポイントとトークン更新エンドポイント
- アプリ登録で構成されたすべての API スコープ。
2. クライアント シークレットを Azure Key Vault に格納する
シークレットを安全に管理するには、それを Azure Key Vault に格納し、API センターのマネージド ID を使用してキー コンテナーにアクセスします。
API キーをシークレットとしてキー コンテナーに格納するには、「 Key Vault でのシークレットの設定と取得」を参照してください。
API センターでマネージド ID を有効にする
このシナリオでは、API センターは マネージド ID を 使用してキー コンテナーにアクセスします。 ニーズに応じて、1 つのシステム割り当て、または 1 つ以上のユーザー割り当てのマネージド ID を有効にします。
次の例は、Azure portal を使用してシステム割り当てマネージド ID を有効にする方法を示しています。 大まかに言うと、構成手順はユーザー割り当てマネージド ID の場合も同様です。
- ポータルで、API Center に移動します。
- 左側のメニューの [セキュリティ] で、[マネージド ID] を選択します。
- [システム割り当て済み] を選択し、状態を [オン] に設定します。
- 保存 を選択します。
マネージド ID に Key Vault シークレット ユーザー ロールを割り当てる
API センターのマネージド ID に、 キー コンテナーの Key Vault シークレット ユーザー ロールを割り当てます。 次の手順では、Azure portal を使います。
- ポータルで、キー コンテナーに移動します。
- 左側のメニューで [アクセス制御 (IAM)] を選択します。
- [ロールの割り当ての追加] を選択します。
-
[ロールの割り当ての追加] ペインで、次のように値を設定します。
- [ロール] タブで [キー コンテナー シークレット ユーザー] を選択します。
- [メンバー] タブの [アクセスの割り当て] で、[マネージド ID]、[>を選択します。
- [マネージド ID の選択] ページ上で、前のセクション内で追加した API Center のシステム割り当てマネージド ID を選択します。 [選択] をクリックします。
- [レビュー + 割り当て] をもう一度選択します
3. API センターに OAuth 2.0 承認を追加する
ポータルで、API Center に移動します。
左側のメニューの [ガバナンス] で、[承認 (プレビュー)]>[+ 構成の追加] を選択します。
[ 構成の追加] ページで、次のように値を設定します。
注
ID プロバイダーで以前に作成したアプリの登録に基づいて設定を構成します。 Microsoft Entra ID を使用している場合は、アプリ登録の [概要] ページでクライアント ID を見つけ、[概要>エンドポイント] ページで URL エンドポイントを見つけます。
設定 説明 タイトル 承認の名前を入力します。 説明 必要に応じて、承認の説明を入力します。 セキュリティ スキーム [OAuth2] を選択します。 クライアント ID ID プロバイダーで作成したアプリのクライアント ID (GUID) を入力します。 クライアント シークレット [ 選択 ] をクリックし、保存したサブスクリプション、キー コンテナー、およびクライアント シークレットを選択します。
例:https://<key-vault-name>.vault.azure.net/secrets/<secret-name>Authorization URL (承認 URL) ID プロバイダーの OAuth 2.0 承認エンドポイントを入力します。
Microsoft Entra ID の例:https://login.microsoftonline.com/<tenant>/oauth2/v2.0/authorizeToken URL (トークン URL) ID プロバイダーの OAuth 2.0 トークン エンドポイントを入力します。
Microsoft Entra ID の例:https://login.microsoftonline.com/<tenant>/oauth2/v2.0/tokenURL の更新 ID プロバイダーの OAuth 2.0 トークン更新エンドポイントを入力します。 ほとんどのプロバイダーでは、トークン URL と同じです
Microsoft Entra ID の例:https://login.microsoftonline.com/<tenant>/oauth2/v2.0/tokenOAuth2 フロー 使用する OAuth 2.0 フローの 1 つまたは両方を選択します。 使用可能な値は 、承認コード (PKCE) と クライアント資格情報です。 スコープ API 用に構成された 1 つ以上の API スコープをスペースで区切って入力します。 スコープが構成されていない場合は、「 .default」と入力します。[作成] を選択して構成を保存します。
API バージョンに認証構成を追加する
API キーまたは OAuth 2.0 フローの設定を構成した後、API センターの API バージョンに API キーまたは OAuth 2.0 構成を追加します。
- ポータルで、API Center に移動します。
- 左側のメニューにある [資産] で、[API] を選択します。
- 承認構成を関連付ける API を選択します。
- 左側のメニューの [ 詳細] で、[ バージョン] を選択します。
- 認証構成を追加する API バージョンを選択します。
- 左側のメニューの [ 詳細] で、[ アクセスの管理 (プレビュー)]>+ [認証の追加] を選択します。
- [ 認証の追加] ページで、関連付ける使用可能な 認証構成 を選択します。
- を選択してを作成します。
注
API バージョンには、複数の認証構成を追加できます。 たとえば、API でサポートされている場合は、API キーと OAuth 2.0 の両方の構成を同じ API バージョンに追加できます。 同様に、同じ構成を複数の API バージョンに追加できます。
特定のユーザーまたはグループによるアクセスを管理する
組織内の特定のユーザーまたはグループによる API バージョンの認証構成へのアクセスを管理できます。 そのためには、API バージョンの特定の認証構成をスコープとする API Center 資格情報アクセス閲覧者 ロールをユーザーまたはグループに割り当てるアクセス ポリシーを構成します。 これは、たとえば、特定のユーザーのみが API キーまたは OAuth 2.0 フローを使用して API センター ポータルで API をテストできるようにする場合に便利です。
ポータルで、API Center に移動します。
認証構成を追加した API バージョンに移動します (前のセクションを参照)。
左側のメニューの [ 詳細] で、[ アクセスの管理 (プレビュー)] を選択します。
アクセスを管理する認証構成の行の末尾にある [ アクセス ポリシーの編集] ドロップダウンを選択します。
[ アクセスの管理 ] ページで、[ + > ユーザーの追加 ] または [ + > グループの追加] を選択します。
追加するユーザー (またはグループ) を検索して選択します。 複数の項目を選択できます。
[選択] をクリックします。
ヒント
アクセス ポリシーからユーザーまたはグループを削除することもできます。 [ アクセスの管理 ] ページで、ユーザーまたはグループのコンテキスト (...) メニューで [ 削除 ] を選択します。
API センター ポータルで API をテストする
API センター ポータルを使用して、認証とユーザー アクセス用に構成した API をテストできます。
ヒント
特定のユーザーが API センター ポータルで特定の API をテストできるようにするだけでなく、API の 可視性設定 を構成することもできます。 ポータルの可視性設定は、サインインしているすべてのユーザーに表示される API を制御します。
ポータルで、API Center に移動します。
左側のメニューの API センター ポータルで、[ ポータルの設定] を選択します。
[ API センター ポータルの表示] を選択します。
API センター ポータルで、テストする API を選択します。
認証方法が構成されている API のバージョンを選択します。
[ オプション] で、[ ドキュメントの表示] を選択します。
API で操作を選択し、[ この API を試す] を選択します。
開いたウィンドウで、認証設定を確認します。 API にアクセスできる場合は、[ 送信 ] を選択して API を試します。
操作が成功すると、
200 OK応答コードと応答本文が表示されます。 操作が失敗すると、エラー メッセージが表示されます。
