Rantai kredensial di pustaka Azure Identity untuk Go

Pustaka Azure Identity menyediakan kredensial —jenis publik yang mengimplementasikan antarmuka TokenCredential pustaka Azure Core. Kredensial mewakili alur autentikasi yang berbeda untuk memperoleh token akses dari ID Microsoft Entra. Kredensial ini dapat dirangkaikan bersama untuk membentuk urutan mekanisme autentikasi yang diurutkan dan dapat dicoba.

Cara kerja kredensial berantai

Pada saat runtime, rantai kredensial mencoba untuk mengautentikasi menggunakan kredensial pertama dari urutan. Jika kredensial tersebut gagal memperoleh token akses, kredensial berikutnya dalam urutan dicoba, dan sebagainya, hingga token akses berhasil diperoleh. Diagram urutan berikut mengilustrasikan perilaku ini:

Mengapa menggunakan rantai kredensial

Kredensial berantai dapat menawarkan manfaat berikut:

• Kesadaran lingkungan: Secara otomatis memilih kredensial yang paling tepat berdasarkan lingkungan tempat aplikasi berjalan. Tanpa itu, Anda harus menulis kode seperti ini:

  // Set up credential based on environment (Azure or local development)
  if os.Getenv("WEBSITE_HOSTNAME") != "" {
      clientID := azidentity.ClientID("abcd1234-...")
      opts := azidentity.ManagedIdentityCredentialOptions{ID: clientID}
      credential, err = azidentity.NewManagedIdentityCredential(&opts)
  
      if err != nil {
        // TODO: handle error
      }
  } else {
      // Use Azure CLI Credential
      credential, err = azidentity.NewAzureCLICredential(nil)
  
      if err != nil {
        // TODO: handle error
      }
  }
  

• Transisi tanpa hambatan: Aplikasi Anda dapat berpindah dari pengembangan lokal ke lingkungan penahapan atau produksi Anda tanpa mengubah kode autentikasi.

• Peningkatan ketahanan: Menyertakan mekanisme fallback yang berpindah ke kredensial berikutnya ketika sebelumnya gagal memperoleh token akses.

Cara memilih kredensial berantai

Dengan bahasa pemrograman Go, ada dua pilihan untuk penautan kredensial:

• Gunakan rantai yang telah dikonfigurasi sebelumnya: Gunakan rantai yang telah dikonfigurasi sebelumnya yang diterapkan oleh jenis DefaultAzureCredential. Untuk pendekatan ini, lihat gambaran umum DefaultAzureCredential pada bagian.
• Bangun rantai kredensial kustom: Mulailah dengan rantai kosong dan sertakan hanya apa yang Anda butuhkan. Untuk pendekatan ini, lihat bagian gambaran umum ChainedTokenCredential.

Gambaran Umum DefaultAzureCredential

DefaultAzureCredential adalah serangkaian kredensial yang memiliki konfigurasi awal yang sudah ditentukan. Ini dirancang untuk mendukung banyak lingkungan, bersama dengan alur autentikasi dan alat pengembang yang paling umum. Dalam bentuk grafis, rantai yang mendasar terlihat seperti ini:

Urutan di mana DefaultAzureCredential mencoba kredensial adalah sebagai berikut.

Pesanan	Bukti Identitas	Deskripsi
1	Lingkungan	Membaca kumpulan variabel lingkungan untuk menentukan apakah pengguna aplikasi (perwakilan layanan aplikasi) telah dikonfigurasi untuk aplikasi tersebut. Jika demikian, DefaultAzureCredential menggunakan nilai-nilai ini untuk mengautentikasi aplikasi ke Azure. Metode ini paling sering digunakan di lingkungan server tetapi juga dapat digunakan saat mengembangkan secara lokal.
2	Identitas Beban Kerja	Jika aplikasi disebarkan ke host Azure dengan Identitas Beban Kerja diaktifkan, autentikasi akun tersebut.
3	Identitas Terkelola	Jika aplikasi disebarkan ke host Azure dengan Identitas Terkelola diaktifkan, autentikasi aplikasi ke Azure menggunakan Identitas Terkelola tersebut.
4	Azure CLI	Jika pengembang diautentikasi ke Azure menggunakan perintah az login Azure CLI, autentikasi aplikasi ke Azure menggunakan akun yang sama.
5	Azure CLI Pengembang	Jika pengembang mengautentikasi ke Azure menggunakan perintah azd auth login Azure Developer CLI, autentikasi dengan akun tersebut.
6	Azure PowerShell	Jika pengembang mengautentikasi ke Azure menggunakan cmdlet Azure PowerShell, autentikasi dengan akun tersebut Connect-AzAccount .

Dalam bentuk yang paling sederhana, Anda dapat menggunakan versi DefaultAzureCredential tanpa parameter sebagai berikut:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

// create a credential
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    // TODO: handle error
}

// create a Blob service client 
accountURL := "https://<my_account_name>.blob.core.windows.net"
client, err := azblob.NewClient(accountURL, credential, nil)
if err != nil {
    // TODO: handle error
}

Cara menyesuaikan DefaultAzureCredential

Bagian berikut menjelaskan strategi untuk mengontrol kredensial mana yang disertakan dalam rantai.

Mengecualikan kategori jenis kredensial

Untuk mengecualikan semua Developer tool atau Deployed service kredensial, atur variabel AZURE_TOKEN_CREDENTIALS lingkungan ke prod atau dev, masing-masing. Saat nilai prod digunakan, rantai kredensial yang mendasar terlihat sebagai berikut:

Saat nilai dev digunakan, rantai terlihat sebagai berikut:

Penting

Variabel AZURE_TOKEN_CREDENTIALS lingkungan didukung dalam azidentity modul versi 1.10.0 dan yang lebih baru.

Untuk memastikan variabel lingkungan ditentukan, atur opsi RequireAzureTokenCredentials ke true:

opts := azidentity.DefaultAzureCredentialOptions{RequireAzureTokenCredentials: true}
credential, err := azidentity.NewDefaultAzureCredential(&opts)
if err != nil {
    // TODO: handle error
}

Menggunakan kredensial tertentu

Untuk mengecualikan semua kredensial kecuali satu, atur variabel AZURE_TOKEN_CREDENTIALS lingkungan ke nama kredensial. Misalnya, Anda dapat mengurangi DefaultAzureCredential rantai menjadi AzureCLICredential dengan mengatur AZURE_TOKEN_CREDENTIALS ke AzureCLICredential. Perbandingan string dilakukan dengan cara yang tidak peka huruf besar/kecil. Nilai string yang valid untuk variabel lingkungan meliputi:

• AzureCLICredential
• AzureDeveloperCLICredential
• AzurePowerShellCredential
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Penting

Variabel AZURE_TOKEN_CREDENTIALS lingkungan mendukung nama kredensial individual dalam azidentity modul versi 1.11.0 dan yang lebih baru.

Untuk memastikan variabel lingkungan ditentukan, atur opsi RequireAzureTokenCredentials ke true:

opts := azidentity.DefaultAzureCredentialOptions{RequireAzureTokenCredentials: true}
credential, err := azidentity.NewDefaultAzureCredential(&opts)
if err != nil {
    // TODO: handle error
}

Gambaran umum ChainedTokenCredential

ChainedTokenCredential adalah rantai kosong yang Anda tambahkan kredensialnya agar sesuai dengan kebutuhan aplikasi Anda. Misalnya:

azCLI, err := azidentity.NewAzureCLICredential(nil)
if err != nil {
  // handle error
}

azdCLI, err := azidentity.NewAzureDeveloperCLICredential(nil)
if err != nil {
  // handle error
}

chain, err := azidentity.NewChainedTokenCredential([]azcore.TokenCredential{azCLI, azdCLI}, nil)
if err != nil {
  // handle error
}

Sampel kode sebelumnya membuat rantai kredensial yang disesuaikan yang terdiri dari dua kredensial. AzureCLICredential dicoba terlebih dahulu, diikuti oleh AzureDeveloperCLICredential, jika perlu. Dalam bentuk grafis, rantai terlihat seperti ini:

diagram

Saran

Untuk peningkatan performa, optimalkan pengurutan kredensial dalam ChainedTokenCredential dari kredensial yang paling banyak hingga paling sedikit digunakan.

Panduan penggunaan untuk DefaultAzureCredential

DefaultAzureCredential tidak diragukan lagi adalah cara paling mudah untuk memulai dengan pustaka Azure Identity, tetapi dengan kenyamanan itu ada kompromi. Setelah menyebarkan aplikasi ke Azure, Anda harus memahami persyaratan autentikasi aplikasi. Untuk alasan itu, ganti DefaultAzureCredential dengan implementasi TokenCredential tertentu, seperti ManagedIdentityCredential.

Berikut alasannya:

• Tantangan debugging: Ketika autentikasi gagal, mungkin sulit untuk men-debug dan mengidentifikasi kredensial yang menyinggung. Anda harus mengaktifkan pencatatan log untuk melihat perkembangan dari satu kredensial ke kredensial berikutnya dan status berhasil/gagal dari masing-masing. Untuk informasi selengkapnya, lihat Mendebug rantai kredensial.
• Beban Performa: Proses mencoba beberapa kredensial secara berurutan dapat menyebabkan beban performa. Misalnya, saat berjalan pada komputer pengembangan lokal, identitas terkelola tidak tersedia. Akibatnya, ManagedIdentityCredential senantiasa gagal di lingkungan pengembangan lokal, kecuali jika dinonaktifkan secara eksplisit melalui properti dengan awalan excludeyang sesuai.
• perilaku yang tidak dapat diprediksi : memeriksa keberadaan variabel lingkungan tertentu. Ada kemungkinan bahwa seseorang dapat menambahkan atau memodifikasi variabel lingkungan ini di tingkat sistem pada komputer host. Perubahan tersebut berlaku secara global dan oleh karena itu mengubah perilaku DefaultAzureCredential pada runtime di aplikasi apa pun yang berjalan di komputer tersebut.

Memperbaiki kredensial rantai

Untuk mendiagnosis masalah yang tidak terduga atau memahami apa yang dilakukan oleh kredensial berantai, aktifkan pencatatan log di aplikasi Anda. Secara opsional, memfilter log hanya untuk peristiwa yang dikeluarkan dari pustaka klien Azure Identity. Misalnya:

import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
// print log output to stdout
azlog.SetListener(func(event azlog.Event, s string) {
    fmt.Println(s)
})
// include only azidentity credential logs
azlog.SetEvents(azidentity.EventAuthentication)

Untuk panduan tentang mengatasi kesalahan dari jenis kredensial tertentu, lihat panduan pemecahan masalah .