다음을 통해 공유

온라인 엔드포인트에 대한 클라이언트 인증

  • 아티클

적용 대상:Azure CLI ml 확장 v2(현재)Python SDK azure-ai-ml v2(현재)

이 문서에서는 클라이언트에서 온라인 엔드포인트에 대한 컨트롤 플레인 작업 및 데이터 평면 작업을 수행하도록 인증하는 방법을 설명합니다.

컨트롤 플레인 작업은 엔드포인트를 제어하고 변경합니다. 컨트롤 플레인 작업에는 온라인 엔드포인트 및 온라인 배포에 대한 CRUD(만들기, 읽기, 업데이트 및 삭제) 작업이 포함됩니다.

데이터 평면 작업은 데이터를 사용하여 엔드포인트를 변경하지 않으면서 온라인 엔드포인트와 상호 작용합니다. 예를 들어 데이터 평면 작업은 온라인 엔드포인트에 채점 요청을 보내고 응답을 받는 것으로 이루어집니다.

필수 조건

이 문서의 단계를 수행하기 전에 다음과 같은 필수 구성 요소가 있는지 확인합니다.

  • Azure Machine Learning 작업 영역 리소스가 없으면 빠른 시작: 작업 영역 리소스 만들기 문서의 단계에서 리소스를 만듭니다.

  • Azure CLI 및 ml 확장 또는 Azure Machine Learning Python SDK v2:

    • Azure CLI 및 확장을 설치하려면 CLI(v2) 설치, 설정 및 사용을 참조하세요.

      Important

      이 문서의 CLI 예제에서는 Bash(또는 호환) 셸을 사용한다고 가정합니다. 예를 들어 Linux 시스템 또는 Linux용 Windows 하위 시스템에서 이러한 예제를 사용합니다.

    • Python SDK v2를 설치하려면 다음 명령을 사용합니다.

      pip install azure-ai-ml azure-identity

      기존 SDK 설치를 최신 버전으로 업데이트하려면 다음 명령을 사용합니다.

      pip install --upgrade azure-ai-ml azure-identity

      자세한 내용은 Azure Machine Learning용 Python SDK v2 설치를 참조하세요.

사용자 ID 준비

온라인 엔드포인트에 대한 컨트롤 플레인 작업(CRUD 작업) 및 데이터 평면 작업(채점 요청 보내기)을 수행하려면 사용자 ID가 필요합니다. 컨트롤 플레인 작업과 데이터 평면 작업에 동일한 사용자 ID 또는 다른 사용자 ID를 사용할 수 있습니다. 이 문서에서는 컨트롤 플레인 작업과 데이터 평면 작업 모두에서 동일한 사용자 ID를 사용합니다.

Microsoft Entra ID에서 사용자 ID를 만들려면 인증 설정을 참조하세요. 나중에 이 ID가 필요합니다.

ID에 사용 권한 할당

이 섹션에서는 엔드포인트와 상호 작용하는 데 필요한 사용자 ID에 사용 권한을 할당합니다. 먼저 기본 제공 역할을 사용하거나 사용자 지정 역할을 만듭니다. 그런 다음 역할을 사용자 ID에 할당합니다.

기본 제공 역할 사용

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 기본 제공 역할을 사용하여 작업 영역 연결에서 암호에 액세스할 수 있으며, 다음과 같은 컨트롤 플레인 RBAC 작업이 포함됩니다.

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

이러한 기본 제공 역할을 사용하는 경우 이 단계에서 필요한 작업은 없습니다.

(선택 사항) 사용자 지정 역할 만들기

기본 제공 역할 또는 다른 미리 만들어진 사용자 지정 역할을 사용하는 경우 이 단계를 건너뛸 수 있습니다.

  1. 역할에 대한 JSON 정의를 만들어 사용자 지정 역할의 범위와 작업을 정의합니다. 예를 들어 다음과 같은 역할 정의를 사용하면 사용자가 지정된 작업 영역에서 온라인 엔드포인트에 대한 CRUD를 수행할 수 있습니다.

    custom-role-for-control-plane.json:

    {
    "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>

    참고 항목

    사용자 지정 역할을 만들려면 다음 세 가지 역할 중 하나가 필요합니다.

    • owner
    • 사용자 액세스 관리자
    • 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에 사용자 지정 역할을 할당하려면 다음 세 가지 역할 중 하나가 필요합니다.

    • owner
    • 사용자 액세스 관리자
    • Microsoft.Authorization/roleAssignments/write 권한(사용자 지정 역할 할당) 및 Microsoft.Authorization/roleAssignments/read(역할 할당 보기) 권한이 있는 사용자 지정 역할.

    기타 Azure 역할 및 해당 권한에 대한 자세한 내용은 Azure 역할 및 Azure Portal을 사용하여 Azure 역할 할당을 참조하세요.

  4. 역할 할당을 확인합니다.

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

컨트롤 플레인 작업을 위한 Microsoft Entra 토큰 가져오기

토큰을 직접 사용하는 방법으로서 REST API로 컨트롤 플레인 작업을 수행하려는 경우 이 단계를 수행합니다.

Azure Machine Learning CLI(v2), Python SDK(v2) 또는 Azure Machine Learning 스튜디오와 같은 다른 방법을 사용하려는 경우 Microsoft Entra 토큰을 수동으로 가져올 필요가 없습니다. 그러지 않아도 로그인하는 동안 사용자 ID가 이미 인증되고 토큰이 자동으로 검색되어 사용자에게 전달됩니다.

Azure 리소스 엔드포인트 https://management.azure.com에서 컨트롤 플레인 작업을 위한 Microsoft Entra 토큰을 검색해도 됩니다.

  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 | tr -d '"')`

(선택 사항) Microsoft Entra 토큰이 리소스 엔드포인트 및 클라이언트 ID에 적합한지 확인

Microsoft Entra 토큰을 검색한 후 jwt.ms를 통해 토큰을 디코딩하여 토큰이 Azure 리소스 엔드포인트 management.azure.com 및 클라이언트 ID에 적합한지 확인할 수 있습니다. 그러면 다음 정보를 포함한 json 응답이 반환됩니다.

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

엔드포인트 만들기

다음 예제에서는 SAI(시스템 할당 ID)를 엔드포인트 ID로 사용하여 엔드포인트를 만듭니다. SAI는 엔드포인트용 관리 ID의 기본 ID 형식입니다. 일부 기본 역할은 SAI에 자동으로 할당됩니다. 시스템 할당 ID에 대한 역할 할당에 대한 자세한 내용은 엔드포인트 ID에 대한 자동 역할 할당을 참조하세요.

CLI에서는 컨트롤 플레인 토큰을 명시적으로 제공할 필요가 없습니다. CLI az login에서는 로그인하는 동안 사용자가 인증되고, 토큰이 자동으로 검색되어 사용자에게 전달됩니다.

  1. 엔드포인트 정의 YAML 파일을 만듭니다.

    endpoint.yml:

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

  2. auth_mode을(를) 키 인증에는 key(으)로, Azure Machine Learning 토큰 인증에는 aml_token(으)로 바꿀 수 있습니다. 이 예제에서는 Microsoft Entra 토큰 인증에 aad_token을(를) 사용합니다.

    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

배포 만들기

배포를 생성하려면 온라인 엔드포인트를 사용하여 ML 모델 배포 또는 REST를 사용하여 모델을 온라인 엔드포인트로서 배포를 참조하세요. 다른 인증 모드에서도 배포를 만드는 방법에 차이가 없습니다.

다음 코드는 배포를 만드는 방법의 예입니다. 온라인 엔드포인트 배포에 대한 자세한 내용은 CLI를 통해 온라인 엔드포인트를 사용하여 ML 모델 배포를 참조하세요

  1. 배포 정의 YAML 파일을 만듭니다.

    blue-deployment.yml:

    $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-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

  2. YAML 파일을 사용하여 배포를 만듭니다. 이 예제에서는 모든 트래픽을 새 배포로 설정합니다.

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

엔드포인트에 대한 채점 URI 가져오기

CLI를 사용하여 엔드포인트를 호출하려는 경우 CLI에서 처리하므로 채점 URI를 명시적으로 가져올 필요가 없습니다. 하지만 여전히 CLI를 사용하여 채점 URI를 가져와 REST API와 같은 다른 채널에서 사용할 수 있습니다.

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

데이터 평면 작업을 위한 키 또는 토큰 가져오기

키 또는 토큰을 가져오는 프로세스가 컨트롤 플레인 작업이기는 하지만 키 또는 토큰을 데이터 평면 작업에 사용할 수도 있습니다. 즉, 나중에 데이터 평면 작업을 수행하는 데 사용하는 키 또는 토큰을 가져오는 데 컨트롤 플레인 토큰을 사용합니다.

컨트롤 플레인 작업 대한 권한 부여에 설명된 대로, 키 또는 Azure Machine Learning 토큰을 가져오려면 역할을 요청하는 사용자 ID에 올바른 역할을 할당해야 합니다. Microsoft Entra 토큰을 가져오는 데에는 사용자 ID에 대한 추가 역할이 필요하지 않습니다.

CLI를 사용하여 엔드포인트를 호출하려는 경우 CLI가 자동으로 처리하므로 데이터 평면 작업을 위한 키 또는 토큰을 명시적으로 가져올 필요가 없습니다. 그러나 여전히 CLI를 사용하여 데이터 평면 작업을 위한 키 또는 토큰을 가져와서 REST API와 같은 다른 채널에서 사용할 수 있습니다.

데이터 평면 작업을 위한 키 또는 토큰을 가져오려면 az ml online-endpoint get-credentials 명령을 사용합니다. 이 명령은 키, 토큰 및/또는 추가 정보가 포함된 JSON 출력을 반환합니다.

팁

JSON 출력에서 특정 정보를 추출하기 위해 CLI 명령의 --query 매개 변수가 예로 사용됩니다. 하지만 이 용도에 적합한 아무 도구나 사용할 수 있습니다.

엔드포인트의 auth_mode가 key인 경우

  • 키는 primaryKey 필드와 secondaryKey 필드에서 반환됩니다.
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_mode가 aml_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_mode가 aad_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)

Microsoft Entra 토큰이 리소스 엔드포인트 및 클라이언트 ID에 적합한지 확인

Microsoft Entra 토큰을 가져온 후 jwt.ms를 통해 토큰을 디코딩하여 토큰이 Azure 리소스 엔드포인트 ml.azure.com 및 클라이언트 ID에 적합한지 확인할 수 있습니다. 그러면 다음 정보를 포함한 json 응답이 반환됩니다.

{
    "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

트래픽 기록 및 모니터링

엔드포인트에 대한 진단 설정에서 트래픽 로깅을 사용하려면 로그를 사용/사용하지 않도록 설정하는 방법의 단계를 따릅니다.

진단 설정을 사용하는 경우 AmlOnlineEndpointTrafficLogs 테이블을 확인하여 인증 모드와 사용자 ID를 확인할 수 있습니다.

관련 콘텐츠