Bagikan melalui

Tutorial: Menambahkan dukungan mode perangkat bersama ke aplikasi Android Anda

Berlaku untuk: Lingkaran hijau dengan simbol tanda centang putih. Penyewa tenaga kerja Lingkaran putih dengan simbol X abu-abu. Penyewa eksternal (pelajari selengkapnya)

Dalam tutorial ini, pengembang Android mempelajari cara menambahkan dukungan mode perangkat bersama di aplikasi Android menggunakan Microsoft Authentication Library (MSAL) untuk Android.

Di tutorial ini, Anda akan:

  • Membuat atau memodifikasi proyek aplikasi Android yang ada.
  • Mengaktifkan dan mendeteksi mode berbagi perangkat
  • Mendeteksi mode akun tunggal atau ganda
  • Mendeteksi perubahan pengguna
  • Mengaktifkan log masuk dan log keluar global

Membuat atau memodifikasi aplikasi Android yang sudah ada

Untuk menyelesaikan tutorial lainnya, Anda perlu membuat aplikasi Android baru atau memodifikasi aplikasi Android yang sudah ada. Jika Anda belum melakukannya, lihat tutorial MSAL Android untuk panduan tentang cara mengintegrasikan MSAL dengan aplikasi Android Anda, memasukkan pengguna, memanggil Microsoft graph, dan mengeluarkan pengguna. Jika Anda lebih suka menggunakan sampel kode lengkap untuk pembelajaran dan pengujian, kloning aplikasi sampel dari GitHub. Sampel memiliki kemampuan untuk bekerja dalam mode satu atau beberapa akun.

Menambahkan MSAL SDK ke repositori Maven lokal Anda

Jika Anda tidak menggunakan aplikasi contoh, tambahkan pustaka MSAL sebagai dependensi dalam file build.gradle, seperti:

dependencies{
  implementation 'com.microsoft.identity.client.msal:4.9.+'
}

Menambahkan dukungan untuk mode akun tunggal

Aplikasi yang ditulis menggunakan SDK Pustaka Autentikasi Microsoft (MSAL) dapat mengelola satu akun atau beberapa akun. Untuk detailnya, lihat mode akun tunggal atau mode beberapa akun.

Fitur platform identitas Microsoft yang tersedia untuk aplikasi Anda bervariasi tergantung pada apakah aplikasi berjalan dalam mode akun tunggal atau mode beberapa akun.

Aplikasi mode perangkat bersama hanya berfungsi dalam mode akun tunggal.

Penting

Aplikasi yang hanya mendukung mode beberapa akun tidak dapat berjalan di perangkat bersama. Jika karyawan memuat aplikasi yang tidak mendukung mode akun tunggal, aplikasi tersebut tidak akan berjalan di perangkat bersama.

Aplikasi yang ditulis sebelum SDK MSAL dirilis berjalan dalam mode beberapa akun dan harus diperbarui untuk mendukung mode akun tunggal sebelum dapat berjalan pada perangkat mode bersama. Mendukung akun tunggal dan beberapa akun

Aplikasi Anda dapat dibuat untuk mendukung berjalan di perangkat pribadi dan perangkat bersama. Jika saat ini aplikasi Anda mendukung beberapa akun dan ingin mendukung mode perangkat bersama, tambahkan dukungan untuk mode akun tunggal.

Anda mungkin juga ingin aplikasi Anda mengubah perilakunya tergantung jenis perangkat yang menjalankannya. Gunakan ISingleAccountPublicClientApplication.isSharedDevice() untuk menentukan kapan harus menjalankan mode akun tunggal.

Ada dua antarmuka berbeda yang melambangkan jenis perangkat yang digunakan aplikasi Anda. Ketika Anda meminta instans aplikasi dari pabrik aplikasi MSAL, objek aplikasi yang benar disediakan secara otomatis.

Model objek berikut mengilustrasikan jenis objek yang mungkin Anda terima dan apa artinya dalam konteks perangkat bersama:

Diagram model pewarisan aplikasi klien publik.

Anda perlu memeriksa jenis dan mengonversi ke antarmuka yang sesuai ketika Anda mendapatkan objek PublicClientApplication Anda. Kode berikut memeriksa beberapa mode akun atau mode akun tunggal, dan melemparkan objek aplikasi dengan tepat:

private IPublicClientApplication mApplication;

        // Running in personal-device mode?
        if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
          IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
          ...
        // Running in shared-device mode?
        } else if (mApplication instanceOf ISingleAccountPublicClientApplication) {
           ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
            ...
        }

Perbedaan berikut berlaku tergantung pada apakah aplikasi Anda berjalan di perangkat bersama atau pribadi:

Perangkat dalam mode berbagi Perangkat pribadi
Rekening Akun tunggal Beberapa akun
Masuk Mendunia Mendunia
Keluar Mendunia Setiap aplikasi dapat mengontrol apakah keluar hanya berlaku untuk aplikasi tersebut.
Jenis akun yang didukung Akun kantor saja Akun pribadi dan akun kerja yang didukung

Mengonfigurasi aplikasi Anda untuk menggunakan mode perangkat bersama

Lihat dokumentasi konfigurasi untuk informasi selengkapnya tentang menyiapkan file konfigurasi Anda.

Atur "shared_device_mode_supported" ke true dalam file konfigurasi MSAL Anda.

Anda mungkin tidak berencana untuk mendukung mode beberapa akun. Bisa jadi jika Anda tidak menggunakan perangkat bersama, dan pengguna dapat masuk ke aplikasi dengan lebih dari satu akun secara bersamaan. Jika demikian, atur "account_mode" ke "SINGLE". Ini menjamin bahwa aplikasi Anda akan selalu mendapatkan ISingleAccountPublicClientApplication, dan secara signifikan menyederhanakan integrasi MSAL Anda. Nilai "account_mode" default adalah "MULTIPLE", jadi penting untuk mengubah nilai ini dalam file konfigurasi jika Anda menggunakan "single account" mode.

Berikut adalah contoh file auth_config.json yang disertakan dalam direktori aplikasi>utama>res>mentah dari aplikasi sampel:

{
  "client_id": "Client ID after app registration at https://aka.ms/MobileAppReg",
  "authorization_user_agent": "DEFAULT",
  "redirect_uri": "Redirect URI after app registration at https://aka.ms/MobileAppReg",
  "account_mode": "SINGLE",
  "broker_redirect_uri_registered": true,
  "shared_device_mode_supported": true,
  "authorities": [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

Mendeteksi mode perangkat yang digunakan bersama

Mode perangkat bersama memungkinkan Anda mengonfigurasi perangkat Android untuk dibagikan oleh beberapa karyawan, sekaligus menyediakan manajemen perangkat yang didukung Microsoft Identity. Karyawan dapat masuk ke perangkat mereka dan mengakses informasi pelanggan dengan cepat. Setelah selesai dengan shift atau tugas, mereka akan dapat keluar dari semua aplikasi di perangkat bersama dengan satu klik dan perangkat akan segera siap untuk digunakan karyawan berikutnya.

Gunakan isSharedDevice() untuk menentukan apakah aplikasi berjalan di perangkat yang berada dalam mode perangkat bersama. Aplikasi Anda dapat menggunakan bendera ini untuk menentukan apakah harus memodifikasi UX dengan semestinya.

Berikut adalah cuplikan kode yang menunjukkan bagaimana Anda bisa menggunakan isSharedDevice(). Ini dari kelas SingleAccountModeFragment di aplikasi contoh:

deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");

Menginisialisasi objek PublicClientApplication

Jika mengatur "account_mode":"SINGLE" di file konfigurasi MSAL, Anda dapat dengan aman mentransmisikan objek aplikasi yang dikembalikan sebagai ISingleAccountPublicCLientApplication.

private ISingleAccountPublicClientApplication mSingleAccountApp;

/*Configure your sample app and save state for this activity*/
PublicClientApplication.create(this.getApplicationCOntext(),
  R.raw.auth_config,
  new PublicClientApplication.ApplicationCreatedListener(){
  @Override
  public void onCreated(IPublicClientApplication application){
  mSingleAccountApp = (ISingleAccountPublicClientApplication)application;
  loadAccount();
  }
  @Override
  public void onError(MsalException exception){
  /*Fail to initialize PublicClientApplication */
  }
});

Mendeteksi mode satu vs. beberapa akun

Jika Anda menulis aplikasi yang hanya akan digunakan untuk pekerja garis depan di perangkat bersama, kami sarankan Anda menulis aplikasi untuk hanya mendukung mode akun tunggal. Ini termasuk sebagian besar aplikasi yang berfokus pada tugas seperti aplikasi rekaman medis, aplikasi faktur, dan sebagian besar aplikasi lini bisnis. Ini akan menyederhanakan pengembangan Anda karena banyak fitur SDK tidak perlu diakomodasi.

Jika aplikasi mendukung beberapa akun dan mode perangkat berbagi, Anda harus melakukan pemeriksaan jenis dan mengubah ke antarmuka yang sesuai seperti yang ditunjukkan di bawah ini.

private IPublicClientApplication mApplication;

        if (mApplication instanceOf IMultipleAccountPublicClientApplication) {
          IMultipleAccountPublicClientApplication multipleAccountApplication = (IMultipleAccountPublicClientApplication) mApplication;
          ...
        } else if (mApplication instanceOf    ISingleAccountPublicClientApplication) {
           ISingleAccountPublicClientApplication singleAccountApplication = (ISingleAccountPublicClientApplication) mApplication;
            ...
        }

Dapatkan pengguna yang sudah masuk dan periksa apakah ada perubahan pengguna di perangkat

Metode loadAccount mengambil akun dari pengguna yang sedang masuk. Metode onAccountChanged menentukan apakah pengguna yang masuk telah berubah, dan jika demikian, hapus:

private void loadAccount()
{
  mSingleAccountApp.getCurrentAccountAsync(new ISingleAccountPublicClientApplication.CurrentAccountCallback())
  {
    @Override
    public void onAccountLoaded(@Nullable IAccount activeAccount)
    {
      if (activeAccount != null)
      {
        signedInUser = activeAccount;
        mSingleAccountApp.acquireTokenSilentAsync(SCOPES,"http://login.microsoftonline.com/common",getAuthSilentCallback());
      }
    }
    @Override
    public void onAccountChanged(@Nullable IAccount priorAccount, @Nullable Iaccount currentAccount)
    {
      if (currentAccount == null)
      {
        //Perform a cleanup task as the signed-in account changed.
        updateSingedOutUI();
      }
    }
    @Override
    public void onError(@NonNull Exception exception)
    {
    }
  }
}

Masuk pengguna secara global

Tanda tangan berikut pengguna masuk dari satu perangkat ke perangkat lainnya pada aplikasi lain yang memakai MSAL dengan menggunakan Aplikasi Authenticator.

private void onSignInClicked()
{
  mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}

Mengeluarkan pengguna secara global

Tindakan berikut ini akan menghapus akun yang masuk dan menghapus token yang dalam cache tidak hanya pada aplikasi tetapi juga dari perangkat yang berada dalam mode perangkat bersama:

private void onSignOutClicked()
{
  mSingleAccountApp.signOut(new ISingleAccountPublicClientApplication.SignOutCallback()
  {
    @Override
    public void onSignOut()
    {
      updateSignedOutUI();
    }
    @Override
    public void onError(@NonNull MsalException exception)
    {
      /*failed to remove account with an exception*/
    }
  });
}

Menerima sinyal untuk mendeteksi keluar dari akun secara global yang dimulai dari aplikasi lain

Untuk menerima siaran perubahan akun, Anda perlu mendaftarkan penerima siaran. Disarankan untuk mendaftarkan penerima siaran Anda melalui penerima yang didaftarkan melalui Konteks.

Segera setelah notifikasi perubahan akun diterima, dapatkan pengguna yang masuk dan tentukan apakah pengguna telah berubah di perangkat. Jika perubahan terdeteksi, mulai pembersihan data untuk akun yang sebelumnya masuk. Disarankan untuk menghentikan operasi apa pun dengan benar dan melakukan pembersihan data.

Cuplikan kode berikut menunjukkan bagaimana Anda dapat mendaftarkan penerima siaran.

private static final String CURRENT_ACCOUNT_CHANGED_BROADCAST_IDENTIFIER = "com.microsoft.identity.client.sharedmode.CURRENT_ACCOUNT_CHANGED";
private BroadcastReceiver mAccountChangedBroadcastReceiver;
private void registerAccountChangeBroadcastReceiver(){
    mAccountChangedBroadcastReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            //INVOKE YOUR PRIOR ACCOUNT CLEAN UP LOGIC HERE
        }
    };
    IntentFilter filter = new

    IntentFilter(CURRENT_ACCOUNT_CHANGED_BROADCAST_IDENTIFIER);
    this.registerReceiver(mAccountChangedBroadcastReceiver, filter);
}

Daftarkan aplikasi dan siapkan penyewa Anda untuk pengujian

Sebelum dapat menyiapkan aplikasi dan memasukkan perangkat ke mode perangkat bersama, Anda perlu mendaftarkan aplikasi dalam penyewa organisasi Anda. Anda kemudian memberikan nilai-nilai ini dalam auth_config.json agar aplikasi Anda berjalan dengan benar.

Untuk informasi tentang cara melakukan ini, lihat Mendaftarkan aplikasi Anda.

Catatan

Saat Mendaftarkan aplikasi, silakan gunakan panduan mulai cepat di sisi kiri lalu pilih Android. Ini akan mengarahkan Anda ke halaman tempat Anda akan diminta untuk memberikan Nama Paket dan Hash Tanda Tangan untuk aplikasi Anda. Ini sangat penting untuk memastikan konfigurasi aplikasi Anda akan berfungsi. Anda kemudian akan menerima objek konfigurasi yang dapat digunakan untuk aplikasi yang akan dipotong dan di tempelkan ke fil auth_config.json.

Mengonfigurasi halaman aplikasi Android Anda

Anda harus memilih Buat perubahan ini untuk saya, kemudian berikan nilai yang diminta oleh panduan cepat. Setelah selesai, MICROSOFT Entra ID menghasilkan semua file konfigurasi yang Anda butuhkan.

Untuk tujuan pengujian, siapkan peran berikut di penyewa Anda - setidaknya dua karyawan dan Administrator Perangkat Cloud. Untuk mengatur Administrator Perangkat Cloud, Anda perlu memodifikasi Peran Organisasi. Dari pusat admin Microsoft Entra, buka Peran Organisasi dengan memilih Entra IDPeran & adminSemua peran, lalu pilih Administrator Perangkat Cloud. Tambahkan pengguna yang dapat menempatkan perangkat ke mode bersama.

Menjalankan aplikasi contoh

Aplikasi Contoh adalah aplikasi sederhana yang akan memanggil Graph API organisasi Anda. Saat pertama kali dijalankan, Anda akan diminta memberikan persetujuan karena aplikasi ini baru bagi akun karyawan Anda.

Layar info konfigurasi aplikasi

Langkah berikutnya

Siapkan perangkat Android untuk menjalankan aplikasi dalam mode perangkat bersama dan menguji aplikasi Anda.

Mode perangkat bersama untuk perangkat Android