Panduan migrasi ADAL ke MSAL untuk Java

Artikel ini menyoroti perubahan yang perlu Anda lakukan untuk memigrasikan aplikasi yang menggunakan Azure Active Directory Authentication Library (ADAL) ke Pustaka Autentikasi Microsoft (MSAL).

Baik Perpustakaan Autentikasi Microsoft untuk Java (MSAL4J) maupun Azure AD Authentication Library for Java (ADAL4J) digunakan untuk mengautentikasi entitas Microsoft Entra dan meminta token dari Microsoft Entra ID. Hingga saat ini, sebagian besar pengembang telah bekerja dengan Azure AD untuk pengembang (v1.0) untuk mengautentikasi dengan berbagai identitas, seperti akun kantor dan sekolah, dengan meminta token menggunakan Azure AD Authentication Library (ADAL).

MSAL menawarkan manfaat berikut:

• Karena menggunakan platform identitas Microsoft yang lebih baru, Anda dapat mengautentikasi sekumpulan identitas Microsoft yang lebih luas seperti identitas Microsoft Entra, akun Microsoft, akun sosial dan lokal melalui Azure AD Business to Consumer (Azure AD B2C), dan akun pelanggan sosial atau lokal melalui Microsoft Entra External ID.
• Pengguna Anda akan mendapatkan pengalaman single sign-on (SSO) terbaik.
• Aplikasi Anda dapat menerapkan persetujuan inkremental, serta mendukung fitur baru seperti Akses Bersyarat.

MSAL untuk Java adalah pustaka autentikasi yang kami sarankan Anda gunakan dengan platform identitas Microsoft. Tidak ada fitur baru yang akan diterapkan pada ADAL4J. Semua upaya ke depan difokuskan untuk meningkatkan MSAL.

Anda dapat mempelajari lebih lanjut tentang MSAL dan memulai dengan gambaran umum tentang Pustaka Autentikasi Microsoft.

Cakupan, bukan sumber daya

ADAL4J memperoleh token untuk sumber daya sedangkan MSAL untuk Java memperoleh token untuk cakupan. Banyak MSAL untuk kelas Java memerlukan parameter cakupan. Parameter ini adalah daftar string yang mendeklarasikan izin dan sumber daya yang diinginkan yang diminta. Lihat cakupan Microsoft Graph untuk melihat contoh cakupan.

Anda dapat menambahkan akhiran cakupan /.default pada sumber daya untuk membantu memigrasikan aplikasi Anda dari ADAL ke MSAL. Misalnya, untuk nilai https://graph.microsoft.comsumber daya , nilai cakupan yang setara adalah https://graph.microsoft.com/.default. Jika sumber daya tidak dalam formulir URL, tetapi ID sumber daya formulir XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, Anda masih dapat menggunakan nilai cakupan sebagai XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Untuk detail lebih lanjut tentang berbagai jenis cakupan akses, rujuk artikel Izin dan persetujuan pada platform identitas Microsoft dan Cakupan untuk API Web yang menerima token v1.0.

Kelas inti

Di ADAL4J, AuthenticationContext kelas mewakili koneksi Anda ke Layanan Token Keamanan (STS), atau server otorisasi, melalui Otoritas. Namun, MSAL untuk Java dirancang di sekitar aplikasi klien. Ini menyediakan dua kelas terpisah: PublicClientApplication dan ConfidentialClientApplication untuk mewakili aplikasi klien. Yang terakhir, ConfidentialClientApplication, mewakili aplikasi yang dirancang untuk mempertahankan rahasia dengan aman seperti pengidentifikasi aplikasi untuk aplikasi daemon.

Tabel berikut menunjukkan bagaimana fungsi ADAL4J memetakan ke MSAL baru untuk fungsi Java:

Metode ADAL4J	Metode MSAL4J
acquireToken(String resource, ClientCredential credential, AuthenticationCallback callback)	ClientCredentialParameters
acquireToken(Sumber daya string, pernyataan ClientAssertion, callback AuthenticationCallback)	ClientCredentialParameters
acquireToken(String resource, AsymmetricKeyCredential credential, AuthenticationCallback callback)	ClientCredentialParameters
acquireToken(String resource, String clientId, String username, String password, AuthenticationCallback callback)	UserNamePasswordParameters
acquireToken(String resource, String clientId, String username, String password=null, AuthenticationCallback callback)	IntegratedWindowsAuthenticationParameters
acquireToken(String resource, UserAssertion userAssertion, ClientCredential credential, AuthenticationCallback callback)	OnBehalfOfParameters
acquireTokenByAuthorizationCode()	AuthorizationCodeParameters
acquireDeviceCode() dan acquireTokenByDeviceCode()	DeviceCodeFlowParameters
acquireTokenByRefreshToken()	SilentParameters

IAccount bukan IUser

ADAL4J menangani pengguna. Meskipun pengguna mewakili satu agen manusia atau perangkat lunak, pengguna dapat memiliki satu atau beberapa akun dalam sistem identitas Microsoft. Misalnya, pengguna mungkin memiliki beberapa akun pribadi Microsoft Entra ID, Azure AD B2C, atau Microsoft.

MSAL untuk Java mendefinisikan konsep Akun melalui IAccount antarmuka. Ini merupakan perubahan yang menyebabkan ketidakcocokan dengan ADAL4J. Ini menangkap fakta bahwa pengguna yang sama dapat memiliki beberapa akun, dan mungkin bahkan di direktori Microsoft Entra yang berbeda. MSAL untuk Java memberikan informasi yang lebih baik dalam skenario pengguna tamu karena informasi akun asal disediakan.

Persistensi cache

ADAL4J tidak memiliki dukungan untuk cache token. MSAL untuk Java menambahkan cache token untuk menyederhanakan pengelolaan masa pakai token dengan secara otomatis menyegarkan token yang kedaluwarsa jika memungkinkan dan mencegah permintaan yang tidak perlu bagi pengguna untuk memberikan kredensial jika memungkinkan.

Otoritas Umum

Di v1.0, jika Anda menggunakan https://login.microsoftonline.com/common otoritas, pengguna dapat masuk dengan akun Microsoft Entra apa pun (untuk organisasi apa pun).

Jika Anda menggunakan otoritas https://login.microsoftonline.com/common di v2.0, pengguna dapat masuk menggunakan organisasi Microsoft Entra mana pun, atau bahkan akun pribadi Microsoft (MSA). Di MSAL untuk Java, jika Anda ingin membatasi login ke akun Microsoft Entra apa pun, gunakan https://login.microsoftonline.com/organizations otoritas (yang merupakan perilaku yang sama seperti dengan ADAL4J). Untuk menentukan otoritas, atur parameter authority dalam metode PublicClientApplication.Builder saat Anda membuat instance kelas PublicClientApplication.

Token v1.0 dan v2.0

Titik akhir v1.0 (digunakan oleh ADAL) hanya memancarkan token v1.0.

Titik akhir v2.0 (digunakan oleh MSAL) dapat memancarkan token v1.0 dan v2.0. Properti manifes aplikasi API web memungkinkan pengembang untuk memilih versi token mana yang diterima. Lihat accessTokenAcceptedVersion dalam dokumentasi referensi manifes aplikasi .

Untuk informasi selengkapnya tentang token v1.0 dan v2.0, lihat token akses Microsoft Entra.

Migrasi ADAL ke MSAL

Di ADAL4J, token refresh diekspos--yang memungkinkan pengembang untuk menyimpannya. Mereka kemudian akan menggunakan AcquireTokenByRefreshToken() untuk mengaktifkan solusi seperti menerapkan layanan jangka panjang yang me-refresh dasbor atas nama pengguna ketika pengguna tidak lagi terhubung.

MSAL untuk Java tidak mengekspos token refresh karena alasan keamanan. Sebagai gantinya, MSAL menangani token refreshing untuk Anda.

MSAL untuk Java memiliki API yang memungkinkan Anda memigrasikan token refresh yang diperoleh dengan ADAL4J ke dalam ClientApplication: RefreshTokenParameters. Dengan metode ini, Anda dapat menyediakan token refresh yang digunakan sebelumnya bersama dengan cakupan (sumber daya) apa pun yang Anda inginkan. Token refresh akan ditukar dengan yang baru dan di-cache untuk digunakan oleh aplikasi Anda.

Cuplikan kode berikut menunjukkan cuplikan kode migrasi sederhana dalam aplikasi klien rahasia:

String rt = GetCachedRefreshTokenForSignedInUser(); // Get refresh token from where you have them stored
Set<String> scopes = Collections.singleton("SCOPE_FOR_REFRESH_TOKEN");

RefreshTokenParameters parameters = RefreshTokenParameters.builder(scopes, rt).build();

PublicClientApplication app = PublicClientApplication.builder(CLIENT_ID) // ClientId for your application
                .authority(AUTHORITY)  //plug in your authority
                .build();

IAuthenticationResult result = app.acquireToken(parameters);

IAuthenticationResult mengembalikan token akses dan token ID, sementara token refresh baru Anda disimpan di cache. Aplikasi ini juga sekarang akan berisi IAccount:

Set<IAccount> accounts =  app.getAccounts().join();

Untuk menggunakan token yang sekarang ada di cache, panggil:

SilentParameters parameters = SilentParameters.builder(scope, accounts.iterator().next()).build();
IAuthenticationResult result = app.acquireToken(parameters);