Panduan migrasi ADAL ke MSAL untuk Android

  • Artikel

Artikel ini menunjukkan perubahan yang perlu Anda lakukan untuk memindahkan aplikasi yang menggunakan Microsoft Azure Active Directory Authentication Library (ADAL) untuk menggunakan Microsoft Authentication Library (MSAL).

Sorotan perbedaan

ADAL berfungsi dengan titik akhir Azure AD v1.0. Microsoft Authentication Library (MSAL) berfungsi dengan platform identitas Microsoft, sebelumnya dikenal sebagai titik akhir Azure AD v2.0. Platform identitas Microsoft berbeda dari Microsoft Azure AD v1.0 karena:

Dukungan:

  • Identitas Organisasi (ID Microsoft Entra)

  • Identitas non-organisasi seperti Outlook.com, Xbox Live, dan sebagainya

  • (Hanya Azure AD B2C) Login gabungan dengan Google, Facebook, Twitter, dan Amazon

  • Merupakan standar yang kompatibel dengan:

    • OAuth v2.0
    • OpenID Connect (OIDC)

API publik MSAL memperkenalkan perubahan penting, termasuk:

  • Model baru untuk mengakses token:
    • ADAL menyediakan akses ke token melalui AuthenticationContext, yang mewakili server. MSAL menyediakan akses ke token melalui PublicClientApplication, yang mewakili server. Pengembang klien tidak perlu membuat instans baru untuk instans PublicClientApplication baru untuk setiap Otoritas yang perlu berinteraksi dengannya. Hanya membutuhkan konfigurasi PublicClientApplication.
    • Dukungan untuk meminta token akses menggunakan cakupan selain pengidentifikasi sumber daya.
    • Dukungan untuk persetujuan inkremental. Pengembang dapat meminta cakupan karena pengguna mengakses semakin banyak fungsionalitas di dalam aplikasi, termasuk yang tidak disertakan selama pendaftaran aplikasi.
    • Otoritas tidak lagi divalidasi pada run-time. Sebaliknya, pengembang menyatakan daftar 'otoritas yang dikenal' selama pengembangan.
  • Perubahan API token:
    • Di ADAL, AcquireToken() pertama-tama membuat permintaan senyap. Jika itu gagal, permintaan interaktif dibuat. Perilaku ini mengakibatkan beberapa pengembang hanya mengandalkan AcquireToken, yang mengakibatkan pengguna secara tak terduga kadang-kadang diminta untuk menunjukkan informasi masuk. MSAL mengharuskan pengembang menyatakan niat tentang kapan pengguna menerima permintaan UI.
      • AcquireTokenSilent selalu menghasilkan permintaan senyap yang berhasil atau gagal.
      • AcquireToken selalu menghasilkan permintaan yang meminta pengguna melalui UI.
  • MSAL mendukung masuk dari browser default atau tampilan web yang disematkan:
    • Secara default, browser default pada perangkat digunakan. Ini memungkinkan MSAL untuk menggunakan status autentikasi (cookie) yang mungkin sudah ada untuk satu atau beberapa akun yang masuk. Jika ada status autentikasi yang ada, autentikasi selama otorisasi melalui hasil MSAL dalam status autentikasi (cookie) yang dibuat untuk kepentingan aplikasi web lain yang akan digunakan di browser yang sama.
  • Model pengecualian baru:
    • Pengecualian lebih jelas mendefinisikan jenis kesalahan yang terjadi dan apa yang perlu dilakukan pengembang untuk menyelesaikannya.
  • MSAL mendukung objek parameter untuk panggilan AcquireToken dan AcquireTokenSilent.
  • MSAL mendukung konfigurasi deklaratif untuk:
    • ID Klien, URI Pengalihan.
    • Browser Tersemat vs Default
    • Otoritas
    • Pengaturan HTTP seperti waktu habis baca dan sambungan

Registrasi dan migrasi aplikasi Anda ke MSAL

Anda tidak perlu mengubah pendaftaran aplikasi yang ada untuk menggunakan MSAL. Jika Anda ingin mengambil keuntungan dari persetujuan inkremental/progresif, Anda mungkin perlu meninjau pendaftaran untuk mengidentifikasi cakupan tertentu yang ingin Anda minta secara bertahap. Informasi lebih lanjut tentang cakupan dan persetujuan inkremental berikut.

Di pendaftaran aplikasi di portal, Anda akan melihat tab API permissions. Ini menyediakan daftar API dan izin (cakupan) yang saat ini dikonfigurasi oleh aplikasi Anda untuk meminta akses. Ini juga menampilkan daftar nama cakupan yang terkait dengan setiap izin API.

Dengan ADAL dan titik akhir Azure AD v1.0, persetujuan pengguna untuk sumber daya yang mereka miliki diberikan pada penggunaan pertama. Dengan MSAL dan platform identitas Microsoft, persetujuan dapat diminta secara bertahap. Persetujuan inkremental berguna untuk izin yang mungkin dianggap oleh pengguna sebagai hak istimewa tinggi, atau mungkin mempertanyakan jika tidak diberi penjelasan yang jelas tentang mengapa izin diperlukan. Di ADAL, izin tersebut mungkin mengakibatkan pengguna meninggalkan log masuk ke aplikasi Anda.

Tip

Gunakan persetujuan inkremental untuk memberi konteks tambahan kepada pengguna tentang kenapa aplikasi Anda memerlukan izin.

Administrator organisasi dapat menyetujui izin yang diperlukan aplikasi Anda atas nama semua anggota organisasinya. Beberapa organisasi hanya mengizinkan admin untuk menyetujui aplikasi. Persetujuan admin mengharuskan Anda menyertakan semua izin API dan cakupan yang digunakan oleh aplikasi Anda dalam pendaftaran aplikasi Anda.

Tip

Meskipun Anda dapat meminta ruang lingkup menggunakan MSAL untuk sesuatu yang tidak termasuk dalam pendaftaran aplikasi Anda, kami sarankan Anda memperbarui pendaftaran aplikasi Untuk menyertakan semua sumber daya dan cakupan yang pernah diberikan pengguna.

Bermigrasi dari ID sumber daya ke cakupan

Autentikasi dan otorisasi permintaan untuk semua izin pada penggunaan pertama

Jika saat ini Anda menggunakan ADAL dan tidak perlu menggunakan persetujuan tambahan, cara paling sederhana untuk mulai menggunakan MSAL adalah dengan membuat permintaan acquireToken menggunakan objek AcquireTokenParameter baru dan mengatur nilai ID sumber daya.

Perhatian

Tidak dimungkinkan untuk mengatur cakupan dan id sumber daya. Mencoba untuk mengatur keduanya akan menghasilkan IllegalArgumentException.

Ini akan menghasilkan perilaku v1 yang sama dengan yang Anda gunakan. Semua izin yang diminta dalam pendaftaran aplikasi Anda diminta dari pengguna selama interaksi pertamanya.

Autentikasi dan minta izin hanya jika diperlukan

Untuk memanfaatkan persetujuan tambahan, buat daftar izin (cakupan) yang digunakan aplikasi Anda dari pendaftaran aplikasi Anda, dan atur ke dalam dua daftar berdasarkan:

  • Cakupan mana yang ingin Anda minta selama interaksi pertama pengguna dengan aplikasi Anda selama masuk.
  • Izin yang terkait dengan fitur penting aplikasi yang juga perlu Anda jelaskan kepada pengguna.

Setelah mengatur cakupan, atur setiap daftar dengan sumber daya (API) mana yang ingin Anda minta tokennya. Serta cakupan lain yang Anda ingin pengguna otorisasikan pada saat yang sama.

Objek parameter yang digunakan untuk membuat permintaan Anda ke dukungan MSAL:

  • Scope: Daftar cakupan yang ingin Anda minta otorisasi dan terima token aksesnya.
  • ExtraScopesToConsent: Daftar cakupan tambahan yang ingin Anda minta otorisasinya saat Anda meminta token akses untuk sumber daya lain. Daftar cakupan ini memungkinkan Anda untuk meminimalkan berapa kali Anda perlu meminta otorisasi pengguna. Yang berarti, lebih sedikit otorisasi pengguna atau prompt persetujuan.

Bermigrasi dari AuthenticationContext ke PublicClientApplications

Membangun PublicClientApplication

Ketika Anda menggunakan MSAL, Anda membuat instans PublicClientApplication. Objek ini memodelkan identitas aplikasi Anda dan digunakan untuk membuat permintaan ke satu atau beberapa otoritas. Dengan objek ini Anda akan mengonfigurasi identitas klien Anda, URI pengalihan, otoritas default, apakah akan menggunakan browser perangkat vs. tampilan web tersemat, tingkat log, dan banyak lagi.

Anda dapat secara deklaratif mengonfigurasi objek ini dengan JSON, yang Anda sediakan sebagai file atau simpan sebagai sumber daya dalam APK Anda.

Meskipun objek ini bukan konstanta, secara internal menggunakan Executors bersama untuk permintaan interaktif dan senyap.

Bisnis ke Bisnis

Di ADAL, setiap organisasi yang Anda minta akses tokennya memerlukan instans AuthenticationContext terpisah. Dalam MSAL, ini bukan lagi persyaratan. Anda dapat menentukan otoritas tempat Anda ingin meminta token sebagai bagian dari permintaan senyap atau interaktif Anda.

Bermigrasi dari validasi otoritas ke otoritas yang diketahui

MSAL tidak memiliki bendera untuk mengaktifkan atau menonaktifkan validasi otoritas. Validasi otoritas adalah fitur dalam ADAL, dan pada rilis awal MSAL, yang mencegah kode Anda meminta token dari otoritas yang berpotensi berbahaya. MSAL sekarang mengambil daftar otoritas yang dikenal oleh Microsoft dan menggabungkan daftar itu dengan otoritas yang telah ditentukan dalam konfigurasi Anda.

Tip

Jika Anda adalah pengguna Azure Business to Consumer (B2C), ini berarti Anda tidak lagi harus menonaktifkan validasi otoritas. Sebagai gantinya, sertakan setiap kebijakan Azure AD B2C yang didukung sebagai otoritas dalam konfigurasi MSAL Anda.

Jika Anda mencoba menggunakan otoritas yang tidak diketahui Microsoft, dan tidak disertakan dalam konfigurasi, Anda akan mendapat UnknownAuthorityException.

Pencatatan

Anda sekarang dapat secara deklaratif mengonfigurasi pembuatan log sebagai bagian dari konfigurasi Anda, seperti ini:

"logging": {
  "pii_enabled": false,
  "log_level": "WARNING",
  "logcat_enabled": true
}

Bermigrasi dari UserInfo ke Akun

Di ADAL, AuthenticationResult menyediakan objek UserInfo yang digunakan untuk mengambil informasi tentang akun yang diautentikasi. Istilah "pengguna", yang berarti agen manusia atau perangkat lunak, diterapkan dengan cara yang menjadikannya sulit untuk mengomunikasikan bahwa beberapa aplikasi mendukung satu pengguna (baik agen manusia atau perangkat lunak) yang memiliki beberapa akun.

Bayangkan rekening bank. Anda mungkin memiliki lebih dari satu rekening di lebih dari satu lembaga keuangan. Ketika Anda membuka akun, Anda (pengguna) diberi informasi masuk, seperti PIN & Kartu ATM, yang digunakan untuk mengakses saldo Anda, pembayaran tagihan, dan sebagainya, untuk setiap akun. Informasi masuk tersebut hanya dapat digunakan di lembaga keuangan yang mengeluarkannya.

Dengan analogi ini, seperti akun di lembaga keuangan, akun di platform identitas Microsoft diakses menggunakan informasi masuk. Kredensial tersebut terdaftar di, atau dikeluarkan, oleh Microsoft. Atau oleh Microsoft atas nama organisasi.

Jika platform identitas Microsoft berbeda dari lembaga keuangan, dalam analogi ini, adalah bahwa platform identitas Microsoft menyediakan kerangka kerja yang memungkinkan pengguna untuk menggunakan satu akun, dan kredensial terkait, untuk mengakses sumber daya yang termasuk dalam beberapa individu dan organisasi. Ini seperti dapat menggunakan kartu yang dikeluarkan oleh satu bank, di lembaga keuangan lain. Ini berfungsi karena semua organisasi yang dimaksud menggunakan platform identitas Microsoft, yang memungkinkan satu akun digunakan di beberapa organisasi. Berikut contohnya:

Sam bekerja untuk Contoso.com tetapi mengelola mesin virtual Azure yang termasuk dalam Fabrikam.com. Agar Sam dapat mengelola mesin virtual Fabrikam, dia perlu diberi wewenang untuk mengaksesnya. Akses ini dapat diberikan dengan menambahkan akun Sam ke Fabrikam.com, dan memberi peran pada akunnya yang memungkinkannya untuk bekerja dengan mesin virtual. Ini akan dilakukan dengan portal Microsoft Azure.

Menambahkan akun Contoso.com Sam sebagai anggota Fabrikam.com akan mengakibatkan pembuatan rekaman baru di ID Microsoft Entra Fabrikam.com untuk Sam. Catatan Sam di ID Microsoft Entra dikenal sebagai objek pengguna. Dalam hal ini, objek pengguna itu akan menunjuk kembali ke objek pengguna Sam di Contoso.com. Objek pengguna Sam di Fabrikam adalah representasi lokal Sam, dan akan digunakan untuk menyimpan informasi tentang akun yang terkait dengan Sam dalam konteks Fabrikam.com. Pada Contoso.com, gelar Sam adalah Senior DevOps Consultant. Di Fabrikam, gelar Sam adalah Contractor-Virtual Machines. Di Contoso.com, Sam tidak bertanggung jawab, atau berwenang, untuk mengelola mesin virtual. Dalam Fabrikam.com, itu satu-satunya fungsi pekerjaannya. Namun Sam masih hanya memiliki satu set informasi masuk untuk diingat, yang merupakan kredensial yang dikeluarkan oleh Contoso.com.

Setelah panggilan acquireToken berhasil dilakukan, Anda akan melihat referensi ke objek IAccount yang dapat digunakan dalam permintaan acquireTokenSilent nanti.

IMultiTenantAccount

Jika Anda memiliki aplikasi yang mengakses klaim tentang akun dari masing-masing penyewa tempat akun diwakili, Anda dapat mengirim objek IAccount ke IMultiTenantAccount. Antarmuka ini menyediakan peta ITenantProfiles, yang di kunci oleh ID penyewa, yang memungkinkan Anda mengakses klaim yang termasuk dalam akun di setiap penyewa tempat Anda minta token, relatif terhadap akun saat ini.

Klaim di akar dari IAccount dan IMultiTenantAccount selalu berisi klaim dari penyewa awal/home. Jika Anda belum mengajukan permintaan token di dalam penyewa home, koleksi ini akan kosong.

Perubahan lainnya

Menggunakan AuthenticationCallback baru

// Existing ADAL Interface
public interface AuthenticationCallback<T> {

    /**
     * This will have the token info.
     *
     * @param result returns <T>
     */
    void onSuccess(T result);

    /**
     * Sends error information. This can be user related error or server error.
     * Cancellation error is AuthenticationCancelError.
     *
     * @param exc return {@link Exception}
     */
    void onError(Exception exc);
}

// New Interface for Interactive AcquireToken
public interface AuthenticationCallback {

    /**
     * Authentication finishes successfully.
     *
     * @param authenticationResult {@link IAuthenticationResult} that contains the success response.
     */
    void onSuccess(final IAuthenticationResult authenticationResult);

    /**
     * Error occurs during the authentication.
     *
     * @param exception The {@link MsalException} contains the error code, error message and cause if applicable. The exception
     *                  returned in the callback could be {@link MsalClientException}, {@link MsalServiceException}
     */
    void onError(final MsalException exception);

    /**
     * Will be called if user cancels the flow.
     */
    void onCancel();
}

// New Interface for Silent AcquireToken
public interface SilentAuthenticationCallback {

    /**
     * Authentication finishes successfully.
     *
     * @param authenticationResult {@link IAuthenticationResult} that contains the success response.
     */
    void onSuccess(final IAuthenticationResult authenticationResult);

    /**
     * Error occurs during the authentication.
     *
     * @param exception The {@link MsalException} contains the error code, error message and cause if applicable. The exception
     *                  returned in the callback could be {@link MsalClientException}, {@link MsalServiceException} or
     *                  {@link MsalUiRequiredException}.
     */
    void onError(final MsalException exception);
}

Bermigrasi ke pengecualian baru

Dalam ADAL, ada satu jenis pengecualian, AuthenticationException, yang mencakup metode untuk mengambil nilai enum ADALError. Di MSAL, ada hierarki pengecualian, dan masing-masing memiliki serangkaian kode kesalahan spesifik terkait sendiri.

Pengecualian Deskripsi
MsalArgumentException Disingkirkan jika satu atau beberapa argumen input tidak valid.
MsalClientException Disingkirkan jika kesalahan adalah sisi klien.
MsalDeclinedScopeException Disingkirkan jika satu atau beberapa cakupan yang diminta ditolak oleh server.
MsalException Pengecualian diperiksa default yang disingkirkan oleh MSAL.
MsalIntuneAppProtectionPolicyRequiredException Disingkirkan jika sumber daya mengaktifkan kebijakan perlindungan MAMCA.
MsalServiceException Disingkirkan jika kesalahan adalah sisi server.
MsalUiRequiredException Disingkirkan jika token tidak dapat disegarkan secara senyap.
MsalUserCancelException Disingkirkan jika pengguna membatalkan alur autentikasi.

Terjemahan ADALError ke MsalException

Jika Anda menangkap kesalahan ini di ADAL... ...tangkap pengecualian MSAL ini:
Tidak ada ADALError yang setara MsalArgumentException
  • ADALError.ANDROIDKEYSTORE_FAILED
  • ADALError.AUTH_FAILED_USER_MISMATCH
  • ADALError.DECRYPTION_FAILED
  • ADALError.DEVELOPER_AUTHORITY_CAN_NOT_BE_VALIDED
  • ADALError.DEVELOPER_AUTHORITY_IS_NOT_VALID_INSTANCE
  • ADALError.DEVELOPER_AUTHORITY_IS_NOT_VALID_URL
  • ADALError.DEVICE_CONNECTION_IS_NOT_AVAILABLE
  • ADALError.DEVICE_NO_SUCH_ALGORITHM
  • ADALError.ENCODING_IS_NOT_SUPPORTED
  • ADALError.ENCRYPTION_ERROR
  • ADALError.IO_EXCEPTION
  • ADALError.JSON_PARSE_ERROR
  • ADALError.NO_NETWORK_CONNECTION_POWER_OPTIMIZATION
  • ADALError.SOCKET_TIMEOUT_EXCEPTION
 MsalClientException
Tidak ada ADALError yang setara MsalDeclinedScopeException
  • ADALError.APP_PACKAGE_NAME_NOT_FOUND
  • ADALError.BROKER_APP_VERIFICATION_FAILED
  • ADALError.PACKAGE_NAME_NOT_FOUND
 MsalException
Tidak ada ADALError yang setara MsalIntuneAppProtectionPolicyRequiredException
  • ADALError.SERVER_ERROR
  • ADALError.SERVER_INVALID_REQUEST
 MsalServiceException
  • ADALError.AUTH_REFRESH_FAILED_PROMPT_NOT_ALLOWED
 MsalUiRequiredException
Tidak ada ADALError yang setara MsalUserCancelException

Pencatatan Log ADAL ke Pencatatan Log MSAL

// Legacy Interface
    StringBuilder logs = new StringBuilder();
    Logger.getInstance().setExternalLogger(new ILogger() {
            @Override
            public void Log(String tag, String message, String additionalMessage, LogLevel logLevel, ADALError errorCode) {
                logs.append(message).append('\n');
            }
        });

// New interface
  StringBuilder logs = new StringBuilder();
  Logger.getInstance().setExternalLogger(new ILoggerCallback() {
      @Override
      public void log(String tag, Logger.LogLevel logLevel, String message, boolean containsPII) {
          logs.append(message).append('\n');
      }
  });

// New Log Levels:
public enum LogLevel
{
    /**
     * Error level logging.
     */
    ERROR,
    /**
     * Warning level logging.
     */
    WARNING,
    /**
     * Info level logging.
     */
    INFO,
    /**
     * Verbose level logging.
     */
    VERBOSE
}