Azure AI Search でロールベースのアクセス制御を有効または無効にする
- [アーティクル]
-
-
Azure AI Search への承認されたアクセスのロールを割り当てる前に、検索サービスでロールベースのアクセス制御を有効にします。
データ プレーン操作では、ロールベースのアクセスは省略可能ですが、より安全なオプションとして推奨されます。 代替策としてはキーベースの認証があり、こちらは既定のものです。
サービス管理 (コントロール プレーン) のロールは組み込まれており、有効または無効にすることはできません。
Note
データ プレーン は、インデックス作成やクエリなどの検索サービス エンドポイントに対する操作、または Search REST API または同等の Azure SDK クライアント ライブラリで指定されるその他の操作を意味します。
前提条件
データ プレーン操作に対してロールベースのアクセスを有効にする
この手順では、OAuth2 アクセス トークンを提供するデータ要求の承認ヘッダーを認識するように検索サービスを構成します。
データ プレーンのロールを有効にすると、変更はすぐに有効になりますが、ロールを割り当てる前に数秒待ってください。
未承認の要求に対する既定のエラー モードは http401WithBearerChallenge です。 または、エラー モードを http403に設定することもできます。
Azure portal にサインインし、検索サービス ページを開きます。
[設定] を選択した後、左側のナビゲーション ウィンドウで [キー] を選択 します。
現在キーを使用していて、クライアントをロールベースのアクセス制御に移行する時間が必要な場合は、[ロールベースの制御] または [両方] を選択します。
| オプション |
説明 |
| API キー |
(既定) 承認するには、要求ヘッダーに API キーが必要です。 |
| ロールベースのアクセス制御 |
タスクを完了するには、ロール割り当てのメンバーシップが必要です。 また、要求に Authorization ヘッダーも必要です。 |
| 両方 |
API キーまたはロールベースのアクセス制御を使用すれば要求は有効ですが、両方を同じ要求で指定すると、API キーが使用されます。 |
管理者として、ロールのみのアプローチを選択した場合は、ユーザー アカウントにデータ プレーン ロールを割り当て、Azure portal 内でのデータ プレーン操作に対する完全な管理アクセス権を復元します。 検索サービス共同作成者、検索インデックス データ共同作成者、検索インデックス データ閲覧者を含むロール。 同等のアクセス権が必要な場合は、3 つのロールすべてが必要です。
ロールの割り当てが有効となるには 5 分から 10 分かかる場合があります。 これが行われるまで、データ プレーン操作に使用されるポータル ページに次のメッセージが表示されます。
ロールのみをサポートするには、次のスクリプトを実行します。
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 秒間に何百も使われた場合のみです。
次のステップ
