pustaka klien Azure Identity untuk C - versi 1.13.3

++

Pustaka identitas Azure menyediakan dukungan autentikasi berbasis token Microsoft Entra ID di seluruh Azure SDK. Ini menyediakan serangkaian TokenCredential implementasi yang dapat digunakan untuk membangun klien Azure SDK yang mendukung autentikasi token Microsoft Entra. Pustaka ini mengikuti Panduan Desain Azure SDK untuk C++.

Kode sumber | Paket (vcpkg) | Dokumentasi | referensi APIDokumentasi | Sampel

Memulai Langkah Pertama

Prasyarat

  • vcpkg untuk akuisisi paket dan manajemen dependensi
  • CMake untuk build proyek
  • langganan Azure
  • Azure CLI juga dapat berguna untuk mengautentikasi di lingkungan pengembangan, membuat akun, dan mengelola peran akun.

Pasang paketnya

Cara term mudah untuk memperoleh C++ SDK adalah memanfaatkan manajer paket vcpkg dan CMake. Lihat bagian readme Azure SDK untuk C++ yang sesuai. Kita akan menggunakan vcpkg dalam mode manifes. Untuk memulai proyek vcpkg dalam mode manifes, gunakan perintah berikut di akar proyek Anda:

vcpkg new --application

Untuk menginstal paket Identitas Azure melalui vcpkg: Untuk menambahkan paket Identitas Azure ke vcpkg Anda, masukkan perintah berikut:

vcpkg add port azure-identity-cpp

Kemudian, tambahkan yang berikut ini di file CMake Anda:

find_package(azure-identity-cpp CONFIG REQUIRED)
target_link_libraries(<your project name> PRIVATE Azure::azure-identity)

Ingatlah untuk mengatur CMAKE_TOOLCHAIN_FILE ke jalur ke vcpkg.cmake salah satu dengan menambahkan yang berikut ini ke file Anda CMakeLists.txt sebelum pernyataan proyek Anda:

set(CMAKE_TOOLCHAIN_FILE "vcpkg-root/scripts/buildsystems/vcpkg.cmake")

Atau dengan menentukannya dalam perintah CMake Anda dengan -DCMAKE_TOOLCHAIN_FILE argumen .

Ada lebih dari satu cara untuk memperoleh dan menginstal pustaka ini. Lihat sampel kami tentang berbagai cara untuk menyiapkan proyek Azure C++ Anda.

Mengautentikasi klien

Saat men-debug dan menjalankan kode secara lokal, biasanya pengembang menggunakan akun mereka sendiri untuk mengautentikasi panggilan ke layanan Azure. Ada beberapa alat pengembang yang dapat digunakan untuk melakukan autentikasi ini di lingkungan pengembangan Anda.

Mengautentikasi melalui Azure CLI

Pengembang dapat menggunakan Azure CLI untuk mengautentikasi. Aplikasi yang menggunakan DefaultAzureCredential atau AzureCliCredential kemudian dapat menggunakan akun ini untuk mengautentikasi panggilan dalam aplikasinya saat berjalan secara lokal.

Untuk mengautentikasi dengan Azure CLI, pengguna dapat menjalankan perintah az login. Untuk pengguna yang berjalan pada sistem dengan browser web default, Azure CLI akan meluncurkan browser untuk mengautentikasi pengguna.

Konsep utama

Credentials

Kredensial adalah kelas yang berisi atau dapat memperoleh data yang diperlukan klien layanan untuk mengautentikasi permintaan. Klien layanan di seluruh Azure SDK menerima kredensial saat dibuat, dan klien layanan menggunakan kredensial tersebut untuk mengautentikasi permintaan ke layanan.

Pustaka Azure Identity berfokus pada autentikasi OAuth dengan ID Microsoft Entra, dan menawarkan berbagai kelas kredensial yang mampu memperoleh token Microsoft Entra untuk mengautentikasi permintaan layanan. Semua kelas kredensial di pustaka ini adalah implementasi TokenCredential kelas abstrak di azure-core, dan salah satunya dapat digunakan oleh untuk membangun klien layanan yang mampu mengautentikasi dengan TokenCredential.

Lihat Kelas Kredensial untuk daftar lengkap jenis kredensial yang tersedia.

DefaultAzureCredential

DefaultAzureCredential menyederhanakan autentikasi saat mengembangkan aplikasi yang disebarkan ke Azure dengan menggabungkan kredensial yang digunakan di lingkungan hosting Azure dengan kredensial yang digunakan dalam pengembangan lokal. Untuk informasi selengkapnya, lihat Gambaran umum DefaultAzureCredential.

Examples

Lihat sampel kode.

Kredensial Token Berantai

ChainedTokenCredential memungkinkan pengguna untuk menyiapkan alur autentikasi kustom yang terdiri dari beberapa kredensial.

Contoh di bawah ini menunjukkan penggunaan ChainedTokenCredential yang akan mencoba mengautentikasi menggunakan EnvironmentCredential, dan mundur untuk mengautentikasi menggunakan ManagedIdentityCredential.

// A configuration demonstrated below would authenticate using EnvironmentCredential if it is
// available, and if it is not available, would fall back to use AzureCliCredential, and then to
// ManagedIdentityCredential.
auto chainedTokenCredential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
    Azure::Identity::ChainedTokenCredential::Sources{
        std::make_shared<Azure::Identity::EnvironmentCredential>(),
        std::make_shared<Azure::Identity::AzureCliCredential>(),
        std::make_shared<Azure::Identity::ManagedIdentityCredential>()});

Azure::Service::Client azureServiceClient("serviceUrl", chainedTokenCredential);

Dukungan Identitas Terkelola

Autentikasi identitas terkelola didukung melalui ManagedIdentityCredential untuk Layanan Azure berikut ini:

Tentukan identitas terkelola yang ditetapkan pengguna dengan ManagedIdentityCredential

Banyak host Azure memungkinkan penetapan identitas terkelola yang ditetapkan pengguna. Contoh berikut menunjukkan konfigurasi ManagedIdentityCredential untuk mengautentikasi identitas terkelola yang ditetapkan pengguna saat disebarkan ke host Azure. Kode sampel menggunakan kredensial untuk mengautentikasi BlobClient dari pustaka klien Azure::Storage::Blobs . Ini juga menunjukkan bagaimana Anda dapat menentukan identitas terkelola yang ditetapkan pengguna baik oleh ID klien, ID sumber daya, atau ID objek.

ID Pelanggan

Untuk menggunakan ID klien, buat ManagedIdentityId dengan ManagedIdentityIdKind::ClientId, atur sebagai IdentityId di ManagedIdentityCredentialOptions, dan teruskan ke ManagedIdentityCredential konstruktor. Contohnya:

// When deployed to an Azure host, ManagedIdentityCredential will authenticate the specified
// user-assigned managed identity.

std::string userAssignedClientId = "<your managed identity client ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId::FromUserAssignedClientId(userAssignedClientId);

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

ID Sumber Daya

Demikian pula, untuk menggunakan ID sumber daya, buat ManagedIdentityId dengan ManagedIdentityIdKind::ResourceId, atur sebagai IdentityId di ManagedIdentityCredentialOptions, dan teruskan ke ManagedIdentityCredential konstruktor. ID sumber daya mengambil formulir /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}. Karena ID sumber daya dapat dibangun oleh konvensi, ID sumber daya dapat lebih nyaman ketika ada sejumlah besar identitas terkelola yang ditetapkan pengguna di lingkungan Anda. Contohnya:

std::string userAssignedResourceId = "/subscriptions/<your managed identity resource ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId::FromUserAssignedResourceId(
    Azure::Core::ResourceIdentifier(userAssignedResourceId));

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

ID Objek

Demikian pula, untuk menggunakan ID objek, buat ManagedIdentityId dengan ManagedIdentityIdKind::ObjectId, atur sebagai IdentityId di ManagedIdentityCredentialOptions, dan teruskan ke ManagedIdentityCredential konstruktor. Contohnya:

std::string userAssignedObjectId = "<your managed identity object ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId::FromUserAssignedObjectId(userAssignedObjectId);

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

Tentukan identitas terkelola yang ditetapkan sistem dengan ManagedIdentityCredential

Anda dapat mengekspresikan niat Anda untuk menggunakan identitas terkelola yang ditetapkan sistem, secara eksplisit, dengan membuat ManagedIdentityId nilai DENGAN dan ID kosong, mengaturnya sebagai ManagedIdentityIdKind::SystemAssigned dalam IdentityId, dan meneruskannya ke ManagedIdentityCredentialOptions konstruktor.ManagedIdentityCredential Contohnya:

ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId::SystemAssigned();

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

Cara alternatif untuk menentukan identitas terkelola yang ditetapkan sistem, secara implisit, adalah dengan memanggil konstruktor default ManagedIdentityCredential . Contohnya:

auto credential = std::make_shared<ManagedIdentityCredential>();
auto blobClient = BlobClient(blobUrl, credential);

Variabel Lingkungan

DefaultAzureCredential dan EnvironmentCredential dapat dikonfigurasi dengan variabel lingkungan. Setiap jenis autentikasi memerlukan nilai untuk variabel tertentu:

Perwakilan layanan dengan rahasia

Nama variabel Nilai
AZURE_TENANT_ID ID penyewa Microsoft Entra aplikasi
AZURE_CLIENT_ID ID aplikasi Microsoft Entra
AZURE_CLIENT_SECRET salah satu rahasia klien aplikasi
AZURE_AUTHORITY_HOST (opsional) URL otoritas autentikasi

Perwakilan layanan dengan sertifikat

nama variabel Nilai
AZURE_CLIENT_ID ID aplikasi Microsoft Entra
AZURE_TENANT_ID ID penyewa Microsoft Entra aplikasi
AZURE_CLIENT_CERTIFICATE_PATH jalur ke file sertifikat yang dikodekan PFX atau PEM termasuk kunci privat
AZURE_AUTHORITY_HOST (opsional) URL otoritas autentikasi

Konfigurasi dicoba dalam urutan di atas. Misalnya, jika nilai untuk rahasia klien dan sertifikat keduanya ada, rahasia klien akan digunakan.

Kelas kredensial

Rantai kredensial

Credential Usage
DefaultAzureCredential Memberikan pengalaman autentikasi yang disederhanakan untuk mulai mengembangkan aplikasi dengan cepat yang dijalankan di Azure.
ChainedTokenCredential Memungkinkan pengguna menentukan alur autentikasi kustom yang menyusun beberapa kredensial.

Mengautentikasi aplikasi yang dihosting Azure

Credential Usage
ManagedIdentityCredential Mengautentikasi identitas terkelola sumber daya Azure.
EnvironmentCredential Mengautentikasi perwakilan layanan atau pengguna melalui informasi kredensial yang ditentukan dalam variabel lingkungan.
WorkloadIdentityCredential Mengautentikasi identitas beban kerja di Kubernetes.

Mengautentikasi perwakilan layanan

Credential Usage
AzurePipelinesCredential Mendukung ID Beban Kerja Microsoft Entra di Azure Pipelines.
ClientAssertionCredential Mengautentikasi perwakilan layanan menggunakan pernyataan klien yang ditandatangani.
ClientSecretCredential Mengautentikasi perwakilan layanan menggunakan rahasia.
ClientCertificateCredential Mengautentikasi perwakilan layanan menggunakan sertifikat.

Mengautentikasi melalui alat pengembangan

Credential Usage
AzureCliCredential Mengautentikasi di lingkungan pengembangan dengan Azure CLI.

Troubleshooting

  1. Pesan log Azure Identity SDK berisi informasi disgnostik, dan dimulai dengan "Identity: ".
  2. Kredensial menimbulkan pengecualian baik ketika gagal mengautentikasi atau tidak dapat menjalankan autentikasi. Ketika kredensial gagal diautentikasi, kredensial AuthenticationException akan dilemparkan. Pengecualian memiliki what() fungsi yang menyediakan informasi lebih lanjut tentang kegagalan.

Contributing

Untuk detail tentang berkontribusi pada repositori ini, lihat panduan berkontribusi.

Proyek ini menyambut kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi Perjanjian Lisensi Kontributor.

Saat Anda mengirimkan permintaan pull, cla-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repositori menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Kode Etik atau hubungi opencode@microsoft.com dengan pertanyaan atau komentar tambahan apa pun.

Banyak orang di seluruh dunia telah membantu membuat proyek ini lebih baik. Anda akan ingin memeriksa:

Melaporkan masalah keamanan dan bug keamanan

Masalah keamanan dan bug harus dilaporkan secara privat, melalui email, ke Microsoft Security Response Center (MSRC) secure@microsoft.com. Anda akan menerima respons dalam waktu 24 jam. Jika karena alasan tertentu Anda tidak melakukannya, silakan tindak lanjuti melalui email untuk memastikan kami menerima pesan asli Anda. Informasi lebih lanjut, termasuk kunci MSRC PGP, dapat ditemukan di Security TechCenter.

Lisensi

Azure SDK untuk C++ dilisensikan di bawah lisensi MIT .

  • Last updated on