Memecahkan masalah autentikasi identitas Azure

Artikel ini membahas teknik investigasi kegagalan, kesalahan umum untuk jenis kredensial di pustaka klien Azure Identity Java, dan langkah-langkah mitigasi untuk mengatasi kesalahan ini. Karena banyak jenis kredensial tersedia di Azure SDK untuk Java, panduan pemecahan masalah ini dibagi menjadi beberapa bagian berdasarkan skenario penggunaan. Bagian berikut tersedia:

Sisa artikel ini mencakup teknik pemecahan masalah umum dan panduan yang berlaku untuk semua jenis kredensial.

Menangani pengecualian Azure Identity

Seperti yang disebutkan dalam penanganan Pengecualian di bagian Azure SDK untuk Javaringkasan Pemecahan Masalah, Azure SDK untuk Java dapat melemparkan serangkaian pengecualian dan kode kesalahan yang komprehensif. Untuk identitas Azure secara khusus, beberapa jenis pengecualian utama penting untuk dipahami.

ClientAuthenticationException

Metode klien layanan apa pun yang membuat permintaan ke layanan dapat menimbulkan pengecualian dari kesalahan autentikasi. Pengecualian ini dapat terjadi karena token diminta dari kredensial saat panggilan pertama ke layanan dilakukan dan pada setiap permintaan berikutnya ke layanan yang memerlukan pembaruan token.

Untuk membedakan kegagalan ini dari kegagalan di klien layanan, kelas Azure Identity menaikkan ClientAuthenticationException dengan detail yang menjelaskan sumber kesalahan dalam pesan pengecualian dan mungkin pesan kesalahan. Tergantung pada aplikasi, kesalahan ini mungkin dapat dipulihkan. Kode berikut menunjukkan contoh menangani ClientAuthenticationException:

// Create a secret client using the DefaultAzureCredential
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://myvault.vault.azure.net/")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

try {
    KeyVaultSecret secret = client.getSecret("secret1");
} catch (ClientAuthenticationException e) {
    //Handle Exception
    e.printStackTrace();
}

CredentialUnavailableException (Pengecualian Kredensial Tidak Tersedia)

CredentialUnavailableException adalah jenis pengecualian khusus yang berasal dari ClientAuthenticationException. Gunakan jenis pengecualian ini untuk menunjukkan bahwa kredensial tidak dapat mengautentikasi di lingkungan saat ini karena kurangnya konfigurasi atau penyiapan yang diperlukan. Pengecualian ini juga memberi sinyal jenis kredensial berantai, seperti DefaultAzureCredential dan ChainedTokenCredential, bahwa kredensial berantai harus terus mencoba jenis kredensial lain nanti dalam rantai.

Masalah izin

Panggilan ke klien layanan yang menghasilkan HttpResponseException dengan StatusCode 401 atau 403 sering menunjukkan bahwa pemanggil tidak memiliki izin yang memadai untuk API yang ditentukan. Periksa dokumentasi layanan untuk menentukan peran mana yang diperlukan untuk permintaan tertentu. Pastikan bahwa pengguna atau perwakilan layanan yang diautentikasi diberikan peran yang sesuai pada sumber daya.

Menemukan informasi yang relevan dalam pesan pengecualian

Pengecualian ClientAuthenticationException dilemparkan ketika kesalahan tak terduga terjadi saat kredensial sedang mengautentikasi. Kesalahan ini dapat mencakup kesalahan yang berasal dari permintaan ke layanan token keamanan (STS) Microsoft Entra dan sering kali berisi informasi yang membantu proses diagnosis. Pertimbangkan pesan ClientAuthenticationException berikut:

ClientSecretCredential authentication failed: A configuration issue is preventing authentication - check the error message from the server for details. You can modify the configuration in the application registration portal. See https://aka.ms/msal-net-invalid-client for details.

Original exception:
AADSTS7000215: Invalid client secret provided. Ensure the secret being sent in the request is the client secret value, not the client secret ID, for a secret added to app 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.
Trace ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Correlation ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Timestamp: 2022-01-01 00:00:00Z

Pesan kesalahan ini berisi informasi berikut:

  • Jenis kredensial gagal: Jenis kredensial yang gagal diautentikasi - dalam hal ini, ClientSecretCredential. Informasi ini berguna saat mendiagnosis masalah dengan jenis kredensial berantai, seperti DefaultAzureCredential atau ChainedTokenCredential.

  • Kode dan pesan kesalahan STS: Kode kesalahan dan pesan yang dikembalikan dari Microsoft Entra STS - dalam hal ini, AADSTS7000215: Invalid client secret provided. Informasi ini memberikan wawasan tentang alasan spesifik permintaan gagal. Misalnya, dalam kasus khusus ini, rahasia klien yang disediakan salah. Untuk informasi selengkapnya tentang kode kesalahan STS, lihat kode kesalahan AADSTS bagian kode kesalahan autentikasi dan otorisasi Microsoft Entra.

  • ID Korelasi dan tanda waktu: ID korelasi dan tanda waktu panggilan yang digunakan untuk mengidentifikasi permintaan di log sisi server. Informasi ini berguna untuk mendukung teknisi saat mendiagnosis kegagalan STS yang tidak terduga.

Mengaktifkan dan mengonfigurasi pengelogan

Azure SDK untuk Java menawarkan cerita pengelogan yang konsisten untuk membantu memecahkan masalah kesalahan aplikasi dan untuk membantu mempercepat resolusinya. Log menangkap alur aplikasi sebelum mencapai status terminal untuk membantu menemukan masalah akar. Untuk panduan tentang pengelogan, lihat Mengonfigurasi pengelogan di Azure SDK untuk Java dan pemecahan masalah melalui tampilan.

Pustaka dasar MSAL, MSAL4J, juga memiliki pencatatan terperinci. Pengelogan ini sangat verbose dan mencakup semua data pribadi, termasuk token. Pencatatan log ini paling berguna saat bekerja dengan dukungan produk. Pada v1.10.0, kredensial yang menawarkan pengelogan ini memiliki metode yang disebut enableUnsafeSupportLogging().

Perhatian

Permintaan dan respons di pustaka Azure Identity berisi informasi sensitif. Lakukan tindakan pencegahan untuk melindungi log saat menyesuaikan output untuk menghindari penyusupan keamanan akun.

Langkah berikutnya

Jika panduan pemecahan masalah dalam artikel ini tidak membantu mengatasi masalah saat Anda menggunakan Azure SDK untuk pustaka klien Java, ajukan masalah di Azure SDK untuk repositori Java GitHub.

  • Last updated on