Rantai kredensial di pustaka klien Azure Identity untuk C++

Pustaka klien Azure Identity menyediakan kredensial—jenis publik yang berasal dari kelas dasar abstrak TokenCredential pustaka Azure Core. Kredensial mewakili alur autentikasi yang berbeda untuk memperoleh token akses dari ID Microsoft Entra. Kredensial ini dapat ditautkan bersama untuk membentuk urutan mekanisme autentikasi yang akan dicoba.

Cara kerja kredensial berantai

Selama runtime, rantai kredensial mencoba mengautentikasi menggunakan kredensial pertama dalam 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 memberikan manfaat sebagai 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)
  std::shared_ptr<Azure::Core::Credentials::TokenCredential> credential;
  if (std::getenv("WEBSITE_HOSTNAME"))
  {
      credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>();
  }
  else
  {
      credential = std::make_shared<Azure::Identity::AzureCliCredential>();
  }
  

• 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 C++, ada dua pilihan untuk rantai kredensial:

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

Gambaran Umum DefaultAzureCredential

DefaultAzureCredential adalah rantai kredensial yang telah dikonfigurasi sebelumnya dengan preferensi tertentu. Desainnya 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 menguji 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 yang Dikelola	Jika aplikasi disebarkan ke host Azure dengan Identitas Terkelola diaktifkan, autentikasi aplikasi ke Azure menggunakan Identitas Terkelola tersebut.
4	Azure CLI	Jika pengembang mengautentikasi ke Azure menggunakan perintah Azure CLI az login , autentikasi aplikasi ke Azure menggunakan akun yang sama.

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

#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

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:

Ketika sebuah nilai dev digunakan, rantai hanya menyertakan AzureCliCredential.

Untuk memastikan variabel lingkungan ditentukan dan diatur ke string yang didukung, teruskan true ke DefaultAzureCredential konstruktor:

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Penting

Kelebihan beban konstruktor yang disebutkan di atas didukung pada paket azure-identity-cpp versi 1.13.1 dan yang lebih baru.

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
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Untuk memastikan variabel lingkungan ditentukan dan diatur ke string yang didukung, teruskan true ke DefaultAzureCredential konstruktor:

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Penting

Kelebihan beban konstruktor yang disebutkan di atas didukung pada paket azure-identity-cpp versi 1.13.1 dan yang lebih baru.

Gambaran umum ChainedTokenCredential

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

#include <azure/identity/azure_cli_credential.hpp>
#include <azure/identity/chained_token_credential.hpp>
#include <azure/identity/managed_identity_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
        Azure::Identity::ChainedTokenCredential::Sources{
            std::make_shared<Azure::Identity::ManagedIdentityCredential>(),
            std::make_shared<Azure::Identity::AzureCliCredential>()});

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

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

Petunjuk / 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 termudah untuk memulai pustaka klien Azure Identity, tetapi dengan kemudahan tersebut datang dengan 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 keberhasilan/kegagalan masing-masing. Untuk informasi selengkapnya, lihat Mendebug rantai kredensial.
• Beban performa: Proses mencoba beberapa kredensial secara berurutan dapat menyebabkan beban pada performa. Misalnya, saat berjalan pada komputer pengembangan lokal, identitas terkelola tidak tersedia. Akibatnya, ManagedIdentityCredential selalu gagal di lingkungan pengembangan lokal.
• Perilaku yang tidak dapat diprediksi: DefaultAzureCredential 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.

Menyelidiki kredensial berantai

Untuk mendiagnosis masalah yang tidak terduga atau untuk memahami apa yang dilakukan kredensial berantai, aktifkan pengelogan di aplikasi Anda. Untuk tujuan ilustrasi, asumsikan bentuk DefaultAzureCredential tanpa parameter digunakan untuk mengautentikasi permintaan ke akun Blob Storage. Aplikasi ini berjalan di lingkungan pengembangan lokal, dan pengembang diautentikasi ke Azure menggunakan Azure CLI. Saat aplikasi dijalankan, entri terkait berikut muncul dalam output:

DEBUG : Identity: Creating DefaultAzureCredential which combines multiple parameterless credentials into a single one.
DefaultAzureCredential is only recommended for the early stages of development, and not for usage in production environment.
Once the developer focuses on the Credentials and Authentication aspects of their application, DefaultAzureCredential needs to be replaced with the credential that is the better fit for the application.
INFO  : Identity: EnvironmentCredential gets created with ClientSecretCredential.
DEBUG : Identity: EnvironmentCredential: 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', and 'AZURE_CLIENT_SECRET' environment variables are set, so ClientSecretCredential with corresponding tenantId, clientId, and clientSecret gets created.
WARN  : Identity: Azure Kubernetes environment is not set up for the WorkloadIdentityCredential credential to work.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2019 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2017 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Cloud Shell source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Azure Arc source.
INFO  : Identity: ManagedIdentityCredential will be created with Azure Instance Metadata Service source.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: AzureCliCredential created.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: DefaultAzureCredential: Created with the following credentials: EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, AzureCliCredential.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from EnvironmentCredential: GetToken(): error response: 400 Bad Request

{"error":"invalid_grant","error_description":"AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance. Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2025-03-07 21:25:44Z","error_codes":[53003],"timestamp":"2025-03-07 21:25:44Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd","error_uri":"https://login.microsoftonline.com/error?code=53003","suberror":"message_only","claims":"{\"access_token\":{\"capolids\":{\"essential\":true,\"values\":[\"cccc2222-dd33-4444-55ee-666666ffffff\"]}}}"}
WARN  : Identity: WorkloadIdentityCredential authentication unavailable. See earlier WorkloadIdentityCredential log messages for details.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from WorkloadIdentityCredential: WorkloadIdentityCredential authentication unavailable. Azure Kubernetes environment is not set up correctly.
INFO  : Identity: DefaultAzureCredential: Successfully got token from ManagedIdentityCredential. This credential will be reused for subsequent calls.
DEBUG : Identity: DefaultAzureCredential: Saved this credential at index 2 for subsequent calls.

Pada output sebelumnya, perhatikan bahwa:

• EnvironmentCredential, WorkloadIdentityCredential, dan ManagedIdentityCredential masing-masing gagal memperoleh token akses Microsoft Entra, dalam urutan tersebut.
• ManagedIdentityCredential berhasil, seperti yang ditunjukkan oleh entri yang dimulai dengan "Successfully got token from ManagedIdentityCredential".