Azure AI 서비스에 대한 요청 인증

Azure AI 서비스에 대한 각 요청에는 인증 헤더가 포함되어야 합니다. 이 헤더는 서비스 또는 서비스 그룹에 대한 구독을 확인하는 데 사용되는 리소스 키 또는 인증 토큰을 전달합니다. 이 문서에서는 요청을 인증하는 세 가지 방법과 각각에 대한 요구 사항에 대해 알아봅니다.

• 단일 서비스 또는 다중 서비스 리소스 키로 인증
• 토큰으로 인증
• Microsoft Entra ID로 인증

필수 조건

요청하기 전에 Azure 계정과 Azure AI 서비스 구독이 필요합니다. 계정이 이미 있는 경우 다음 섹션으로 건너뜁니다. 계정이 없는 경우 몇 분 만에 설정을 완료할 수 있는 가이드 Azure AI 서비스 리소스 만들기가 있습니다.

Azure Portal에서 해당 리소스로 이동합니다. 키 및 엔드포인트 섹션은 리소스 관리 섹션에서 찾을 수 있습니다. 엔드포인트 및 액세스 키를 복사합니다. API 호출을 인증하는 데 모두 필요합니다. KEY1 또는 KEY2를 사용할 수 있습니다. 항상 두 개의 키를 사용하면 서비스 중단 없이 키를 안전하게 회전하고 다시 생성할 수 있습니다.

인증 헤더

Azure AI 서비스에 사용할 수 있는 인증 헤더를 빠르게 검토해 보겠습니다.

헤더	설명
Ocp-Apim-Subscription-Key	이 헤더를 사용하여 특정 서비스에 대한 리소스 키 또는 다중 서비스 리소스 키로 인증합니다.
Ocp-Apim-Subscription-Region	이 헤더는 Azure AI 번역기 서비스와 함께 다중 서비스 리소스 키를 사용할 때만 필요합니다. 이 헤더를 사용하여 리소스 지역을 지정합니다.
Authorization	액세스 토큰을 사용하는 경우 이 헤더를 사용합니다. 토큰 교환을 수행하는 단계는 다음 섹션에서 자세히 설명합니다. 제공되는 값은 Bearer <TOKEN> 형식을 따릅니다.

단일 서비스 리소스 키로 인증

첫 번째 옵션은 Azure AI 번역기와 같은 특정 서비스에 대한 리소스 키를 사용하여 요청을 인증하는 것입니다. 이 키는 만든 각 리소스에 대해 Azure Portal에서 사용할 수 있습니다. Azure Portal에서 해당 리소스로 이동합니다. 키 및 엔드포인트 섹션은 리소스 관리 섹션에서 찾을 수 있습니다. 엔드포인트 및 액세스 키를 복사합니다. API 호출을 인증하는 데 모두 필요합니다. KEY1 또는 KEY2를 사용할 수 있습니다. 항상 두 개의 키를 사용하면 서비스 중단 없이 키를 안전하게 회전하고 다시 생성할 수 있습니다.

리소스 키를 사용하여 요청을 인증하려면 Ocp-Apim-Subscription-Key 헤더로 전달되어야 합니다. Azure AI 번역기 서비스에 대한 호출 샘플은 다음과 같습니다.

Translator 서비스에 대한 호출 샘플은 다음과 같습니다.

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

다중 서비스 리소스 키로 인증

다중 서비스 리소스 키를 사용하여 요청을 인증할 수 있습니다. 주요 차이점은 다중 서비스 리소스 키가 특정 서비스에 연결되지 않고, 오히려 단일 키를 사용하여 여러 Azure AI 서비스에 대한 요청을 인증할 수 있다는 것입니다. 지역별 가용성, 지원되는 기능 및 가격에 대한 자세한 내용은 Azure AI 서비스 가격 책정을 참조하세요.

리소스 키는 각 요청에 Ocp-Apim-Subscription-Key 헤더로 제공됩니다.

지원되는 지역

Azure AI 서비스 다중 서비스 리소스 키를 사용하여 api.cognitive.microsoft.com에 요청할 때 URL에 지역을 포함해야 합니다. 예: westus.api.cognitive.microsoft.com

Azure AI 번역기와 함께 다중 서비스 리소스 키를 사용하는 경우 Ocp-Apim-Subscription-Region 헤더로 리소스 지역을 지정해야 합니다.

다중 서비스 리소스 인증이 지원되는 지역은 다음과 같습니다.

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2
• francecentral
• koreacentral
• northcentralus
• southafricanorth
• uaenorth
• switzerlandnorth

샘플 요청

Azure AI 번역기 서비스에 대한 호출 샘플은 다음과 같습니다.

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Ocp-Apim-Subscription-Region: YOUR_SUBSCRIPTION_REGION' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

액세스 토큰으로 인증

일부 Azure AI 서비스는 액세스 토큰을 허용하고 경우에 따라 요구합니다. 현재 다음 서비스는 액세스 토큰을 지원합니다.

• Text Translation API
• 음성 서비스: 음성 텍스트 변환 API
• 음성 서비스: 텍스트 음성 변환 API

Warning

액세스 토큰을 지원하는 서비스는 시간이 지남에 따라 변경될 수 있으므로 이 인증 방법을 사용하기 전에 서비스에 대한 API 참조를 확인합니다.

단일 서비스 및 다중 서비스 리소스 키 모두 인증 토큰으로 교환될 수 있습니다. 인증 토큰은 10분 동안 유효합니다. JWT(JSON Web Token) 형식으로 저장되며 JWT 라이브러리를 사용하여 프로그래밍 방식으로 쿼리할 수 있습니다.

액세스 토큰은 요청에 Authorization 헤더로 포함됩니다. 제공되는 토큰 값은 Bearer 뒤에 나와야 합니다(예: Bearer YOUR_AUTH_TOKEN).

샘플 요청

액세스 토큰에 대한 리소스 키를 교환하려면 다음 URL을 사용하세요: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken.

curl -v -X POST \
"https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

토큰 교환을 지원하는 다중 서비스 지역은 다음과 같습니다.

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2

액세스 토큰을 받은 후에는 각 요청에서 이를 Authorization 헤더로 전달해야 합니다. Azure AI 번역기 서비스에 대한 호출 샘플은 다음과 같습니다.

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Microsoft Entra ID로 인증

Important

Microsoft Entra 인증은 항상 Azure 리소스의 사용자 지정 하위 도메인 이름과 함께 사용해야 합니다. 지역별 엔드포인트는 Microsoft Entra 인증을 지원하지 않습니다.

이전 섹션에서는 단일 서비스 또는 다중 서비스 구독 키를 사용하여 Azure AI 서비스에 대해 인증하는 방법을 보여주었습니다. 이러한 키를 이용하면 빠르고 쉽게 개발을 시작할 수 있지만 Azure RBAC(역할 기반 액세스 제어)를 필요로 하는 더 복잡한 시나리오에서는 한계가 있습니다. Microsoft Entra ID를 사용하여 인증하는 데 필요한 사항을 살펴보겠습니다.

다음 섹션에서는 Azure Cloud Shell 환경 또는 Azure CLI를 사용하여 하위 도메인을 만들고, 역할을 할당하고, Azure AI 서비스를 호출하기 위한 전달자 토큰을 얻습니다. 작업하면서 어려움에 처할 경우를 위해 각 세션에서는 Azure Cloud Shell/Azure CLI의 각 명령에 대해 사용 가능한 모든 옵션이 있는 링크가 제공됩니다.

Important

조직에서 Microsoft Entra ID를 통해 인증을 수행하는 경우 조직의 사용자가 항상 Microsoft Entra ID를 사용해야 하도록 로컬 인증을 사용하지 않도록 설정(키를 사용한 인증)해야 합니다.

사용자 지정 하위 도메인을 사용하여 리소스 만들기

먼저 사용자 지정 하위 도메인을 만들어야 합니다. 사용자 지정 하위 도메인 이름이 없는 기존 Azure AI 서비스 리소스를 사용하려면 Azure AI 서비스 사용자 지정 하위 도메인의 지침에 따라 리소스에 대한 사용자 지정 하위 도메인을 활성화하세요.

1. Azure Cloud Shell을 열어 시작합니다. 그런 다음, 구독을 선택합니다.

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. 그런 다음 사용자 지정 하위 도메인을 사용하여 Azure AI 서비스 리소스를 생성합니다. 하위 도메인 이름은 전역적으로 고유해야 하며 특수 문자(예: ".", "!", ",")를 포함할 수 없습니다.

   $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
   

3. 성공하는 경우 엔드포인트는 리소스에 고유한 하위 도메인 이름을 표시해야 합니다.

서비스 주체에 역할 할당

이제 리소스와 연결된 사용자 지정 하위 도메인이 있으므로 서비스 주체에 역할을 할당해야 합니다.

참고 항목

Azure 역할 할당을 전파하는 데 최대 5분이 소요될 수 있습니다.

1. 먼저 Microsoft Entra 애플리케이션을 등록합니다.

   $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force
   
   $app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword
   

   다음 단계에서 ApplicationId가 필요합니다.

2. 다음으로 Microsoft Entra 애플리케이션의 서비스 주체를 만들어야 합니다.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   참고 항목

   Azure Portal에 애플리케이션을 등록하면 이 단계가 완료됩니다.

3. 마지막 단계는 서비스 주체(리소스로 범위 지정)에 "Cognitive Services 사용자" 역할을 할당하는 것입니다. 역할을 할당함으로써 서비스 주체에게 이 리소스에 대한 액세스 권한을 부여하게 됩니다. 동일한 서비스 주체에게 구독에서 여러 리소스에 대한 액세스 권한을 부여할 수 있습니다.

   참고 항목

   애플리케이션에 대한 ObjectId가 아닌 서비스 주체의 ObjectId가 사용됩니다. ACCOUNT_ID는 사용자가 만든 Azure AI 서비스 계정의 Azure 리소스 ID입니다. Azure Portal에서 리소스의 "속성"에서 Azure 리소스 ID를 찾을 수 있습니다.

   New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
   

샘플 요청

이 샘플에서는 암호를 사용하여 서비스 주체를 인증합니다. 그런 다음, 제공된 토큰을 사용하여 Computer Vision API를 호출합니다.

1. TenantId 가져오기:

   $context=Get-AzContext
   $context.Tenant.Id
   

2. 토큰 가져오기:

   $tenantId = $context.Tenant.Id
   $clientId = $app.ApplicationId
   $clientSecret = "<YOUR_PASSWORD>"
   $resourceUrl = "https://cognitiveservices.azure.com/"
   
   $tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
   $body = @{
       grant_type    = "client_credentials"
       client_id     = $clientId
       client_secret = $clientSecret
       resource      = $resourceUrl
   }
   
   $responseToken = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body
   $accessToken = $responseToken.access_token
   

   참고 항목

   스크립트에서 암호를 사용할 때 가장 안전한 옵션은 PowerShell 비밀 관리 모듈을 사용하고 Azure Key Vault와 같은 솔루션과 통합하는 것입니다.

3. Computer Vision API 호출하기:

   $url = $account.Endpoint+"vision/v1.0/models"
   $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"="Bearer $accessToken"} -Verbose
   $result | ConvertTo-Json
   

다른 방법으로는 인증서를 사용하여 서비스 주체를 인증할 수 있습니다. 서비스 주체 외에도 다른 Microsoft Entra 애플리케이션을 통해 권한을 위임하면 사용자 계정도 지원됩니다. 이 경우 토큰을 가져올 때 암호 또는 인증서 대신 사용자에게 2단계 인증을 요구하는 메시지가 표시됩니다.

관리 ID에 대한 액세스 권한 부여

Azure AI 서비스는 Azure 리소스에 대한 관리 ID를 사용하는 Microsoft Entra 인증을 지원합니다. Azure 리소스에 대한 관리 ID는 Azure VM(가상 머신), 함수 앱, 가상 머신 확장 집합 및 기타 서비스에서 실행되는 애플리케이션의 Microsoft Entra 자격 증명을 사용하여 Azure AI 서비스 리소스에 대한 액세스 권한을 부여할 수 있습니다. Microsoft Entra 인증과 함께 Azure 리소스에 대한 관리 ID를 사용하면 클라우드에서 실행되는 응용 프로그램에 자격 증명을 저장할 필요가 없습니다.

VM에서 관리 ID 사용

Azure 리소스에 대한 관리 ID를 사용하여 VM에서 Azure AI 서비스 리소스에 대한 액세스 권한을 부여하려면 먼저 VM에서 Azure 리소스에 대한 관리 ID를 사용하도록 설정해야 합니다. Azure 리소스의 관리 ID를 사용하도록 설정하는 방법을 알아보려면 다음을 참조하세요.

• Azure Portal
• Azure PowerShell
• Azure CLI
• Azure Resource Manager 템플릿
• Azure Resource Manager 클라이언트 라이브러리

관리 ID에 대한 자세한 내용은 Azure 리소스의 관리 ID를 참조하세요.

Azure 키 자격 증명 모음을 사용하여 자격 증명에 안전하게 액세스

Azure Key Vault를 사용하여 Azure AI 서비스 애플리케이션을 안전하게 개발할 수 있습니다. Key Vault를 사용하면 인증 자격 증명을 클라우드에 저장할 수 있으며 애플리케이션에 보안 정보를 저장하지 않으므로 비밀이 실수로 유출될 가능성을 줄일 수 있습니다.

인증이 Microsoft Entra ID를 통해 수행됩니다. 권한 부여는 Azure RBAC(Azure 역할 기반 액세스 제어) 또는 Key Vault 액세스 정책을 통해 수행할 수 있습니다. Azure RBAC는 자격 증명 모음을 관리하고 자격 증명 모음에 저장된 데이터에 액세스하는 데 사용할 수 있지만 키 자격 증명 모음 액세스 정책은 자격 증명 모음에 저장된 데이터에 액세스하려는 경우에만 사용할 수 있습니다.

참고 항목

• Azure AI 서비스란?
• Azure AI 서비스 가격
• 사용자 지정 하위 도메인