Bagikan melalui

Panduan migrasi ADAL ke MSAL untuk Android

  • Artikel

Artikel ini menyoroti perubahan yang perlu Anda lakukan untuk memigrasikan aplikasi yang menggunakan 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 Azure AD v1.0 karena:

Mendukung:

  • Identitas Organisasi (ID Microsoft Entra)

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

  • (Khusus Azure AD B2C) Login federasi dengan Google, Facebook, X, dan Amazon

  • Apakah standar 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 klien. Pengembang klien tidak perlu membuat instans baru PublicClientApplication untuk setiap Otoritas yang perlu mereka berinteraksi. Hanya satu PublicClientApplication konfigurasi yang diperlukan.
    • Dukungan untuk meminta token akses menggunakan cakupan selain pengidentifikasi sumber daya.
    • Dukungan untuk persetujuan inkremental. Pengembang dapat meminta cakupan saat pengguna mengakses semakin banyak fungsionalitas di aplikasi, termasuk yang tidak disertakan selama pendaftaran aplikasi.
    • Otoritas tidak lagi divalidasi pada run-time. Sebagai gantinya, pengembang mendeklarasikan daftar 'otoritas yang diketahui' selama pengembangan.
  • Perubahan API token:
    • Di ADAL, AcquireToken() pertama-tama membuat permintaan senyap. Gagal itu, itu membuat permintaan interaktif. Perilaku ini mengakibatkan beberapa pengembang hanya AcquireTokenmengandalkan , yang mengakibatkan pengguna secara tak terduga dimintai kredensial kadang-kadang. MSAL mengharuskan pengembang disengaja ketika 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 tidak ada status autentikasi yang ada, mengautentikasi selama otorisasi melalui MSAL mengakibatkan status autentikasi (cookie) dibuat untuk kepentingan aplikasi web lain yang akan digunakan di browser yang sama.
  • Model pengecualian baru:
    • Pengecualian lebih jelas menentukan jenis kesalahan yang terjadi dan apa yang perlu dilakukan pengembang untuk mengatasinya.
  • MSAL mendukung objek parameter untuk AcquireToken panggilan dan AcquireTokenSilent .
  • MSAL mendukung konfigurasi deklaratif untuk:
    • ID Klien, URI Pengalihan.
    • Browser Tersemat vs Default
    • Pihak berwenang
    • Pengaturan HTTP seperti waktu baca dan koneksi habis

Pendaftaran dan migrasi aplikasi Anda ke MSAL

Anda tidak perlu mengubah pendaftaran aplikasi yang ada untuk menggunakan MSAL. Jika Anda ingin memanfaatkan persetujuan bertahap/progresif, Anda mungkin perlu meninjau pendaftaran untuk mengidentifikasi cakupan spesifik yang ingin Anda minta secara bertahap. Informasi selengkapnya tentang cakupan dan persetujuan inkremental berikut.

Di pendaftaran aplikasi di portal, Anda akan melihat tab izin API. Ini menyediakan daftar API dan izin (cakupan) yang saat ini dikonfigurasi aplikasi Anda untuk meminta akses. Ini juga menunjukkan 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 dipertimbangkan pengguna dengan hak istimewa tinggi, atau mungkin mempertanyakan jika tidak diberikan penjelasan yang jelas tentang mengapa izin diperlukan. Di ADAL, izin tersebut mungkin mengakibatkan pengguna meninggalkan masuk ke aplikasi Anda.

Ujung

Gunakan persetujuan inkremental untuk memberikan konteks tambahan kepada pengguna Anda tentang mengapa aplikasi Anda memerlukan izin.

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

Ujung

Meskipun Anda dapat meminta cakupan menggunakan MSAL untuk sesuatu yang tidak disertakan dalam pendaftaran aplikasi, kami sarankan Anda memperbarui pendaftaran aplikasi untuk menyertakan semua sumber daya dan cakupan yang dapat diberikan izin kepada pengguna.

Migrasi dari ID sumber daya ke cakupan

Mengautentikasi dan meminta otorisasi untuk semua izin saat penggunaan pertama

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

Hati

Tidak dimungkinkan untuk mengatur cakupan dan id sumber daya. Mencoba 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 pertama mereka.

Mengautentikasi dan meminta izin hanya jika diperlukan

Untuk memanfaatkan persetujuan inkremental, 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 Anda mengatur cakupan, atur setiap daftar dengan sumber daya (API) mana yang ingin Anda minta tokennya. Serta cakupan lain yang Anda inginkan untuk diotorisasi pengguna secara bersamaan.

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

  • Scope: Daftar cakupan yang ingin Anda minta otorisasinya dan menerima token akses.
  • ExtraScopesToConsent: Daftar cakupan tambahan yang ingin Anda minta otorisasi 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 permintaan persetujuan.

Migrasi dari AuthenticationContext ke PublicClientApplications

Membangun PublicClientApplication

Saat 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, mengalihkan URI, otoritas default, apakah akan menggunakan browser perangkat vs. tampilan web yang disematkan, 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 singleton, secara internal objek ini menggunakan berbagi Executors untuk permintaan interaktif dan senyap.

Bisnis ke Bisnis

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

Migrasi dari validasi otoritas ke otoritas yang diketahui

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

Ujung

Jika Anda adalah pengguna Azure Business to Consumer (B2C), ini berarti Anda tidak perlu lagi 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 oleh Microsoft, dan tidak disertakan dalam konfigurasi Anda, Anda akan mendapatkan UnknownAuthorityException.

Penebangan

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

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

Migrasi dari UserInfo ke Akun

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

Pertimbangkan rekening bank. Anda mungkin memiliki lebih dari satu akun di lebih dari satu lembaga keuangan. Saat Anda membuka akun, Anda (pengguna) mengeluarkan kredensial, seperti Kartu ATM & PIN, yang digunakan untuk mengakses saldo, pembayaran tagihan, dan sebagainya, untuk setiap akun. Kredensial tersebut hanya dapat digunakan di lembaga keuangan yang mengeluarkannya.

Dengan analogi, seperti akun di lembaga keuangan, akun di platform identitas Microsoft diakses menggunakan kredensial. Kredensial tersebut didaftarkan, 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 milik 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 adalah contohnya:

Sam bekerja untuk Contoso.com tetapi mengelola komputer virtual Azure milik Fabrikam.com. Bagi Sam untuk mengelola komputer virtual Fabrikam, dia harus berwenang untuk mengaksesnya. Akses ini dapat diberikan dengan menambahkan akun Sam ke Fabrikam.com, dan memberi akunnya peran yang memungkinkannya untuk bekerja dengan komputer virtual. Ini akan dilakukan dengan portal 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 tersebut akan menunjuk kembali ke objek pengguna Sam di Contoso.com. Objek pengguna Fabrikam Sam adalah representasi lokal Sam, dan akan digunakan untuk menyimpan informasi tentang akun yang terkait dengan Sam dalam konteks Fabrikam.com. Dalam Contoso.com, judul Sam adalah Konsultan DevOps Senior. Di Fabrikam, judul Sam adalah Contractor-Virtual Machines. Dalam Contoso.com, Sam tidak bertanggung jawab, atau berwenang, untuk mengelola komputer virtual. Dalam Fabrikam.com, itu satu-satunya fungsi pekerjaannya. Namun Sam masih hanya memiliki satu set kredensial untuk dilacak, yang merupakan kredensial yang dikeluarkan oleh Contoso.com.

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

IMultiTenantAccount

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

Klaim di akar IAccount dan IMultiTenantAccount selalu berisi klaim dari penyewa rumah. Jika Anda belum membuat permintaan untuk token dalam penyewa rumah, 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

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

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

Terjemahan ADALError ke MsalException

Jika Anda menangkap kesalahan ini di ADAL... ... menangkap 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

Pengelogan ADAL ke Pengelogan 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
}