ロールベースのアクセス制御を使用して Azure AI Search に接続する

1. Azure portal にサインインします。

2. お使いの検索サービスに移動します。

3. 左側のナビゲーション ペインで [アクセス制御 (IAM)] を選択します。

4. [+ 追加]>[ロール割り当ての追加] の順に選択します。

5. 該当するロールを選びます。

   • 所有者 (クエリのアクセス許可を除く、すべてのデータ プレーン操作とコントロール プレーン操作へのフル アクセス)
   • 共同作成者 (ロールを割り当てるアクセス許可を除き、所有者と同じ)
   • 閲覧者 (メトリックの監視と表示に使用可能)

6. [メンバー] タブで Microsoft Entra ユーザーまたはグループの ID を選びます。

7. [確認と 割り当て] タブで、 [確認と割り当て] を選択して ロールを割り当てます。

PowerShell を使用してロールを割り当てる場合は、New-AzRoleAssignment を呼び出して、Azure のユーザーまたはグループの名前と、割り当てのスコープを指定します。

この例では、検索サービスにスコープを設定したロールの割り当てを作成します。

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

1. Azure portal にサインインします。

2. お使いの検索サービスに移動します。

3. 左側のナビゲーション ペインで [アクセス制御 (IAM)] を選択します。

4. [+ 追加]>[ロール割り当ての追加] の順に選択します。

   

5. ロールを選択します。

   • Search Service Contributor (インデックス、インデクサー、スキルセット、その他の最上位オブジェクトに対する create-read-update-delete 操作)
   • Search インデックス データ共同作成者 (ドキュメントの読み込みとインデックス作成ジョブの実行)
   • Search インデックス データ閲覧者 (インデックスのクエリ)

   フル アクセスを提供するロールのもう 1 つの組み合わせは、共同作成者または所有者、および Search インデックス データ閲覧者です。

6. [メンバー] タブで Microsoft Entra ユーザーまたはグループの ID を選びます。

7. [確認と 割り当て] タブで、 [確認と割り当て] を選択して ロールを割り当てます。

8. 他のロールに対しても繰り返します。 ほとんどの開発者には、3 つがすべて必要です。

PowerShell を使用してロールを割り当てる場合は、New-AzRoleAssignment を呼び出して、Azure のユーザーまたはグループの名前と、割り当てのスコープを指定します。

この例では、検索サービスにスコープを設定したロールの割り当てを作成します。

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

この例では、特定のインデックスにスコープを設定したロールの割り当てを作成します。

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

1. Azure portal にサインインします。

2. お使いの検索サービスに移動します。

3. 左側のナビゲーション ペインで [アクセス制御 (IAM)] を選択します。

4. [+ 追加]>[ロール割り当ての追加] の順に選択します。

5. Search インデックス データ閲覧者ロールを選択します。

6. [メンバー] タブで Microsoft Entra ユーザーまたはグループの ID を選びます。 別のサービスのアクセス許可を設定する場合は、システム マネージド ID またはユーザー マネージド ID を使用している可能性があります。 ロールの割り当てがサービス ID 向けの場合は、そのオプションを選択します。

7. [確認と 割り当て] タブで、 [確認と割り当て] を選択して ロールを割り当てます。

PowerShell を使用してロールを割り当てる場合は、New-AzRoleAssignment を呼び出して、Azure のユーザーまたはグループの名前と、割り当てのスコープを指定します。

1. サブスクリプション ID、Search Service リソース グループ、Search Service 名を取得します。

2. Azure OpenAI などの Azure サービスのオブジェクト識別子を取得します。

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. ロール定義を取得し、アクセス許可を確認して、これが目的のロールであることを確認します。

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. プレースホルダーを有効な値で置き換えて、ロールの割り当てを作成します。

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME
   

5. 特定のインデックスにスコープを設定したロールの割り当ての例を次に示します。

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME
   

1. Azure portal にサインインします。

2. お使いの検索サービスに移動します。

3. [概要] ページで、[インデックス] タブを選択します。

   • Search サービス共同作成者は、任意のオブジェクトを表示および作成できますが、ドキュメントを読み込んだり、インデックスに対してクエリを実行したりすることはできません。 権限を確認するには、検索インデックスを作成します。

   • Search インデックス データ共同作成者は、ドキュメントを読み込むことができます。 ポータルでは [データのインポート] ウィザードの外部には [ドキュメントの読み込み] オプションはありませんが、[インデクサーのリセットと実行] を行うことでドキュメントの読み込みアクセス許可を確認できます。

   • 検索インデックス データ閲覧者は、インデックスに対してクエリを実行できます。 権限を確認するには、Search エクスプローラーを使用します。 クエリを送信し、結果を表示できるようにする必要がありますが、インデックス定義を表示できたり、作成できたりする必要はありません。

このアプローチは、REST クライアント拡張機能を備えた Visual Studio Code を前提としています。

1. Azure CLI のコマンド シェルを開き、Azure サブスクリプションにサインインします。

   az login
   

2. テナント ID とサブスクリプション ID を取得します。 この ID は、今後の手順で変数として使用されます。

   az account show
   

3. アクセス トークンを取得します。

   az account get-access-token --query accessToken --output tsv
   

4. Visual Studio Code の新しいテキスト ファイルに、次の変数を貼り付けます。

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. 指定した変数を使用する要求を貼り付けて送信します。 "検索インデックス データ閲覧者" であればクエリを送信できます。 サポートされている API バージョンを使用できます。

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

特定の環境のトークンを取得する方法の詳細については、「REST API を使用して Azure AI 検索サービスを管理する」および「Microsoft ID プラットフォームの認証ライブラリ」を参照してください。

1. Azure.Search.Documents パッケージを使用します。

2. トークン認証用に Azure.Identity for .NET を使用します。 Microsoft ではほとんどのシナリオで DefaultAzureCredential() を推奨します。

3. DefaultAzureCredential() を使用したクライアント接続の例を次に示します。

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

4. クライアント シークレット資格情報の別の使用例を次に示します。

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

1. azure.search.documents (Azure SDK for Python) を使用します。

2. トークン認証用に Azure.Identity for Python を使用します。

3. Python クライアントがサーバー側で実行しているアプリケーションである場合、DefaultAzureCredential を使用します。 アプリがブラウザーで実行している場合、対話型の認証を有効にします。

4. 次に例を示します。

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

1. @azure/search-documents (Azure SDK for JavaScript) バージョン 11.3 を使用します。

2. トークン認証用に Azure.Identity for JavaScript を使用します。

3. React を使用している場合は、Search に対する Microsoft Entra 認証に InteractiveBrowserCredential を使用します。 詳細については、「@azure/identity を使用する場合」を参照してください。

1. azure-search-documents (Azure SDK for Java) を使用します。

2. トークン認証用に Azure.Identity for Java を使用します。

3. Azure で実行するアプリには DefaultAzureCredential をお勧めします。

次の手順は、「Azure portal を使用して Azure カスタム ロールを作成または更新する」から派生したものです。 検索サービス ページでは、既存のロールからの複製がサポートされています。

次の手順では、インデックスを名前で一覧表示する権限を追加して検索クエリの権限を増強したカスタム ロールを作成します。 通常、インデックスの一覧表示は管理者用の機能とされています。

1. Azure portal で検索サービスに移動します。

2. 左側のナビゲーション ペインで [アクセス制御 (IAM)] を選択します。

3. アクション バーで、[ロール] を選択します。

4. [検索インデックス データ閲覧者] (または別のロール) を右クリックし、[複製] を選択して [カスタム ロールを作成する] ウィザードを開きます。

5. [基本] タブでカスタム ロールの名前 ("Search Index Data Explorer" など) を指定し、[次へ] をクリックします。

6. [アクセス許可] タブで [アクセス許可の追加] を選択します。

7. [アクセス許可の追加] タブで、Microsoft Search タイルを検索して選択します。

8. カスタム ロールのアクセス許可を設定します。 ページの上部で、既定の [アクション] の選択を使用して以下を行います。

   • Microsoft.Search/operations で、[Read : List all available operations]\(読み取り: 使用可能なすべての操作を一覧表示する\) を選択します。
   • Microsoft.Search/searchServices/indexes で、[Read: Read Index]\(読み取り: インデックスの読み取り\) を選択します。

9. 同じページの [データ アクション] に切り替え、Microsoft.Search/searchServices/indexes/documents で [Read : Read Documents]\(読み取り: ドキュメントの読み取り\) を選択します。

   JSON の定義は、次の例のようになります。

   {
    "properties": {
        "roleName": "search index data explorer",
        "description": "",
        "assignableScopes": [
            "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
      }
    }
   

10. [確認および作成] を選択してロールを作成します。 これで、ユーザーとグループをロールに割り当てることがきるようになりました。

この PowerShell の例は、検索インデックス データ閲覧者の複製に、すべてのインデックスを名前で一覧表示することができる権限を追加したカスタム ロールを作成するための JSON 構文を示しています。

1. アトミック アクセス許可の一覧を確認して、必要なものを判断します。 この例には、次のものが必要です。

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. カスタム ロールを作成する PowerShell セッションを設定します。 詳細な手順については、Azure PowerShell の記事を参照してください。

3. JSON ドキュメントとしてロール定義を用意します。 PowerShell を使ってカスタム ロールを作成する構文の例を次に示します。

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

1. アトミック アクセス許可の一覧を確認して、必要なものを判断します。

2. 手順については、「REST API を使用して Azure カスタム ロールを作成または更新する」を参照してください。

3. ロールを複製または作成するか、JSON を使ってカスタム ロールを指定します (JSON の構文については、[PowerShell] タブを参照してください)。

1. アトミック アクセス許可の一覧を確認して、必要なものを判断します。

2. 手順については、「Azure CLI を使用して Azure カスタム ロールを作成または更新する」を参照してください。

3. ロールを複製または作成するか、JSON を使ってカスタム ロールを指定します (JSON の構文については、[PowerShell] タブを参照してください)。