次の方法で共有


オンライン エンドポイント用にクライアントを認証する

適用対象:Azure CLI ML 拡張機能 v2 (現行)Python SDK azure-ai-ml v2 (現行)

この記事では、Azure Machine Learning オンライン エンドポイントのクライアントを認証する方法について説明します。 アクセス許可を設定し、エンドポイントを作成し、トークンまたはキーを取得し、キー、Azure Machine Learning トークン (aml_token)、または Microsoft Entra トークン (aad_token) の 3 つの認証モードのいずれかを使用してデータをスコア付けします。

オンライン エンドポイント認証には、次の 2 種類の操作が含まれます。

  • コントロール プレーン操作を使用して、エンドポイントの制御と変更を行います。 コントロール プレーン操作に該当するのは、オンライン エンドポイントとオンライン デプロイの作成、読み取り、更新、削除 (CRUD) の各操作です。
  • データ プレーン操作は、エンドポイントに変更を加えず、データを使用してオンライン エンドポイントと連携します。 たとえば、データ プレーン操作は、オンライン エンドポイントにスコアリング要求を送信し、応答を取得することで構成されます。

認証モードの選択

オンライン エンドポイントでは、データ プレーン操作に対して 3 つの認証モードがサポートされています。 セキュリティ要件とエンドポイントの種類に最適なモードを選択します。

Azure Machine Learning トークン (aml_token) Microsoft Entra トークン (aad_token)
セキュリティ レベル 最低 — 静的キーの有効期限が切れない 中 - 有効期間が短く、自動更新される 最上位 — アイデンティティに基づく、役割範囲
エンドポイントの種類 マネージドおよび Kubernetes マネージドおよび Kubernetes 管理下のみ
スコアリングには RBAC が必要です いいえ いいえ はい (score/action ロール)
トークンの有効期間 有効期限なし (手動でローテーション) 更新時の有効期間が短い 有効期間が短い (Microsoft Entra ポリシーごと)
最適な用途 開発とテスト 自動化されたパイプライン 運用ワークロード

マネージド オンライン エンドポイントでの運用ワークロードの場合は、最も強力なセキュリティのために Microsoft Entra トークン認証 (aad_token) を使用します。 開発エンドポイントまたは Kubernetes エンドポイントでは、キーベースの認証が最も簡単なオプションです。

重要

Microsoft Entra トークン (aad_token) 認証は、マネージド オンライン エンドポイントでのみサポートされます。 Kubernetes オンライン エンドポイントの場合は、キーまたは Azure Machine Learning トークン (aml_token) 認証を使用します。 詳細については、「 オンライン エンドポイントの認証と承認」を参照してください。

前提条件

  • Azure Machine Learning ワークスペース。 ワークスペースを作成する手順については、「ワークスペースの 作成」を参照してください。

  • Azure CLI と ml 拡張機能または Azure Machine Learning Python SDK v2:

    Azure CLI と ml 拡張機能をインストールするには、 CLI のインストールと設定 (v2) に関するページを参照してください。

    この記事の例では、Bash シェルまたは互換性のあるシェルを使用することを前提としています。 たとえば、Linux システム上のシェルや Linux 用 Windows サブシステムを使用できます。

  • Python SDK: パッケージの azure-ai-mlazure-identity (pip install azure-ai-ml azure-identity)
  • Azure CLI: ml 拡張機能 (az extension add -n ml)
  • Microsoft Entra ID のユーザー ID。 ユーザー ID の作成の詳細については、「 認証の設定」を参照してください。 ID ID は後の手順で必要になります。
  • コントロール プレーンとデータ プレーン操作に必要な RBAC ロール: ワークスペース スコープでユーザー ID に次のいずれかのロールを割り当てます。
    • AzureML データ サイエンティスト (組み込み) - エンドポイントとスコアリングに対する CRUD 操作のアクセス許可が含まれます。 AzureML データ サイエンティストロールを参照してください。
    • 所有者 または 共同作成者 - エンドポイントを管理するためのフル アクセス。
    • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/* アクションを持つカスタム ロール。
  • (省略可能) Azure Machine Learning ワークスペース接続シークレット 閲覧者 - ワークスペース接続からシークレットにアクセスする必要がある場合にのみ必要です。

セットアップを確認する

次のスニペットを実行して、資格情報と RBAC のアクセス許可が正しく構成されていることを確認します。

az login
az ml online-endpoint list --resource-group <RESOURCE_GROUP> --workspace-name <WORKSPACE_NAME>

予期される出力: エンドポイントの JSON 配列 (エンドポイントがまだ存在しない場合は空の [] )。

リファレンス: az ml online-endpoint list

その ID にアクセス許可を割り当てます。

必要な RBAC ロールが既に割り当てられている場合は ( 前提条件に記載されているように)、「 エンドポイントの作成」に進む。 このセクションでは、必要に応じてカスタム ロールを作成する方法について詳しく説明します。

組み込みのロールの詳細を表示する

AzureML Data Scientist 組み込みロールには、次のコントロール プレーン RBAC アクションが含まれます。

  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/write
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/delete
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/read
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/action
  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action

また、このデータ プレーン RBAC アクションは次のとおりです。

  • Microsoft.MachineLearningServices/workspaces/onlineEndpoints/score/action

Azure Machine Learning Workspace Connection Secrets Reader組み込みロールには、次のものが含まれます。

  • Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action
  • Microsoft.MachineLearningServices/workspaces/metadata/secrets/read

(オプション) カスタム ロールを作成する

組み込みロールまたはその他の事前に作成されたカスタム ロールを使用している場合は、この手順をスキップします。

  1. ロールに対応する JSON 定義を作成し、カスタム ロールのスコープとアクションを定義します。 たとえば、次のロール定義 (custom-role-for-control-plane.json) を使用すると、ユーザーは指定したワークスペース内のオンライン エンドポイントに対して CRUD 操作を実行できます。

    {
        "Name": "Custom role for control plane operations - online endpoint",
        "IsCustom": true,
        "Description": "Can CRUD against online endpoints.",
        "Actions": [
            "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/write",
            "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/delete",
            "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/read",
            "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action",
            "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listKeys/action",
            "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/regenerateKeys/action"
        ],
        "NotActions": [
        ],
        "AssignableScopes": [
            "/subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>"
        ]
    }
    

    次のロール定義 (custom-role-for-scoring.json) を使用すると、ユーザーは、指定したワークスペース内のオンライン エンドポイントにスコアリング要求を送信できます。

    {
        "Name": "Custom role for scoring - online endpoint",
        "IsCustom": true,
        "Description": "Can score against online endpoints.",
        "Actions": [
            "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*/action"
        ],
        "NotActions": [
        ],
        "AssignableScopes": [
            "/subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>"
        ]
    }
    
  2. その JSON 定義を使用し、カスタム ロールを作成します:

    az role definition create --role-definition custom-role-for-control-plane.json --subscription <subscriptionID>
    
    az role definition create --role-definition custom-role-for-scoring.json --subscription <subscriptionID>
    

    カスタム ロールを作成するには、以下の 3 つのロールのいずれかが必要です:

    • オーナー
    • ユーザーアクセス管理者
    • Microsoft.Authorization/roleDefinitions/writeアクセス許可 (カスタム ロールの作成、更新、削除) とMicrosoft.Authorization/roleDefinitions/readアクセス許可 (カスタム ロールを表示する) を持つカスタム ロール。

    カスタム ロールの作成に関する詳細については、「Azure カスタム ロール」を参照してください。

  3. ロールの定義を確認します。

    az role definition list --custom-role-only -o table
    
    az role definition list -n "Custom role for control plane operations - online endpoint"
    az role definition list -n "Custom role for scoring - online endpoint"
    
    export role_definition_id1=`(az role definition list -n "Custom role for control plane operations - online endpoint" --query "[0].id" | tr -d '"')`
    
    export role_definition_id2=`(az role definition list -n "Custom role for scoring - online endpoint" --query "[0].id" | tr -d '"')`
    

ロールを ID に割り当てる

  1. AzureML Data Scientist という組み込みロールを使用する場合、次のコードを使用し、そのロールをユーザー ID に割り当てます。

    az role assignment create --assignee <identityID> --role "AzureML Data Scientist" --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
    
  2. オプションで、Azure Machine Learning Workspace Connection Secrets Reader という組み込みロールを使用する場合、次のコードを使用し、そのロールをユーザー ID に割り当てます。

    az role assignment create --assignee <identityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
    
  3. カスタム ロールを使用する場合、次のコードを使用し、そのロールをユーザー ID に割り当てます。

    az role assignment create --assignee <identityID> --role "Custom role for control plane operations - online endpoint" --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
    
    az role assignment create --assignee <identityID> --role "Custom role for scoring - online endpoint" --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
    

    カスタム ロールをユーザー ID に割り当てるには、以下の 3 つのロールのいずれかが必要です。

    • オーナー
    • ユーザーアクセス管理者
    • Microsoft.Authorization/roleAssignments/write (カスタム ロールの割り当て) と、Microsoft.Authorization/roleAssignments/read (ロール割り当ての表示) の各アクセス許可を許可するカスタム ロール。

    Azure ロールとそのアクセス許可の詳細については、Azure portal を使用した Azure ロールAzure ロールの割り当てに関するページを参照してください。

  4. ロールの割り当てを確認します:

    az role assignment list --scope /subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>
    

コントロール プレーン トークンを取得する

トークンを直接使用する REST API を使用してコントロール プレーン操作を実行する場合は、この手順を完了します。

ml 拡張機能 v2、Python SDK v2、Azure Machine Learning Studio で Azure CLI などの他の方法を使用する場合は、Microsoft Entra トークンを手動で取得する必要はありません。 サインイン中にユーザー ID が認証され、トークンが自動的に取得されて渡されます。

コントロール プレーン操作用の Microsoft Entra トークンは、Azure リソース エンドポイント ( https://management.azure.com) から取得できます。

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

    az login
    
  2. 特定の ID を使用することを希望する場合は、次のコードを使用し、その ID でサインインします。

    az login --identity --username <identityID>
    
  3. トークンを取得するには、次のコンテキストを使用します。

    export CONTROL_PLANE_TOKEN=$(az account get-access-token \
        --resource https://management.azure.com \
        --query accessToken -o tsv)
    

リファレンス: az loginaz account get-access-token

コントロール プレーン トークンを確認する (省略可能)

Microsoft Entra トークンを取得した後は、management.azure.comしてトークンをデコードすることで、トークンが適切な Azure リソース エンドポイント () と適切なクライアント ID 用であることを確認できます。

ヒント

jwt.ms サイトは、ブラウザーでトークンを完全にデコードする Microsoft 所有のツールであり、データはサーバーに送信されません。 信頼されていないデコード ツールにトークンを貼り付けてはいけません。

デコードされたトークンは、次の情報を含む JSON 応答を返します。

{
    "aud": "https://management.azure.com",
    "oid": "<your-object-id>"
}

エンドポイントの作成

次の例では、エンドポイント ID としてシステム割り当て ID (SAI) を使用してエンドポイントを作成します。 SAI はエンドポイントの既定の ID の種類であり、一部の基本ロールは自動的に割り当てられます。 詳細については、「 エンドポイント ID のロールの自動割り当て」を参照してください。

CLI では、コントロール プレーン トークンを明示的に指定する必要はありません。 代わりに、CLI az login コマンドはサインイン中にユーザーを認証し、トークンが自動的に取得されて渡されます。

  1. endpoint.ymlという名前のエンドポイント定義 YAML ファイル 作成します。

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
    name: my-endpoint
    auth_mode: aad_token
    

    キー認証の場合はauth_mode、Azure Machine Learning トークン認証の場合はkeyaml_tokenを設定できます。 この例では、Microsoft Entra トークン認証に aad_token を使用します。

    aad_token認証モードは、マネージド オンライン エンドポイントでのみサポートされます。 Kubernetes オンライン エンドポイントの場合は、 auth_modekey または aml_token に設定します。

  2. エンドポイントを作成します。

    az ml online-endpoint create -f endpoint.yml
    
  3. エンドポイントの状態を確認します。

    az ml online-endpoint show -n my-endpoint
    
  4. エンドポイントの作成時に auth_mode をオーバーライドする (たとえば、aad_token に) ことを希望する場合は、次のコードを実行します:

    az ml online-endpoint create -n my-endpoint --auth-mode aad_token
    
  5. 既存のエンドポイントを更新し、 auth_mode (たとえば、 aad_token) を指定する場合は、次のコードを実行します。

    az ml online-endpoint update -n my-endpoint --set auth_mode=aad_token
    

リファレンス: az ml online-endpoint create, az ml online-endpoint show, az ml online-endpoint update

デプロイの作成

デプロイを作成するには、「 オンライン エンドポイントを使用して機械学習モデルをデプロイ する」または「 REST を使用してモデルをオンライン エンドポイントとしてデプロイする」を参照してください。 さまざまな認証モードのデプロイを作成する方法に違いはありません。

以下のコードは、デプロイを作成する方法の例です。 オンライン エンドポイントのデプロイの詳細については、「オンライン エンドポイントを 使用した機械学習モデルのデプロイ (CLI を使用)」を参照してください。

  1. blue-deployment.ymlという名前のデプロイ定義 YAML ファイルを作成します。

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
    name: blue
    endpoint_name: my-aad-auth-endp1
    model:
      path: ../../model-1/model/
    code_configuration:
      code: ../../model-1/onlinescoring/
      scoring_script: score.py
    environment: 
      conda_file: ../../model-1/environment/conda.yml
      image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu22.04:latest
    instance_type: Standard_DS3_v2
    instance_count: 1
    
  2. YAML ファイルを使用してデプロイを作成します。 この例では、すべてのトラフィックを新しいデプロイに設定します。

    az ml online-deployment create -f blue-deployment.yml --all-traffic
    

リファレンス: az ml online-deployment create

スコアリング URI を取得する

az ml online-endpoint invokeを使用してエンドポイントを呼び出すと、CLI によってスコア付け URI が自動的に解決されるため、手動で取得する必要はありません。

ただし、他のツール (REST API やカスタム HTTP クライアントなど) で使用するためにスコアリング URI が必要な場合は、次のコマンドを使用して取得できます。

scoringUri=$(az ml online-endpoint show -n my-endpoint --query "scoring_uri")

リファレンス: az ml online-endpoint show

データ プレーン キーまたはトークンを取得する

キーまたはトークンを取得するプロセスがコントロール プレーン操作であっても、データ プレーン操作にはキーまたはトークンを使用できます。 つまり、コントロール プレーン トークンを使用して、後でデータ プレーン操作に使用するキーまたはトークンを取得します。

トークンの有効期間は、認証モードによって異なります。

  • キー: キーは期限切れになりませんが、セキュリティのために定期的にローテーションする必要があります。 キーを回転するには、 regenerateKeys アクションを使用します。
  • Azure Machine Learning トークン (aml_token):refreshAfterTimeUtc フィールドを含む有効期間の短いトークン。 有効期限が切れないように、この時間の後に新しいトークンを要求します。
  • Microsoft Entra トークン (aad_token): Microsoft Entra ID トークンの有効期間ポリシー (通常は 60 ~ 90 分) に従います。 expiryTimeUtcする前にトークンを更新します。

キーまたは Azure Machine Learning トークンを取得するには、「 コントロール プレーン操作の承認」で説明されているように、要求しているユーザー ID に正しいロールが割り当てられている必要があります。 ユーザー ID は、Microsoft Entra トークンを取得するために追加のロールを必要としません。

CLI を使用してエンドポイントを呼び出す予定の場合は、CLI によって提供されるため、データ プレーン操作のキーまたはトークンを明示的に取得する必要はありません。 ただし、REST API などの他のチャネルで使用できるように、CLI を使用してデータ プレーン操作のキーまたはトークンを取得することもできます。

データ プレーン操作用のキーまたはトークンを取得するには、az ml online-endpoint get-credentials コマンドを使用します。 このコマンドは、キー、トークン、またはその他の情報を含む JSON 出力を返します。

ヒント

次のコマンドでは、 --query パラメーターを使用して、JSON 出力から特定の情報を抽出します。 ただし、その目的に適した任意のツールを使用できます。

エンドポイントの auth_modekey

  • キーは primaryKeysecondaryKey の各フィールド内で返されます。

    export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query primaryKey)
    export DATA_PLANE_TOKEN2=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query secondaryKey)
    

エンドポイントの auth_modeaml_token

  • トークンは、 accessToken フィールドに返されます。

  • トークンの有効期限が expiryTimeUtc フィールドに返されます。

  • トークンの更新時間は、 refreshAfterTimeUtc フィールドに返されます。

    export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)
    export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc)
    export REFRESH_AFTER_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query refreshAfterTimeUtc)
    

エンドポイントの auth_modeaad_token

  • トークンは、 accessToken フィールドに返されます。

  • トークンの有効期限が expiryTimeUtc フィールドに返されます。

    export DATA_PLANE_TOKEN=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query accessToken)
    export EXPIRY_TIME_UTC=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -g $RESOURCE_GROUP -w $WORKSPACE_NAME -o tsv --query expiryTimeUtc)
    

リファレンス: az ml online-endpoint get-credentials

データ プレーン トークンを確認する (省略可能)

Entra トークンを取得した後、トークンが適切な Azure リソース エンドポイント、 ml.azure.com、および適切なクライアント ID 用であることを確認するには、次の情報を含む JSON 応答を返す jwt.ms を介してトークンをデコードします。

ヒント

jwt.ms サイトは、ブラウザーでトークンを完全にデコードする Microsoft 所有のツールであり、データはサーバーに送信されません。 信頼されていないデコード ツールにトークンを貼り付けてはいけません。

{
    "aud": "https://ml.azure.com",
    "oid": "<your-object-id>"
}

スコアデータ

キー、Azure Machine Learning トークン、Microsoft Entra トークンのいずれかを使用するエンドポイントの場合、az ml online-endpoint invoke を使用できます。 CLI ではキーまたはトークンが自動的に提供されるため、明示的に渡す必要はありません。

az ml online-endpoint invoke -n my-endpoint -r request.json

リファレンス: az ml online-endpoint invoke

エンドポイント トラフィックを監視する

エンドポイントの診断設定でトラフィック ログを有効にするには、「 ログを有効にする」の手順を実行します。

診断設定が有効になっている場合は、 AmlOnlineEndpointTrafficLogs テーブルを表示して、認証モードとユーザー ID を確認できます。

認証エラーのトラブルシューティング

次の表に、一般的な認証エラーとその解決策を示します。

エラー 想定される原因 Resolution
401 権限がありません 見つからない、期限切れ、または間違った対象ユーザートークン トークン対象ユーザーがエンドポイントの種類 (コントロール プレーンの management.azure.com 、データ プレーンの ml.azure.com ) と一致するかどうかを確認します。 期限切れのトークンを更新します。
403 許可されていません ユーザーの識別情報には必要なRBACロールが不足しています エンドポイント スコープで、score/action アクセス許可を持つ AzureML Data Scientist またはカスタム ロールを割り当てます。 ID へのアクセス許可の割り当てを参照してください。
aad_token 受け入れられない Kubernetes エンドポイントでの aad_token の使用 keyまたはaml_tokenに切り替えます。 Microsoft Entra トークン認証は、マネージド オンライン エンドポイントでのみサポートされます。
AADSTS700016 または同様の Entra エラー トークン要求のリソースまたは対象ユーザーが間違っている リソース パラメーターが操作の種類 (コントロール プレーンの https://management.azure.com 、データ プレーンの https://ml.azure.com ) と一致していることを確認します。