バッチエンドポイントでの認可

2024-10-16

バッチエンドポイントは Microsoft Entra 認証 (つまり aad_token) をサポートします。そのため、バッチエンドポイントを呼び出すには、ユーザーが有効な Microsoft Entra 認証トークンをバッチエンドポイント URI に提示する必要があります。承認はエンドポイントレベルで適用されます。次の記事では、バッチエンドポイントを正しく操作する方法と、そのセキュリティ要件について説明します。

承認のしくみ

バッチエンドポイントを呼び出すには、ユーザーがセキュリティプリンシパルを表す有効な Microsoft Entra トークンを提示する必要があります。このプリンシパルには、ユーザープリンシパルまたはサービスプリンシパルを指定できます。いずれの場合も、エンドポイントが呼び出されると、トークンに関連付けられている ID の下にバッチデプロイジョブが作成されます。ジョブを正常に作成するには、ID に次のアクセス許可が必要です。

バッチエンドポイント/デプロイを読み取る。
バッチ推論エンドポイント/デプロイでジョブを作成する。
実験/実行を作成する。
データストアとの間で読み取りと書き込みを行う。
データストアシークレットを一覧表示する。

RBAC のアクセス許可の詳細な一覧については、「バッチエンドポイントの呼び出し用に RBAC を構成する」を参照してください。

重要

データストアの構成方法によっては、バッチエンドポイントの呼び出しに使用される ID は、基になるデータの読み取りには使用されない場合があります。詳細については、「データアクセス用にコンピューティングクラスターを構成する」を参照してください。

さまざまな種類の資格情報を使用してジョブを実行する方法

次の例では、さまざまな種類の資格情報を使用してバッチデプロイジョブを開始するさまざまな方法を示します。

重要

プライベートリンクが有効なワークスペースで作業している場合、Azure Machine Learning Studio の UI からバッチエンドポイントを呼び出すことはできません。代わりに、Azure Machine Learning CLI v2 を使用してジョブを作成してください。

前提条件

この例は、モデルがバッチエンドポイントとして正しくデプロイされていることを前提としています。具体的には、バッチデプロイでの MLflow モデルの使用に関するチュートリアルで作成した "心臓病分類器" を使います。

ユーザーの資格情報を使用してジョブを実行する

この場合は、現在ログインしているユーザーの ID を使ってバッチエンドポイントを実行します。次の手順のようにします。

Azure CLI を使用して、対話型認証またはデバイスコード認証を使用してログインします。
```
az login
```

認証が完了したら、次のコマンドを使用してバッチデプロイジョブを実行します。

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci

Azure Machine Learning SDK for Python を使用して、対話型認証またはデバイス認証を使用してログインします。

from azure.ai.ml import MLClient
from azure.identity import InteractiveAzureCredentials

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"

ml_client = MLClient(InteractiveAzureCredentials(), subscription_id, resource_group, workspace)

認証が完了したら、次のコマンドを使用してバッチデプロイジョブを実行します。

job = ml_client.batch_endpoints.invoke(
        endpoint_name,
        input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci")
    )

REST を使用する場合は、サービスプリンシパルを使用してバッチエンドポイントを呼び出すことをお勧めします。ただし、REST で独自の資格情報を使用して特定のデプロイをテストする場合は、アカウントの Microsoft Entra トークンを生成することで実行できます。次の手順のようにします。

ユーザーアカウントの有効なトークンを取得する最も簡単な方法は、Azure CLI を使用することです。コンソールで、次のコマンドを実行します。
```
az account get-access-token --resource https://ml.azure.com \
                            --query "accessToken" \
                            --output tsv
```
生成された出力をメモします。

認証が完了したら、呼び出し URI への要求を、前に取得した <TOKEN> と置き換えます。

要求:

POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json

本文は次のようになります。

{
    "properties": {
        "InputData": {
            "mnistinput": {
                "JobInputType" : "UriFolder",
                "Uri":  "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci"
            }
        }
    }
}

サービスプリンシパルを使用してジョブを実行する

この場合、Microsoft Entra ID で既に作成されているサービスプリンシパルを使って、バッチエンドポイントを実行します。認証を完了するには、認証を実行するためのシークレットを作成する必要があります。次の手順のようにします。

「オプション 3: 新しいクライアントシークレットを作成する」の説明に従って、認証に使うシークレットを作成します。
サービスプリンシパルを使って認証を行うには、次のコマンドを使います。詳細については、「Azure CLI を使用してサインインする」を参照してください。
```
az login --service-principal \
         --tenant <tenant> \
         -u <app-id> \
         -p <password-or-cert> 
```

認証が完了したら、次のコマンドを使用してバッチデプロイジョブを実行します。

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/

「オプション 3: 新しいクライアントシークレットを作成する」の説明に従って、認証に使うシークレットを作成します。

サービスプリンシパルを使って認証を行うには、次に示すように、環境変数を使って、サービスプリンシパルのテナント ID、クライアント ID、クライアントシークレットを指定します。

from azure.ai.ml import MLClient
from azure.identity import EnvironmentCredential

os.environ["AZURE_TENANT_ID"] = "<TENANT_ID>"
os.environ["AZURE_CLIENT_ID"] = "<CLIENT_ID>"
os.environ["AZURE_CLIENT_SECRET"] = "<CLIENT_SECRET>"

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"

ml_client = MLClient(EnvironmentCredential(), subscription_id, resource_group, workspace)

認証が完了したら、次のコマンドを使用してバッチデプロイジョブを実行します。

job = ml_client.batch_endpoints.invoke(
        endpoint_name,
        input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci")
    )

「オプション 3: 新しいクライアントシークレットを作成する」の説明に従って、認証に使うシークレットを作成します。
Azure からログインサービスを使って、認可トークンを取得します。認可トークンは、特定のスコープに対して発行されます。 Azure Machine Learning のリソースの種類は https://ml.azure.com です。要求は次のようになります。

要求:
```
POST /{TENANT_ID}/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
```
本文:
```
grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&resource=https://ml.azure.com
```
重要

バッチエンドポイント (https://ml.azure.com) を呼び出すためのリソーススコープは、それらの管理に使用されるリソーススコープとは異なることに注意してください。 Azure のすべての管理 API (Azure Machine Learning を含む) はリソーススコープ https://management.azure.com を使用します。

認証が終わったら、クエリを使ってバッチデプロイジョブを実行します。

要求:

POST jobs HTTP/1.1
Host: <ENDPOINT_URI>
Authorization: Bearer <TOKEN>
Content-Type: application/json

本文は次のようになります。

{
    "properties": {
        "InputData": {
            "mnistinput": {
                "JobInputType" : "UriFolder",
                "Uri":  "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci"
            }
        }
    }
}

マネージド ID を使用してジョブを実行する

マネージド ID を使って、バッチエンドポイントとデプロイを呼び出すことができます。この管理 ID はバッチエンドポイントに属しているのではなく、エンドポイントを実行するために使われる ID であり、したがってバッチジョブを作成することに注意してください。このシナリオでは、ユーザー割り当て ID とシステム割り当て ID の両方を使用できます。

Azure リソースのマネージド ID 用に構成されたリソースでは、マネージド ID を使用してサインインできます。リソースの ID を使用したサインインは、--identity フラグを介して行われます。詳細については、「Azure CLI を使用してサインインする」を参照してください。

az login --identity

認証が完了したら、次のコマンドを使用してバッチデプロイジョブを実行します。

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci

Azure リソースのマネージド ID 用に構成されたリソースでは、マネージド ID を使用してサインインできます。次の例に示すように、ManagedIdentityCredential オブジェクトと共にリソース ID を使用します。

from azure.ai.ml import MLClient
from azure.identity import ManagedIdentityCredential

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"
resource_id = "<resource-id>"

ml_client = MLClient(ManagedIdentityCredential(resource_id), subscription_id, resource_group, workspace)

認証が完了したら、次のコマンドを使用してバッチデプロイジョブを実行します。

job = ml_client.batch_endpoints.invoke(
        endpoint_name,
        input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci")
    )

バッチエンドポイントの呼び出し用に RBAC を構成する

バッチエンドポイントにより、コンシューマーがジョブの生成に使用できる永続的な API が公開されます。呼び出し元は、これらのジョブを生成できるように適切なアクセス許可を要求します。組み込みのセキュリティロールのいずれかを使用することも、目的に合わせてカスタムロールを作成することもできます。

バッチエンドポイントを正常に呼び出すには、エンドポイントの呼び出しに使用される ID に次の明示的なアクションを許可する必要があります。 Azure ロールを割り当てる手順については、「Azure ロールを割り当てる手順」を参照してください。

"actions": [
    "Microsoft.MachineLearningServices/workspaces/read",
    "Microsoft.MachineLearningServices/workspaces/data/versions/write",
    "Microsoft.MachineLearningServices/workspaces/datasets/registered/read",
    "Microsoft.MachineLearningServices/workspaces/datasets/registered/write",
    "Microsoft.MachineLearningServices/workspaces/datasets/unregistered/read",
    "Microsoft.MachineLearningServices/workspaces/datasets/unregistered/write",
    "Microsoft.MachineLearningServices/workspaces/datastores/read",
    "Microsoft.MachineLearningServices/workspaces/datastores/write",
    "Microsoft.MachineLearningServices/workspaces/datastores/listsecrets/action",
    "Microsoft.MachineLearningServices/workspaces/listStorageAccountKeys/action",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/read",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/write",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/deployments/read",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/deployments/write",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/deployments/jobs/write",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/jobs/write",
    "Microsoft.MachineLearningServices/workspaces/computes/read",
    "Microsoft.MachineLearningServices/workspaces/computes/listKeys/action",
    "Microsoft.MachineLearningServices/workspaces/metadata/secrets/read",
    "Microsoft.MachineLearningServices/workspaces/metadata/snapshots/read",
    "Microsoft.MachineLearningServices/workspaces/metadata/artifacts/read",
    "Microsoft.MachineLearningServices/workspaces/metadata/artifacts/write",
    "Microsoft.MachineLearningServices/workspaces/experiments/read",
    "Microsoft.MachineLearningServices/workspaces/experiments/runs/submit/action",
    "Microsoft.MachineLearningServices/workspaces/experiments/runs/read",
    "Microsoft.MachineLearningServices/workspaces/experiments/runs/write",
    "Microsoft.MachineLearningServices/workspaces/metrics/resource/write",
    "Microsoft.MachineLearningServices/workspaces/modules/read",
    "Microsoft.MachineLearningServices/workspaces/models/read",
    "Microsoft.MachineLearningServices/workspaces/endpoints/pipelines/read",
    "Microsoft.MachineLearningServices/workspaces/endpoints/pipelines/write",
    "Microsoft.MachineLearningServices/workspaces/environments/read",
    "Microsoft.MachineLearningServices/workspaces/environments/write",
    "Microsoft.MachineLearningServices/workspaces/environments/build/action",
    "Microsoft.MachineLearningServices/workspaces/environments/readSecrets/action"
]

データアクセス用にコンピューティングクラスターを構成する

バッチエンドポイントを使用すると、承認されたユーザーのみがバッチデプロイを呼び出してジョブを生成できるようになります。ただし、入力データの構成方法によっては、基になるデータの読み取りに他の資格情報を使用できます。次の表を使用して、使用される資格情報を理解します。

データ入力の種類	ストア内の資格情報	使用される資格情報	アクセス許可の付与
データストア	はい	ワークスペース内のデータストアの資格情報	アクセスキーまたは SAS
データ資産	はい	ワークスペース内のデータストアの資格情報	アクセスキーまたは SAS
データストア	いいえ	ジョブの ID + コンピューティングクラスターのマネージド ID	RBAC
データ資産	いいえ	ジョブの ID + コンピューティングクラスターのマネージド ID	RBAC
Azure Blob Storage (アジュール・ブロブ・ストレージ)	適用しない	ジョブの ID + コンピューティングクラスターのマネージド ID	RBAC
Azure Data Lake Storage Gen1	適用しない	ジョブの ID + コンピューティングクラスターのマネージド ID	POSIX
Azure Data Lake Storage Gen2	適用しない	ジョブの ID + コンピューティングクラスターのマネージド ID	POSIX と RBAC

表内の「ジョブの ID + コンピューティングクラスターのマネージド ID」と表示されている項目については、マウントとストレージアカウントの構成にコンピューティングクラスターのマネージド ID が使われます。ただし、ジョブの ID は、基になるデータを読み取るために引き続き使用され、きめ細かいアクセス制御を実現します。つまり、ストレージからデータを正常に読み取るには、デプロイが実行されているコンピューティングクラスターのマネージド ID に、少なくともストレージアカウントへのストレージ BLOB データ閲覧者アクセス権が必要になります。

データアクセス用にコンピューティングクラスターを構成するには、次の手順を実行します。

[Azure Machine Learning Studio] に移動します。
[コンピューティング]、[コンピューティングクラスター] の順に移動します。
デプロイで使用しているコンピューティングクラスターを選択します。このアクションにより、コンピューティングクラスターの [詳細] ページが開きます。
マネージド ID をコンピューティングクラスターに割り当てます。
1. ページの [マネージド ID] セクションに移動し、コンピューティングにマネージド ID が割り当てられているかどうかを確認します。そうでない場合は、鉛筆アイコンを選択してマネージド ID を編集します。
2. [ マネージド ID の割り当て ] の横にあるスライダーを選択して有効にし、必要に応じて構成します。システム割り当てマネージド ID またはユーザー割り当てマネージド ID を使用できます。システム割り当てマネージド ID を使っている場合は、"[ワークスペース名]/computes/[コンピューティングクラスター名]" という名前です。
3. 変更を保存します。
Azure portal に移動し、データが配置されている関連ストレージアカウントに移動します。データ入力がデータ資産またはデータストアの場合は、それらの資産が配置されているストレージアカウントを探します。
ストレージアカウントでストレージ BLOB データ閲覧者のアクセスレベルを割り当てます。
1. [アクセス制御 (IAM)] セクションに移動します。
2. [ロールの割り当て] タブを選び、[追加]>[ロールの割り当て] をクリックします。
3. ストレージ BLOB データ閲覧者というロールを探して選び、[次へ] をクリックします。
4. [メンバーの選択] をクリックします。
5. 作成したマネージド ID を探します。システム割り当てマネージド ID を使っている場合は、"[ワークスペース名]/computes/[コンピューティングクラスター名]" という名前です。
6. アカウントを追加し、ウィザードを完了します。
エンドポイントは、選んだストレージアカウントからジョブと入力データを受け取る準備が整いました。

次の方法で共有

バッチ エンドポイントでの認可

承認のしくみ

さまざまな種類の資格情報を使用してジョブを実行する方法

前提条件

ユーザーの資格情報を使用してジョブを実行する

サービス プリンシパルを使用してジョブを実行する

マネージド ID を使用してジョブを実行する

バッチ エンドポイントの呼び出し用に RBAC を構成する

データ アクセス用にコンピューティング クラスターを構成する

次のステップ

フィードバック

その他のリソース

バッチエンドポイントでの認可

サービスプリンシパルを使用してジョブを実行する

バッチエンドポイントの呼び出し用に RBAC を構成する

データアクセス用にコンピューティングクラスターを構成する