Tutorial: Menambahkan dukungan mode perangkat bersama ke aplikasi Android Anda
Dalam tutorial ini, pengembang Android mempelajari cara menambahkan dukungan mode perangkat bersama di aplikasi Android menggunakan Microsoft Authentication Library (MSAL) untuk Android.
Dalam tutorial ini:
- Membuat atau memodifikasi proyek aplikasi Android yang ada.
- Mengaktifkan dan mendeteksi mode perangkat bersama
- Mendeteksi mode akun tunggal atau beberapa
- Mendeteksi sakelar pengguna
- Mengaktifkan masuk dan 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 sampel, tambahkan pustaka MSAL sebagai dependensi dalam file build.gradle Anda, seperti:
dependencies{
implementation 'com.microsoft.identity.client.msal:4.9.+'
}
Menambahkan dukungan untuk mode akun tunggal
Aplikasi yang ditulis menggunakan Microsoft Authentication Library (MSAL) SDK 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 pada perangkat bersama. Jika karyawan memuat aplikasi yang tidak mendukung mode akun tunggal, aplikasi tersebut tidak akan berjalan di perangkat bersama.
Aplikasi yang ditulis sebelum MSAL SDK 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 aplikasi Anda saat ini mendukung beberapa akun dan Anda ingin mendukung mode perangkat bersama, tambahkan dukungan untuk mode akun tunggal.
Anda mungkin juga ingin aplikasi mengubah perilakunya tergantung pada jenis perangkat yang dijalankannya. Gunakan ISingleAccountPublicClientApplication.isSharedDevice() untuk menentukan kapan harus berjalan dalam mode akun tunggal.
Ada dua antarmuka berbeda yang mewakili jenis perangkat tempat aplikasi Anda aktif. Saat 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:
Anda perlu melakukan pemeriksaan jenis dan transmisi ke antarmuka yang sesuai saat Anda mendapatkan objek Anda PublicClientApplication . 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 mode bersama | Perangkat pribadi | |
|---|---|---|
| Account | Akun tunggal | Beberapa akun |
| Masuk | Global | Global |
| Keluar | Global | Setiap aplikasi dapat mengontrol apakah keluar bersifat lokal untuk aplikasi. |
| Jenis akun yang didukung | Akun kerja saja | Akun pribadi dan kerja 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. Itu 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 mentah res>utama>aplikasi>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 bersama
Mode perangkat bersama memungkinkan Anda mengonfigurasi perangkat Android untuk dibagikan oleh beberapa karyawan, sambil 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 pada perangkat yang berada dalam mode perangkat bersama. Aplikasi Anda dapat menggunakan bendera ini untuk menentukan apakah harus memodifikasi UX yang sesuai.
Berikut adalah cuplikan kode yang menunjukkan bagaimana Anda dapat menggunakan isSharedDevice(). Ini dari SingleAccountModeFragment kelas di aplikasi sampel:
deviceModeTextView.setText(mSingleAccountApp.isSharedDevice() ? "Shared" : "Non-Shared");
Menginisialisasi objek PublicClientApplication
Jika Anda mengatur "account_mode":"SINGLE" dalam file konfigurasi MSAL, Anda dapat dengan aman mentransmisikan objek aplikasi yang ISingleAccountPublicCLientApplicationdikembalikan sebagai .
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 catatan 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 bersama, Anda harus melakukan pemeriksaan jenis dan mentransmisikan 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;
...
}
Mendapatkan pengguna yang masuk dan menentukan apakah pengguna telah berubah di perangkat
Metode ini loadAccount mengambil akun pengguna yang masuk. Metode onAccountChanged menentukan apakah pengguna yang masuk telah berubah, dan jika demikian, bersihkan:
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
Berikut ini memasukkan pengguna di seluruh perangkat ke aplikasi lain yang menggunakan MSAL dengan Aplikasi Authenticator:
private void onSignInClicked()
{
mSingleAccountApp.signIn(getActivity(), SCOPES, null, getAuthInteractiveCallback());
}
Keluarkan pengguna secara global
Berikut ini menghapus akun yang masuk dan menghapus token yang di-cache dari tidak hanya 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 siaran untuk mendeteksi keluar 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 terdaftar konteks.
Saat siaran perubahan akun diterima, segera 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.
Nota
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. Kemudian, Anda akan menerima objek konfigurasi yang dapat digunakan untuk aplikasi yang akan dipotong dan ditempelkan ke file auth_config.json.
Anda harus memilih Buat perubahan ini untuk saya lalu berikan nilai yang diminta mulai 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 Anda dengan memilih Peran Identitas>& Peran admin>& admin>Semua peran, lalu pilih Administrator Perangkat Cloud. Tambahkan pengguna yang dapat memasukkan perangkat ke dalam mode bersama.
Menjalankan aplikasi sampel
Aplikasi Sampel adalah aplikasi sederhana yang akan memanggil Graph API organisasi Anda. Pada eksekusi pertama, Anda akan diminta untuk menyetujui karena aplikasi baru untuk akun karyawan Anda.
Langkah berikutnya
Siapkan perangkat Android untuk menjalankan aplikasi dalam mode perangkat bersama dan menguji aplikasi Anda.