Microsoft Entra ID でキーレス認証を構成する

Azure AI Foundry Models では、Microsoft Entra ID を使用したキーレス承認がサポートされます。 キーレス認証により、セキュリティが強化され、ユーザー エクスペリエンスが簡素化され、運用の複雑さが軽減され、最新の開発に対する堅牢なコンプライアンス サポートが提供されます。 これは、セキュリティで保護されたスケーラブルな ID 管理ソリューションを導入する組織にとって強力な選択肢となります。

この記事では、Azure AI Foundry Models で推論用に Microsoft Entra ID を構成する方法について説明します。

Azure 内のリソースのコンテキストにおけるロールを理解する

Microsoft Entra ID は、認証にロールベースのアクセス制御 (RBAC) の考え方を使用しています。 ロールは、クラウド リソースへのアクセスを管理するうえで中心的な役割を果たします。 ロールは基本的に、特定の Azure リソースに対して実行できる操作を定義するアクセス許可のコレクションです。 ユーザー、グループ、サービス プリンシパル、またはマネージド ID (総称してセキュリティ プリンシパル) にロールを割り当てることで、Azure 環境内での特定のリソースへのアクセスを制御します。

ロールを割り当てるときは、セキュリティ プリンシパル、ロールの定義、スコープを指定します。 この組み合わせはロールの割り当てと呼ばれます。 Azure AI Foundry Models は、Azure AI Services リソースの機能であるため、その特定のリソースに割り当てられたロールが推論のアクセスを制御します。

リソースへのアクセスには次の 2 種類があります。

• 管理アクセス: リソースの管理に関連する操作。 通常、リソースの状態と構成を変更します。 Azure では、それらの操作はコントロール プレーン操作であり、Azure portal、Azure CLI、またはコードとしてのインフラストラクチャを使用して実行できます。 例としては、新しいモデル デプロイの作成、コンテンツ フィルタリングの構成の変更、提供されるモデルのバージョンの変更、デプロイの SKU の変更などがあります。

• 開発者アクセス: リソースの消費に関連する操作。 たとえば、Chat Completions API の呼び出しが挙げられます。 ただし、ユーザーはリソースの状態や構成を変更できません。

Azure では、管理操作は常に Microsoft Entra ID を使用して実行されます。 Cognitive Services 共同作成者などのロールを使用すれば、これらの操作を実行できます。 一方、開発者の操作は、アクセス キーまたは Microsoft Entra ID のどちらか、あるいはその両方を使用して実行できます。 Cognitive Services ユーザーなどのロールを使用すれば、それらの操作を実行できます。

推論のために Azure AI Foundry Models への開発者アクセスを構成するには、次の手順に従います。

[前提条件]

この記事を完了するには、以下が必要です。

• Azure サブスクリプション。 GitHub モデルを使用している場合は、エクスペリエンスをアップグレードし、プロセスで Azure サブスクリプションを作成できます。 その場合は、 GitHub モデルから Azure AI Foundry モデルへのアップグレード に関するページを参照してください。

• Azure AI Foundry リソース (旧称 Azure AI Services)。 詳細については、「 Azure AI Foundry リソースの作成」を参照してください。

• エンドポイント URL とキー。

  

• Microsoft.Authorization/roleAssignments/writeロールベースのアクセス制御など、Microsoft.Authorization/roleAssignments/delete アクセス許可および アクセス許可を持つアカウント。

• ロールを割り当てるには、次の 3 つの要素を指定する必要があります。

  • セキュリティ プリンシパル: ユーザー アカウントなど。
  • ロールの定義: Cognitive Services ユーザー ロール。
  • スコープ: Azure AI サービス リソース。

• Cognitive Services ユーザー ロールを使用する代わりにカスタム ロール定義を作成する場合は、ロールに次のアクセス許可があることを確認します。

  {
    "permissions": [
      {
        "dataActions": [
          "Microsoft.CognitiveServices/accounts/MaaS/*"
        ]
      }
    ]
  }
  

推論のために Microsoft Entra ID を構成する

推論のために Microsoft Entra ID を構成するには、次の手順に従います。

1. Azure portal に移動し、使用している Azure AI Foundry (以前の既知の Azure AI サービス) リソースを見つけます。 プロジェクトまたはハブで Azure AI Foundry を使用している場合は、次の方法でそこに移動できます。

   1. Azure AI Foundry ポータルに移動します。

   2. ランディング ページで、[管理センターを開く] を選択します。

   3. [ 接続済みリソース ] セクションに移動し、構成する Azure AI Foundry (旧称 Azure AI Services) リソースへの接続を選択します。 一覧にない場合は、[すべて表示] を選択して完全な一覧を表示します。

      

   4. [接続の詳細] セクションの [リソース] で、Azure リソースの名前を選択します。 新しいページが開きます。

   5. これで、Azure portal に移動し、リソース自体のあらゆる側面を管理できるようになりました。

      

2. 左側のペインで、アクセスの制御 (IAM) を選択し、追加>ロールの割り当て追加を選択します。

   

   ヒント

   [自分のアクセスの表示] オプションを使用して、どのロールが既に自分に割り当てられているかを確認します。

3. [職務権限ロール]で、「Cognitive Services ユーザー」と入力します。 ロールの一覧が絞り込まれます。

   

4. ロールを選択し、[次へ] を選択します。

5. [メンバー]で、アクセス権を付与するユーザーまたはグループを選択します。 セキュリティ グループの方が管理と保守が容易なので、可能な限りセキュリティ グループを使用することをお勧めします。

   

6. [次へ] を選択し、ウィザードを終了します。

7. 選択したユーザーは、推論のために Microsoft Entra ID を使用できるようになりました。

   ヒント

   Azure ロールの割り当ての反映には最大で 5 分かかる場合があることに留意してください。 セキュリティ グループを使用する場合、セキュリティ グループへのユーザーの追加または削除はすぐに反映されます。

既にキーを使用できるユーザーの場合は、引き続きキーベースのアクセスが可能であることに注意してください。 キーを無効にする場合は、Azure portal の左側のナビゲーションで、[リソース管理]>[キーとエンドポイント]>[Key1 の再生成] と [Key2 の再生成] を選択します。

コードで Microsoft Entra ID を使用する

リソースで Microsoft Entra ID を構成したら、推論エンドポイントを使用するときにそれを利用できるように、コードを更新する必要があります。 次の例は、チャット補完モデルを使用する方法を示しています。

pip install azure-ai-inference

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

npm install @azure-rest/ai-inference

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    clientOptions,
);

dotnet add package Azure.AI.Inference --prerelease

dotnet add package Azure.Identity

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

TokenCredential credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions.
);

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.3</version>
</dependency>

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

Microsoft Entra ID を使用する場合の資格情報のオプション

DefaultAzureCredential は、Microsoft Entra ID への認証を行うための、独自の順序付けられたメカニズムのシーケンスです。 各認証メカニズムは、TokenCredential クラスから派生したクラスであり、資格情報と呼ばれます。 実行時に、DefaultAzureCredential は最初の資格情報を使用して認証を試みます。 その資格情報がアクセス トークンの取得に失敗した場合は、アクセス トークンが正常に取得されるまで、シーケンス内の次の資格情報が試行されます。 これにより、アプリは環境固有のコードを記述することなく、異なる環境で異なる資格情報を使用できます。

上記のコードをローカルの開発ワークステーション上で実行すると、環境変数内でアプリケーション サービス プリンシパルが検索されるか、ローカルにインストールされた開発者ツール (Visual Studio など) で開発者の資格情報のセットが検索されます。 どちらの方法も、ローカル開発中に Azure リソースに対してアプリを認証するために使用できます。

Azure にデプロイすると、この同じコードで他の Azure リソースに対してアプリを認証することもできます。 DefaultAzureCredential は、他のサービスに対して自動的に認証する環境設定とマネージド ID 構成を取得できます。

ベスト プラクティス

• 運用環境で確定的な資格情報を使用する: 運用環境では、DefaultAzureCredential から次のいずれかの確定的なソリューションに移行することを強くお勧めします。

  • 特定のTokenCredential実装、例えばManagedIdentityCredentialのようなもの。 オプションについては、派生リストを参照してください。
  • アプリが動作する Azure 環境向けに最適化された、簡素化された ChainedTokenCredential の実装。 ChainedTokenCredential は基本的に、運用用の ManagedIdentity や開発用の VisualStudioCredential など、使用可能な資格情報オプションの特定の許可リストを作成します。

• 可能であれば、コードが実行されている Azure リソースに対して、システム割り当てまたはユーザー割り当てのマネージド ID を構成します。 それらの特定の ID への Microsoft Entra ID アクセスを構成します。

トラブルシューティング

トラブルシューティングを行う前に、適切なアクセス許可が割り当てられていることを確認します。

1. Azure portal に移動し、使用している Azure AI Foundry (以前の既知の Azure AI サービス) リソースを見つけます。

2. 左側のウィンドウで、[ アクセス制御 (IAM)] を選択し、[ アクセスの確認] を選択します。

3. サービスへの接続に使用しているユーザーまたは ID の名前を入力します。

4. Cognitive Services ユーザーロールが一覧表示されていることを確認します (または、「前提条件」で説明されているように、必要なアクセス許可を含むロール)。

   Von Bedeutung

   所有者や共同作成者などのロールは、Microsoft Entra ID 経由でアクセスを提供しません。

5. 一覧にない場合は、続行する前に、このガイドの手順に従ってください。

次の表に、Microsoft Entra ID のトラブルシューティングに役立つ複数のシナリオを示します。

プロジェクトで Microsoft Entra ID を使用する

リソースに Microsoft Entra ID が構成されている場合でも、プロジェクトではリソースの予測を利用するために、引き続きキーを使用している可能性があります。 Azure AI Foundry プレイグラウンドを使用する場合は、プロジェクトの接続に関連付けられた資格情報が使用されます。

この動作を変更するには、Microsoft Entra ID を使用するようにプロジェクトからの接続を更新する必要があります。 次の手順に従います。

1. Azure AI Foundry ポータルに移動します。

2. 接続を介して Azure AI Foundry (旧称 Azure AI Services) リソースを使用しているプロジェクトまたはハブに移動します。

3. [管理センター] を選択します。

4. [ 接続済みリソース ] セクションに移動し、構成する Azure AI Foundry (旧称 Azure AI Services) リソースへの接続を選択します。 一覧にない場合は、[すべて表示] を選択して完全な一覧を表示します。

5. [接続の詳細] セクションの [アクセスの詳細] の横にある編集アイコンを選択します。

6. [認証] で、値を Microsoft Entra ID に変更します。

7. [更新] を選択します。

8. 接続が Microsoft Entra ID で動作するように構成されました。

リソースでキーベースの認証を無効にする

Microsoft Entra ID を実装し、サービスを使用するすべてのアプリケーションで互換性やフォールバックの問題に完全に対処している場合は、キーベースの認証を無効にすることをお勧めします。 キー ベースの認証の無効化は、Bicep/ARM を使用してデプロイする場合にのみ使用できます。

Azure AI Foundry Models では、Microsoft Entra ID を使用したキーレス承認がサポートされます。 キーレス認証により、セキュリティが強化され、ユーザー エクスペリエンスが簡素化され、運用の複雑さが軽減され、最新の開発に対する堅牢なコンプライアンス サポートが提供されます。 これは、セキュリティで保護されたスケーラブルな ID 管理ソリューションを導入する組織にとって強力な選択肢となります。

この記事では、Azure AI Foundry Models で推論用に Microsoft Entra ID を構成する方法について説明します。

Azure 内のリソースのコンテキストにおけるロールを理解する

Microsoft Entra ID は、認証にロールベースのアクセス制御 (RBAC) の考え方を使用しています。 ロールは、クラウド リソースへのアクセスを管理するうえで中心的な役割を果たします。 ロールは基本的に、特定の Azure リソースに対して実行できる操作を定義するアクセス許可のコレクションです。 ユーザー、グループ、サービス プリンシパル、またはマネージド ID (総称してセキュリティ プリンシパル) にロールを割り当てることで、Azure 環境内での特定のリソースへのアクセスを制御します。

ロールを割り当てるときは、セキュリティ プリンシパル、ロールの定義、スコープを指定します。 この組み合わせはロールの割り当てと呼ばれます。 Azure AI Foundry Models は、Azure AI Services リソースの機能であるため、その特定のリソースに割り当てられたロールが推論のアクセスを制御します。

リソースへのアクセスには次の 2 種類があります。

• 管理アクセス: リソースの管理に関連する操作。 通常、リソースの状態と構成を変更します。 Azure では、それらの操作はコントロール プレーン操作であり、Azure portal、Azure CLI、またはコードとしてのインフラストラクチャを使用して実行できます。 例としては、新しいモデル デプロイの作成、コンテンツ フィルタリングの構成の変更、提供されるモデルのバージョンの変更、デプロイの SKU の変更などがあります。

• 開発者アクセス: リソースの消費に関連する操作。 たとえば、Chat Completions API の呼び出しが挙げられます。 ただし、ユーザーはリソースの状態や構成を変更できません。

Azure では、管理操作は常に Microsoft Entra ID を使用して実行されます。 Cognitive Services 共同作成者などのロールを使用すれば、これらの操作を実行できます。 一方、開発者の操作は、アクセス キーまたは Microsoft Entra ID のどちらか、あるいはその両方を使用して実行できます。 Cognitive Services ユーザーなどのロールを使用すれば、それらの操作を実行できます。

推論のために Azure AI Foundry Models への開発者アクセスを構成するには、次の手順に従います。

[前提条件]

この記事を完了するには、以下が必要です。

• Azure サブスクリプション。 GitHub モデルを使用している場合は、エクスペリエンスをアップグレードし、プロセスで Azure サブスクリプションを作成できます。 その場合は、 GitHub モデルから Azure AI Foundry モデルへのアップグレード に関するページを参照してください。

• Azure AI Foundry リソース (旧称 Azure AI Services)。 詳細については、「 Azure AI Foundry リソースの作成」を参照してください。

• エンドポイント URL とキー。

  

• Microsoft.Authorization/roleAssignments/writeロールベースのアクセス制御など、Microsoft.Authorization/roleAssignments/delete アクセス許可および アクセス許可を持つアカウント。

• ロールを割り当てるには、次の 3 つの要素を指定する必要があります。

  • セキュリティ プリンシパル: ユーザー アカウントなど。
  • ロールの定義: Cognitive Services ユーザー ロール。
  • スコープ: Azure AI サービス リソース。

• Cognitive Services ユーザー ロールを使用する代わりにカスタム ロール定義を作成する場合は、ロールに次のアクセス許可があることを確認します。

  {
    "permissions": [
      {
        "dataActions": [
          "Microsoft.CognitiveServices/accounts/MaaS/*"
        ]
      }
    ]
  }
  

• Azure CLI をインストールします。

• 次の情報を特定します。

  • Azure のサブスクリプション ID。

  • あなたの Azure AI Foundry (旧称 Azure AI Services) リソース名。

  • Azure AI Foundry (旧称 Azure AI Services) リソースがデプロイされているリソース グループ。

推論のために Microsoft Entra ID を構成する

推論のために Microsoft Entra ID を構成するには、次の手順に従います。

1. Azure サブスクリプションにログインします。

   az login
   

2. 複数のサブスクリプションがある場合は、リソースが配置されているサブスクリプションを選択します。

   az account set --subscription "<subscription-id>"
   

3. 使用する予定の Azure AI Foundry (旧称 Azure AI Services) リソースとリソース グループの名前を使用して、次の環境変数を設定します。

   ACCOUNT_NAME="<ai-services-resource-name>"
   RESOURCE_GROUP="<resource-group>"
   

4. リソースのフル ネームを取得します。

   RESOURCE_ID=$(az resource show -g $RESOURCE_GROUP -n $ACCOUNT_NAME --resource-type "Microsoft.CognitiveServices/accounts")
   

5. アクセス許可を割り当てるセキュリティ プリンシパルのオブジェクト ID を取得します。 次の例は、以下の項目に関連付けられているオブジェクト ID を取得する方法を示しています:

   ログインしている自分のアカウント:

   OBJECT_ID=$(az ad signed-in-user show --query id --output tsv)
   

   セキュリティ グループ:

   OBJECT_ID=$(az ad group show --group "<group-name>" --query id --output tsv)
   

   サービス主体:

   OBJECT_ID=$(az ad sp show --id "<service-principal-guid>" --query id --output tsv)
   

6. Cognitive Services ユーザー ロールをサービス プリンシパル (リソースにスコープ指定) に割り当てます。 ロールを割り当てて、このリソースにサービス プリンシパル アクセス権を付与します。

   az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID
   

7. 選択したユーザーは、推論のために Microsoft Entra ID を使用できるようになりました。

   ヒント

   Azure ロールの割り当ての反映には最大で 5 分かかる場合があることに留意してください。 セキュリティ グループへのユーザーの追加または削除は、すぐに反映されます。

コードで Microsoft Entra ID を使用する

リソースで Microsoft Entra ID を構成したら、推論エンドポイントを使用するときにそれを利用できるように、コードを更新する必要があります。 次の例は、チャット補完モデルを使用する方法を示しています。

pip install azure-ai-inference

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

npm install @azure-rest/ai-inference

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    clientOptions,
);

dotnet add package Azure.AI.Inference --prerelease

dotnet add package Azure.Identity

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

TokenCredential credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions.
);

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.3</version>
</dependency>

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

Microsoft Entra ID を使用する場合の資格情報のオプション

DefaultAzureCredential は、Microsoft Entra ID への認証を行うための、独自の順序付けられたメカニズムのシーケンスです。 各認証メカニズムは、TokenCredential クラスから派生したクラスであり、資格情報と呼ばれます。 実行時に、DefaultAzureCredential は最初の資格情報を使用して認証を試みます。 その資格情報がアクセス トークンの取得に失敗した場合は、アクセス トークンが正常に取得されるまで、シーケンス内の次の資格情報が試行されます。 これにより、アプリは環境固有のコードを記述することなく、異なる環境で異なる資格情報を使用できます。

上記のコードをローカルの開発ワークステーション上で実行すると、環境変数内でアプリケーション サービス プリンシパルが検索されるか、ローカルにインストールされた開発者ツール (Visual Studio など) で開発者の資格情報のセットが検索されます。 どちらの方法も、ローカル開発中に Azure リソースに対してアプリを認証するために使用できます。

Azure にデプロイすると、この同じコードで他の Azure リソースに対してアプリを認証することもできます。 DefaultAzureCredential は、他のサービスに対して自動的に認証する環境設定とマネージド ID 構成を取得できます。

ベスト プラクティス

• 運用環境で確定的な資格情報を使用する: 運用環境では、DefaultAzureCredential から次のいずれかの確定的なソリューションに移行することを強くお勧めします。

  • 特定のTokenCredential実装、例えばManagedIdentityCredentialのようなもの。 オプションについては、派生リストを参照してください。
  • アプリが動作する Azure 環境向けに最適化された、簡素化された ChainedTokenCredential の実装。 ChainedTokenCredential は基本的に、運用用の ManagedIdentity や開発用の VisualStudioCredential など、使用可能な資格情報オプションの特定の許可リストを作成します。

• 可能であれば、コードが実行されている Azure リソースに対して、システム割り当てまたはユーザー割り当てのマネージド ID を構成します。 それらの特定の ID への Microsoft Entra ID アクセスを構成します。

トラブルシューティング

トラブルシューティングを行う前に、適切なアクセス許可が割り当てられていることを確認します。

1. Azure portal に移動し、使用している Azure AI Foundry (以前の既知の Azure AI サービス) リソースを見つけます。

2. 左側のウィンドウで、[ アクセス制御 (IAM)] を選択し、[ アクセスの確認] を選択します。

3. サービスへの接続に使用しているユーザーまたは ID の名前を入力します。

4. Cognitive Services ユーザーロールが一覧表示されていることを確認します (または、「前提条件」で説明されているように、必要なアクセス許可を含むロール)。

   Von Bedeutung

   所有者や共同作成者などのロールは、Microsoft Entra ID 経由でアクセスを提供しません。

5. 一覧にない場合は、続行する前に、このガイドの手順に従ってください。

次の表に、Microsoft Entra ID のトラブルシューティングに役立つ複数のシナリオを示します。

Azure AI Foundry Models では、Microsoft Entra ID を使用したキーレス承認がサポートされます。 キーレス認証により、セキュリティが強化され、ユーザー エクスペリエンスが簡素化され、運用の複雑さが軽減され、最新の開発に対する堅牢なコンプライアンス サポートが提供されます。 これは、セキュリティで保護されたスケーラブルな ID 管理ソリューションを導入する組織にとって強力な選択肢となります。

この記事では、Azure AI Foundry Models で推論用に Microsoft Entra ID を構成する方法について説明します。

Azure 内のリソースのコンテキストにおけるロールを理解する

Microsoft Entra ID は、認証にロールベースのアクセス制御 (RBAC) の考え方を使用しています。 ロールは、クラウド リソースへのアクセスを管理するうえで中心的な役割を果たします。 ロールは基本的に、特定の Azure リソースに対して実行できる操作を定義するアクセス許可のコレクションです。 ユーザー、グループ、サービス プリンシパル、またはマネージド ID (総称してセキュリティ プリンシパル) にロールを割り当てることで、Azure 環境内での特定のリソースへのアクセスを制御します。

ロールを割り当てるときは、セキュリティ プリンシパル、ロールの定義、スコープを指定します。 この組み合わせはロールの割り当てと呼ばれます。 Azure AI Foundry Models は、Azure AI Services リソースの機能であるため、その特定のリソースに割り当てられたロールが推論のアクセスを制御します。

リソースへのアクセスには次の 2 種類があります。

• 管理アクセス: リソースの管理に関連する操作。 通常、リソースの状態と構成を変更します。 Azure では、それらの操作はコントロール プレーン操作であり、Azure portal、Azure CLI、またはコードとしてのインフラストラクチャを使用して実行できます。 例としては、新しいモデル デプロイの作成、コンテンツ フィルタリングの構成の変更、提供されるモデルのバージョンの変更、デプロイの SKU の変更などがあります。

• 開発者アクセス: リソースの消費に関連する操作。 たとえば、Chat Completions API の呼び出しが挙げられます。 ただし、ユーザーはリソースの状態や構成を変更できません。

Azure では、管理操作は常に Microsoft Entra ID を使用して実行されます。 Cognitive Services 共同作成者などのロールを使用すれば、これらの操作を実行できます。 一方、開発者の操作は、アクセス キーまたは Microsoft Entra ID のどちらか、あるいはその両方を使用して実行できます。 Cognitive Services ユーザーなどのロールを使用すれば、それらの操作を実行できます。

推論のために Azure AI Foundry Models への開発者アクセスを構成するには、次の手順に従います。

[前提条件]

この記事を完了するには、以下が必要です。

• Azure サブスクリプション。 GitHub モデルを使用している場合は、エクスペリエンスをアップグレードし、プロセスで Azure サブスクリプションを作成できます。 その場合は、 GitHub モデルから Azure AI Foundry モデルへのアップグレード に関するページを参照してください。

• Azure AI Foundry リソース (旧称 Azure AI Services)。 詳細については、「 Azure AI Foundry リソースの作成」を参照してください。

• エンドポイント URL とキー。

  

• Microsoft.Authorization/roleAssignments/writeロールベースのアクセス制御など、Microsoft.Authorization/roleAssignments/delete アクセス許可および アクセス許可を持つアカウント。

• ロールを割り当てるには、次の 3 つの要素を指定する必要があります。

  • セキュリティ プリンシパル: ユーザー アカウントなど。
  • ロールの定義: Cognitive Services ユーザー ロール。
  • スコープ: Azure AI サービス リソース。

• Cognitive Services ユーザー ロールを使用する代わりにカスタム ロール定義を作成する場合は、ロールに次のアクセス許可があることを確認します。

  {
    "permissions": [
      {
        "dataActions": [
          "Microsoft.CognitiveServices/accounts/MaaS/*"
        ]
      }
    ]
  }
  

• Azure CLI をインストールします。

• 次の情報を特定します。

  • Azure のサブスクリプション ID。

このチュートリアルについて

この記事の中の例は、Azure-Samples/azureai-model-inference-bicep リポジトリに含まれるサンプル コードに基づいています。 ファイル内容のコピーや貼り付けをする必要なく、ローカル環境でコマンドを実行するには、次のコマンドを使用してリポジトリをクローンし、そのコーディング言語のフォルダーに移動します。

git clone https://github.com/Azure-Samples/azureai-model-inference-bicep

この例のファイルは、次の場所にあります。

cd azureai-model-inference-bicep/infra

リソースを理解する

このチュートリアルを使うと、次のことを作成できます。

これらのリソースを作成するには、次の資産を使用します。

1. テンプレート modules/ai-services-template.bicep を使用して、Azure AI Foundry (旧称 Azure AI Services) リソースを記述します。

   modules/ai-services-template.bicep

   @description('Location of the resource.')
   param ___location string = resourceGroup().___location
   
   @description('Name of the Azure AI Services account.')
   param accountName string
   
   @description('The resource model definition representing SKU')
   param sku string = 'S0'
   
   @description('Whether or not to allow keys for this account.')
   param allowKeys bool = true
   
   @allowed([
     'Enabled'
     'Disabled'
   ])
   @description('Whether or not public endpoint access is allowed for this account.')
   param publicNetworkAccess string = 'Enabled'
   
   @allowed([
     'Allow'
     'Deny'
   ])
   @description('The default action for network ACLs.')
   param networkAclsDefaultAction string = 'Allow'
   
   resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
     name: accountName
     ___location: ___location
     identity: {
       type: 'SystemAssigned'
     }
     sku: {
       name: sku
     }
     kind: 'AIServices'
     properties: {
       customSubDomainName: accountName
       publicNetworkAccess: publicNetworkAccess
       networkAcls: {
         defaultAction: networkAclsDefaultAction
       }
       disableLocalAuth: allowKeys
     }
   }
   
   output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
   output id string = account.id
   

   ヒント

   このテンプレートはパラメータ allowKeys を取ることができ、これが false の場合、リソースでのキーの使用が無効になることに注意してください。 この構成は省略可能です。

2. テンプレート modules/role-assignment-template.bicep を使用して、Azure でのロールの割り当てを記述します。

   modules/role-assignment-template.bicep

   @description('Specifies the role definition ID used in the role assignment.')
   param roleDefinitionID string
   
   @description('Specifies the principal ID assigned to the role.')
   param principalId string
   
   @description('Specifies the resource ID of the resource to assign the role to.')
   param scopeResourceId string = resourceGroup().id
   
   var roleAssignmentName= guid(principalId, roleDefinitionID, scopeResourceId)
   resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
     name: roleAssignmentName
     properties: {
       roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionID)
       principalId: principalId
     }
   }
   
   output name string = roleAssignment.name
   output resourceId string = roleAssignment.id
   

リソースの作成

コンソール内で、次の手順に従います。

1. 主なデプロイを定義します。

   deploy-entra-id.bicep

   @description('Location to create the resources in')
   param ___location string = resourceGroup().___location
   
   @description('Name of the resource group to create the resources in')
   param resourceGroupName string = resourceGroup().name
   
   @description('Name of the AI Services account to create')
   param accountName string = 'azurei-models-dev'
   
   @description('ID of the developers to assign the user role to')
   param securityPrincipalId string
   
   module aiServicesAccount 'modules/ai-services-template.bicep' = {
     name: 'aiServicesAccount'
     scope: resourceGroup(resourceGroupName)
     params: {
       accountName: accountName
       ___location: ___location
       allowKeys: false
     }
   }
   
   module roleAssignmentDeveloperAccount 'modules/role-assignment-template.bicep' = {
     name: 'roleAssignmentDeveloperAccount'
     scope: resourceGroup(resourceGroupName)
     params: {
       roleDefinitionID: 'a97b65f3-24c7-4388-baec-2e87135dc908' // Azure Cognitive Services User
       principalId: securityPrincipalId
     }
   }
   
   output endpoint string = aiServicesAccount.outputs.endpointUri
   

2. Azure にログインします。

   az login
   

3. 適切なサブスクリプションを使用していることを確認します。

   az account set --subscription "<subscription-id>"
   

4. デプロイを実行します。

   RESOURCE_GROUP="<resource-group-name>"
   SECURITY_PRINCIPAL_ID="<your-security-principal-id>"
   
   az deployment group create \
     --resource-group $RESOURCE_GROUP \
     --securityPrincipalId $SECURITY_PRINCIPAL_ID
     --template-file deploy-entra-id.bicep
   

5. このテンプレートは、作成したモデルのデプロイメントを使用するために利用できる Azure AI Foundry モデルのエンドポイントを出力します。

コードで Microsoft Entra ID を使用する

リソースで Microsoft Entra ID を構成したら、推論エンドポイントを使用するときにそれを利用できるように、コードを更新する必要があります。 次の例は、チャット補完モデルを使用する方法を示しています。

pip install azure-ai-inference

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

npm install @azure-rest/ai-inference

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    clientOptions,
);

dotnet add package Azure.AI.Inference --prerelease

dotnet add package Azure.Identity

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

TokenCredential credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions.
);

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.3</version>
</dependency>

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

Microsoft Entra ID を使用する場合の資格情報のオプション

DefaultAzureCredential は、Microsoft Entra ID への認証を行うための、独自の順序付けられたメカニズムのシーケンスです。 各認証メカニズムは、TokenCredential クラスから派生したクラスであり、資格情報と呼ばれます。 実行時に、DefaultAzureCredential は最初の資格情報を使用して認証を試みます。 その資格情報がアクセス トークンの取得に失敗した場合は、アクセス トークンが正常に取得されるまで、シーケンス内の次の資格情報が試行されます。 これにより、アプリは環境固有のコードを記述することなく、異なる環境で異なる資格情報を使用できます。

上記のコードをローカルの開発ワークステーション上で実行すると、環境変数内でアプリケーション サービス プリンシパルが検索されるか、ローカルにインストールされた開発者ツール (Visual Studio など) で開発者の資格情報のセットが検索されます。 どちらの方法も、ローカル開発中に Azure リソースに対してアプリを認証するために使用できます。

Azure にデプロイすると、この同じコードで他の Azure リソースに対してアプリを認証することもできます。 DefaultAzureCredential は、他のサービスに対して自動的に認証する環境設定とマネージド ID 構成を取得できます。

ベスト プラクティス

• 運用環境で確定的な資格情報を使用する: 運用環境では、DefaultAzureCredential から次のいずれかの確定的なソリューションに移行することを強くお勧めします。

  • 特定のTokenCredential実装、例えばManagedIdentityCredentialのようなもの。 オプションについては、派生リストを参照してください。
  • アプリが動作する Azure 環境向けに最適化された、簡素化された ChainedTokenCredential の実装。 ChainedTokenCredential は基本的に、運用用の ManagedIdentity や開発用の VisualStudioCredential など、使用可能な資格情報オプションの特定の許可リストを作成します。

• 可能であれば、コードが実行されている Azure リソースに対して、システム割り当てまたはユーザー割り当てのマネージド ID を構成します。 それらの特定の ID への Microsoft Entra ID アクセスを構成します。

トラブルシューティング

トラブルシューティングを行う前に、適切なアクセス許可が割り当てられていることを確認します。

1. Azure portal に移動し、使用している Azure AI Foundry (以前の既知の Azure AI サービス) リソースを見つけます。

2. 左側のウィンドウで、[ アクセス制御 (IAM)] を選択し、[ アクセスの確認] を選択します。

3. サービスへの接続に使用しているユーザーまたは ID の名前を入力します。

4. Cognitive Services ユーザーロールが一覧表示されていることを確認します (または、「前提条件」で説明されているように、必要なアクセス許可を含むロール)。

   Von Bedeutung

   所有者や共同作成者などのロールは、Microsoft Entra ID 経由でアクセスを提供しません。

5. 一覧にない場合は、続行する前に、このガイドの手順に従ってください。

次の表に、Microsoft Entra ID のトラブルシューティングに役立つ複数のシナリオを示します。

リソースでキーベースの認証を無効にする

Microsoft Entra ID を実装し、サービスを使用するすべてのアプリケーションで互換性やフォールバックの問題に完全に対処している場合は、キーベースの認証を無効にすることをお勧めします。 プロパティ disableLocalAuth を変更することで、これを実現できます。

modules/ai-services-template.bicep

@description('Location of the resource.')
param ___location string = resourceGroup().___location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  ___location: ___location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id