Azure AI Search でロールベースのアクセス制御を有効または無効にする
- [アーティクル]
-
-
Azure AI 検索 では、既定でキーベースの認証が使用されますが、Azure ロールベースのアクセス制御 (RBAC) を通じて、すべてのコントロール プレーンおよびデータ プレーン操作に対する Microsoft Entra ID 認証と認可が完全にサポートされます。
Azure AI Search への認可済みデータ プレーン アクセスに対するロールを割り当てる前に、検索サービスでロールベースのアクセス制御を有効にする必要があります。 サービス管理 (コントロール プレーン) のロールは組み込まれており、有効または無効にすることはできません。
Note
"データ プレーン" とは、検索サービス エンドポイントに対する操作 (たとえばインデックス作成やクエリ)、またはその他の検索サービス REST API または同等の Azure SDK クライアント ライブラリで指定される操作を指します。 "コントロール プレーン" とは、Azure リソース管理 (たとえば検索サービスの作成や構成) を指します。
前提条件
データ プレーン操作に対してロールベースのアクセスを有効にする
この手順では、OAuth2 アクセス トークンを提供するデータ要求の承認ヘッダーを認識するように検索サービスを構成します。
データ プレーンのロールを有効にすると、変更はすぐに有効になりますが、ロールを割り当てる前に数秒待ってください。
未承認の要求に対する既定のエラー モードは http401WithBearerChallenge です。 または、エラー モードを http403に設定することもできます。
Azure portal にサインインし、検索サービス ページを開きます。
[設定] を選択した後、左側のナビゲーション ウィンドウで [キー] を選択 します。
現在キーを使用していて、クライアントをロールベースのアクセス制御に移行する時間が必要な場合は、[ロールベースの制御] または [両方] を選択します。
| オプション |
説明 |
| API キー |
(既定) 承認するには、要求ヘッダーに API キーが必要です。 |
| ロールベースのアクセス制御 |
タスクを完了するには、ロール割り当てのメンバーシップが必要です。 また、要求に Authorization ヘッダーも必要です。 |
| 両方 |
API キーまたはロールベースのアクセス制御を使用すれば要求は有効ですが、両方を同じ要求で指定すると、API キーが使用されます。 |
管理者として、ロールのみのアプローチを選択した場合は、ユーザー アカウントにデータ プレーン ロールを割り当て、Azure portal 内でのデータ プレーン操作に対する完全な管理アクセス権を復元します。 検索サービス共同作成者、検索インデックス データ共同作成者、検索インデックス データ閲覧者を含むロール。 同等のアクセス権が必要な場合は、最初の 2 つのロールが必要です。
ロールの割り当てが有効になるまでに 5 分から 10 分かかることがあります。 これが完了するまでは、データ プレーン操作に使用される Azure portal ページには次のメッセージが表示されます。
ロールのみをサポートするには、次のスクリプトを実行します。
az search service update `
--name YOUR-SEARCH-SERVICE-NAME `
--resource-group YOUR-RESOURCE-GROUP-NAME `
--disable-local-auth
または、次のスクリプトを実行して、キーとロールの両方をサポートします。
az search service update `
--name YOUR-SEARCH-SERVICE-NAME `
--resource-group YOUR-RESOURCE-GROUP-NAME `
--aad-auth-failure-mode http401WithBearerChallenge `
--auth-options aadOrApiKey
詳細については、Azure CLI を使用した Azure AI 検索 サービスの管理に関するページを参照してください。
認証の種類をロールのみに設定するには、次のコマンドを実行します。
Set-AzSearchService `
-Name YOUR-SEARCH-SERVICE-NAME `
-ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
-DisableLocalAuth 1
または、次のコマンドを実行して、キーとロールの両方をサポートします。
Set-AzSearchService `
-Name YOUR-SEARCH-SERVICE-NAME `
-ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
-AuthOption AadOrApiKey
詳細については、「PowerShell を使用して Azure AI 検索 サービスを管理する」を参照してください。
Management REST API のサービスの作成または更新を使用して、ロールベースのアクセス制御についてサービスを構成します。
Management REST API 呼び出しはすべて、Microsoft Entra ID を介して認証されます。 認証された要求を設定する方法については、REST を使用した Azure AI Search の管理に関するページを参照してください。
現在の構成を確認できるように、サービス設定を取得します。
GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
PATCH を使用し、サービス構成を更新します。 次の変更により、キー アクセスとロールベース アクセスの両方が有効になります。 ロールのみの構成が必要な場合、API キーの無効化に関するセクションを参照してください。
"properties" の "authOptions" を "aadOrApiKey" に設定します。 "authOptions" を設定するには、"disableLocalAuth" プロパティを false にする必要があります。
必要に応じて、"aadAuthFailureMode" を設定して、認証に失敗した場合、403 ではなく 401 を返すかどうかを指定します。 有効な値は "http401WithBearerChallenge" または "http403" です。
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
"properties": {
"disableLocalAuth": false,
"authOptions": {
"aadOrApiKey": {
"aadAuthFailureMode": "http401WithBearerChallenge"
}
}
}
}
ロールベースのアクセス制御を無効にする
データ プレーン操作のロールベースのアクセス制御を無効にし、代わりにキーベースの認証を使用することができます。 たとえば、アクセス許可の問題を除外するために、テスト ワークフローの一部としてこれを行うことができます。
ロールベースのアクセスを有効にするには、前に実行した手順を元に戻します。
Azure portal にサインインし、検索サービス ページを開きます。
[設定] を選択した後、左側のナビゲーション ウィンドウで [キー] を選択 します。
[API Keys](API キー) を選択します。
API キー認証を無効にする
組み込みのロールと Microsoft Entra 認証のみを使用している場合は、サービスでキー アクセス (ローカル認証) を無効にすることができます。 API キーを無効にすると、ヘッダーで API キーを渡すデータ関連のすべての要求を検索サービスが拒否します。
管理 API キーは無効にできますが、削除することはできません。 クエリ API キーは削除できます。
セキュリティ機能を無効にするには、所有者か共同作成者のアクセス許可が必要です。
Azure portal で検索サービスに移動します。
左側のナビゲーション ウィンドウで、[キー] を選択します。
[ロールベースのアクセス制御] を選択します。
変更はすぐに有効になりますが、テストする前に数秒待ってください。 所有者、サービス管理者、または共同管理者のメンバーとしてロールを割り当てるアクセス許可があると仮定すると、ポータル機能を使用してロールベースのアクセスをテストできます。
キーベースの認証を無効にするには、-disableLocalAuth を true に設定します。 これは、前のセクションで示した "enable roles only" スクリプトと同じ構文です。
az search service update `
--name YOUR-SEARCH-SERVICE-NAME `
--resource-group YOUR-RESOURCE-GROUP-NAME `
--disable-local-auth
キー認証を再度有効にするには、-disableLocalAuth を false に設定します。 検索サービスでは、要求での API キーの受け入れが自動的に再開されます (機能が指定されている場合)。
詳細については、Azure CLI を使用した Azure AI 検索 サービスの管理に関するページを参照してください。
キーベースの認証を無効にするには、DisableLocalAuth を true に設定します。 これは、前のセクションで示した "enable roles only" スクリプトと同じ構文です。
Set-AzSearchService `
-Name YOUR-SEARCH-SERVICE-NAME `
-ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
-DisableLocalAuth 1
キー認証を再度有効にするには、DisableLocalAuth を false に設定します。 検索サービスでは、要求での API キーの受け入れが自動的に再開されます (機能が指定されている場合)。
詳細については、「PowerShell を使用して Azure AI 検索 サービスを管理する」を参照してください。
キーベースの認証を無効にするには、"disableLocalAuth" を true に設定します。
現在の構成を確認できるように、サービス設定を取得します。
GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
PATCH を使用し、サービス構成を更新します。 次の修正により、"authOptions" が null に設定されます。
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
"properties": {
"disableLocalAuth": true
}
}
キー認証を再度有効にするには、"disableLocalAuth" を false に設定します。 検索サービスでは、要求での API キーの受け入れが自動的に再開されます (機能が指定されている場合)。
ロールベースのアクセス制御の効果
ロールベースのアクセス制御では、一部の要求の待機時間が長くなる可能性があります。 サービス リソース (インデックス、インデクサー、スキルセットなど) とサービス プリンシパルの一意の組み合わせごとに、認可チェックがトリガーされます。 これらの認可チェックにより、要求あたり最大 200 ミリ秒の待機時間が追加される可能性があります。
まれに、多数の異なるサービス プリンシパルから要求が送信され、すべてが異なるサービス リソース (インデックス、インデクサーなど) を対象としている場合、認可チェックによって調整が発生する可能性があります。 調整が発生するのは、検索サービス リソースとサービス プリンシパルの一意の組み合わせが 1 秒間に何百も使われた場合のみです。
次のステップ
