Mengautentikasi permintaan ke layanan Azure AI

Setiap permintaan ke layanan Azure AI harus menyertakan header autentikasi. Header ini meneruskan kunci sumber daya atau token autentikasi, yang digunakan untuk memvalidasi langganan Anda untuk layanan atau grup layanan. Dalam artikel ini, Anda akan mempelajari tentang tiga cara untuk mengautentikasi permintaan dan persyaratan untuk masing-masing.

• Mengautentikasi dengan kunci sumber daya layanan tunggal atau multi-layanan
• Mengautentikasi dengan token
• Mengautentikasi dengan ID Microsoft Entra

Prasyarat

Sebelum membuat permintaan, Anda memerlukan akun Azure dan langganan layanan Azure AI. Jika Anda sudah memiliki akun, lanjutkan dan lompati ke bagian berikutnya. Jika Anda tidak memiliki akun, kami memiliki panduan untuk menyiapkan Anda dalam hitung menit: Membuat sumber daya layanan Azure AI.

Buka sumber daya Anda di portal Azure. Bagian Kunci & Titik Akhir dapat ditemukan di bagian Manajemen Sumber Daya. Salin titik akhir dan kunci akses Anda karena keduanya diperlukan untuk mengautentikasi panggilan API Anda. Anda dapat menggunakan KEY1 atau KEY2. Selalu miliki dua kunci untuk memungkinkan Anda memutar dan meregenerasi kunci dengan aman tanpa menyebabkan gangguan layanan.

Header autentikasi

Mari kita tinjau header autentikasi yang tersedia untuk digunakan dengan layanan Azure AI dengan cepat.

Header	Deskripsi
Ocp-Apim-Subscription-Key	Gunakan header ini untuk mengautentikasi dengan kunci sumber daya untuk layanan tertentu atau kunci sumber daya multi-layanan.
Ocp-Apim-Subscription-Region	Header ini hanya diperlukan saat menggunakan kunci sumber daya multi-layanan dengan layanan Penerjemah Azure AI. Gunakan header ini untuk menentukan wilayah sumber daya.
Authorization	Gunakan header ini jika Anda menggunakan token akses. Langkah-langkah untuk melakukan pertukaran token dirinci di bagian berikut. Nilai yang diberikan mengikuti format ini: Bearer <TOKEN>.

Mengautentikasi dengan kunci sumber daya layanan tunggal

Opsi pertama adalah mengautentikasi permintaan dengan kunci sumber daya untuk layanan tertentu, seperti Penerjemah Azure AI. Kunci tersedia di portal Azure untuk setiap sumber daya yang telah Anda buat. Buka sumber daya Anda di portal Azure. Bagian Kunci & Titik Akhir dapat ditemukan di bagian Manajemen Sumber Daya. Salin titik akhir dan kunci akses Anda karena keduanya diperlukan untuk mengautentikasi panggilan API Anda. Anda dapat menggunakan KEY1 atau KEY2. Selalu miliki dua kunci untuk memungkinkan Anda memutar dan meregenerasi kunci dengan aman tanpa menyebabkan gangguan layanan.

Untuk menggunakan kunci sumber daya untuk mengautentikasi permintaan, kunci tersebut harus diteruskan sebagai Ocp-Apim-Subscription-Key header. Ini adalah contoh panggilan ke layanan Penerjemah Azure AI:

Ini adalah panggilan sampel ke layanan Penerjemah:

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

Mengautentikasi dengan kunci sumber daya multi-layanan

Anda dapat menggunakan kunci sumber daya multi-layanan untuk mengautentikasi permintaan. Perbedaan utamanya adalah bahwa kunci sumber daya multi-layanan tidak terkait dengan layanan tertentu, melainkan, satu kunci dapat digunakan untuk mengautentikasi permintaan untuk beberapa layanan Azure AI. Lihat Harga layanan Azure AI untuk informasi tentang ketersediaan regional, fitur yang didukung, dan harga.

Kunci sumber daya disediakan di setiap permintaan sebagai Ocp-Apim-Subscription-Key header.

Wilayah yang didukung

Saat menggunakan kunci sumber daya multi-layanan layanan Azure AI untuk membuat permintaan ke api.cognitive.microsoft.com, Anda harus menyertakan wilayah dalam URL. Misalnya: westus.api.cognitive.microsoft.com.

Saat menggunakan kunci sumber daya multi-layanan dengan Penerjemah Azure AI, Anda harus menentukan wilayah sumber daya dengan Ocp-Apim-Subscription-Region header.

Autentikasi sumber daya multi-layanan didukung di wilayah ini:

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

Sampel permintaan

Ini adalah contoh panggilan ke layanan Penerjemah 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

Mengautentikasi dengan token akses

Beberapa layanan Azure AI menerima, dan dalam beberapa kasus memerlukan token akses. Saat ini, layanan ini mendukung token akses:

• API Terjemahan Teks
• Layanan Ucapan: API Ucapan ke teks
• Layanan Ucapan: API teks ke ucapan

Peringatan

Layanan yang mendukung token akses dapat berubah seiring waktu, harap periksa referensi API untuk suatu layanan sebelum menggunakan metode autentikasi ini.

Kunci sumber daya layanan tunggal dan multi-layanan dapat ditukar dengan token autentikasi. Token autentikasi berlaku selama 10 menit. Mereka disimpan dalam format JSON Web Token (JWT) dan dapat dikueri secara terprogram menggunakan pustaka JWT.

Token akses disertakan dalam permintaan sebagai header Authorization. Nilai token yang diberikan harus didahului oleh Bearer, misalnya: Bearer YOUR_AUTH_TOKEN.

Sampel permintaan

Gunakan URL ini untuk menukar kunci sumber daya dengan token akses: 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"

Wilayah multi-layanan ini mendukung pertukaran token:

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

Setelah mendapatkan token akses, Anda harus meneruskannya di setiap permintaan sebagai header Authorization. Ini adalah contoh panggilan ke layanan Penerjemah 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

Autentikasi dengan Microsoft Entra ID

Penting

Autentikasi Microsoft Entra selalu perlu digunakan bersama dengan nama subdomain kustom sumber daya Azure Anda. Titik akhir regional tidak mendukung autentikasi Microsoft Entra.

Di bagian sebelumnya, kami menunjukkan kepada Anda cara mengautentikasi terhadap layanan Azure AI menggunakan kunci langganan layanan tunggal atau multi-layanan. Meskipun kunci ini menyediakan jalur yang cepat dan mudah untuk memulai pengembangan, kunci tersebut terlena dalam skenario yang lebih kompleks yang memerlukan kontrol akses berbasis peran Azure (Azure RBAC). Mari kita lihat apa yang diperlukan untuk mengautentikasi menggunakan ID Microsoft Entra.

Di bagian berikut, Anda akan menggunakan lingkungan Azure Cloud Shell atau Azure CLI untuk membuat subdomain, menetapkan peran, dan mendapatkan token pembawa untuk memanggil layanan Azure AI. Jika Anda terjebak, tautan disediakan di setiap bagian dengan semua opsi yang tersedia untuk setiap perintah di Azure Cloud Shell/Azure CLI.

Penting

Jika organisasi Anda melakukan autentikasi melalui ID Microsoft Entra, Anda harus menonaktifkan autentikasi lokal (autentikasi dengan kunci) sehingga pengguna di organisasi harus selalu menggunakan ID Microsoft Entra.

Membuat sumber daya dengan subdomain kustom

Langkah pertama adalah membuat subdomain kustom. Jika Anda ingin menggunakan sumber daya layanan Azure AI yang sudah ada yang tidak memiliki nama subdomain kustom, ikuti instruksi di subdomain kustom layanan Azure AI untuk mengaktifkan subdomain kustom untuk sumber daya Anda.

1. Mulai dengan membuka Azure Cloud Shell. Kemudian pilih langganan:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. Selanjutnya, buat sumber daya layanan Azure AI dengan subdomain kustom. Nama subdomain harus unik secara global dan tidak dapat menyertakan karakter khusus, seperti: ".", "!", ",".

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

3. Jika berhasil, peserta harus menampilkan nama subdomain yang unik untuk sumber daya Anda.

Menetapkan peran ke perwakilan layanan

Sekarang setelah Anda memiliki subdomain khusus yang terkait dengan sumber daya Anda, Anda harus menetapkan peran untuk kepala layanan.

Catatan

Ingatlah bahwa penetapan peran Azure mungkin membutuhkan waktu hingga lima menit untuk disebarluaskan.

1. Pertama, mari kita daftarkan aplikasi Microsoft Entra.

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

   Anda akan membutuhkan ApplicationId di langkah berikutnya.

2. Selanjutnya, Anda perlu membuat perwakilan layanan untuk aplikasi Microsoft Entra.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Catatan

   Jika Anda mendaftarkan aplikasi di portal Microsoft Azure, langkah ini selesai untuk Anda.

3. Langkah terakhir adalah menetapkan peran "Pengguna Azure Cognitive Services" ke perwakilan layanan (tercakup ke sumber daya). Dengan menetapkan peran, Anda memberikan akses pokok layanan ke sumber daya ini. Anda dapat memberikan akses pokok layanan yang sama ke beberapa sumber daya dalam langganan Anda.

   Catatan

   ObjectId dari perwakilan layanan digunakan, bukan ObjectId untuk aplikasi. ACCOUNT_ID akan menjadi Id sumber daya Azure dari akun layanan Azure AI yang Anda buat. Anda dapat menemukan Id sumber daya Azure dari "properti" sumber daya di portal Microsoft Azure.

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

Permintaan sampel

Dalam sampel ini, kata sandi digunakan untuk mengotentikasi perwakilan layanan. Token yang disediakan kemudian digunakan untuk memanggil Computer Vision API.

1. Dapatkan TenantId Anda:

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

2. Mendapatkan token:

   $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
   

   Catatan

   Setiap kali Anda menggunakan kata sandi dalam skrip, opsi yang paling aman adalah menggunakan modul Manajemen Rahasia PowerShell dan berintegrasi dengan solusi seperti Azure Key Vault.

3. Hubungi 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
   

Atau, perwakilan layanan dapat diautentikasi dengan sertifikat. Selain perwakilan layanan, perwakilan pengguna juga didukung dengan memiliki izin yang didelegasikan melalui aplikasi Microsoft Entra lainnya. Dalam hal ini, alih-alih kata sandi atau sertifikat, pengguna akan diminta untuk autentikasi dua faktor saat memperoleh token.

Mengotorisasi akses ke identitas terkelola

Layanan Azure AI mendukung autentikasi Microsoft Entra dengan identitas terkelola untuk sumber daya Azure. Identitas terkelola untuk sumber daya Azure dapat mengotorisasi akses ke sumber daya layanan Azure AI menggunakan kredensial Microsoft Entra dari aplikasi yang berjalan di komputer virtual (VM) Azure, aplikasi fungsi, set skala komputer virtual, dan layanan lainnya. Dengan menggunakan identitas terkelola untuk sumber daya Azure bersama dengan autentikasi Microsoft Entra, Anda dapat menghindari penyimpanan kredensial dengan aplikasi Anda yang berjalan di cloud.

Mengaktifkan identitas terkelola pada VM

Sebelum Anda dapat menggunakan identitas terkelola untuk sumber daya Azure untuk mengotorisasi akses ke sumber daya layanan Azure AI dari VM, Anda harus mengaktifkan identitas terkelola untuk sumber daya Azure di VM. Untuk mempelajari cara mengaktifkan identitas terkelola untuk Azure Resources, lihat:

• Portal Azure
• Azure PowerShell
• Azure CLI
• Templat Azure Resource Manager
• Pustaka klien Azure Resource Manager

Untuk informasi selengkapnya tentang identitas terkelola, lihat Identitas terkelola untuk sumber daya Azure.

Menggunakan brankas kunci Azure untuk mengakses kredensial dengan aman

Anda dapat menggunakan Azure Key Vault untuk mengembangkan aplikasi layanan Azure AI dengan aman. Key Vault memungkinkan Anda menyimpan kredensial autentikasi di cloud, dan mengurangi kemungkinan rahasia bocor secara tidak sengaja, karena Anda tidak akan menyimpan informasi keamanan di aplikasi Anda.

Autentikasi dilakukan melalui ID Microsoft Entra. Otorisasi dapat dilakukan melalui kontrol akses berbasis peran Azure (Azure RBAC) atau kebijakan akses Key Vault. RBAC Azure dapat digunakan untuk pengelolaan brankas dan mengakses data yang disimpan dalam brankas, sementara kebijakan akses brankas kunci hanya dapat digunakan ketika mencoba mengakses data yang disimpan di brankas.

Lihat juga

• Apa itu layanan Azure AI?
• Harga layanan Azure AI
• Subdomain kustom