Mulai cepat: Menambahkan masuk pengguna dengan Microsoft ke aplikasi Android - Microsoft identity platform

Artikel
10/24/2023

Selamat Datang! Ini mungkin bukan halaman yang Anda inginkan. Saat ini kami sedang melakukan perbaikan. Untuk sementara waktu, silakan gunakan tautan di bawah ini yang akan membawa Anda ke artikel yang tepat:

Mulai cepat: Memasukkan pengguna dan memanggil Microsoft Graph dari aplikasi Android

Kami mohon maaf atas ketidaknyamanan ini dan menghargai kesabaran Anda selama kami menyelesaikan masalah ini.

Dalam mulai cepat ini, Anda mengunduh dan menjalankan sampel kode yang menunjukkan bagaimana aplikasi Android dapat masuk ke pengguna dan mendapatkan token akses untuk memanggil Microsoft Graph API.

Lihat Cara kerja sampel untuk melihat ilustrasi.

Aplikasi harus diwakili oleh objek aplikasi di MICROSOFT Entra ID sehingga platform identitas Microsoft dapat memberikan token ke aplikasi Anda.

Prasyarat

Akun Azure dengan langganan aktif. Buat akun secara gratis.
Android Studio
Android 16+

Langkah 1: Konfigurasikan aplikasi di portal Microsoft Azure

Agar sampel kode dalam mulai cepat ini berfungsi, tambahkan URI Pengalihan yang kompatibel dengan broker Auth.

Buat perubahan ini untuk saya

Already configured Aplikasi Anda dikonfigurasi dengan atribut ini

Langkah 2: Unduh proyek

Menjalankan project menggunakan Android Studio.

Unduh sampel kode

Langkah 3: Aplikasi Anda dikonfigurasi dan siap dijalankan

Kami telah mengonfigurasi proyek Anda dengan nilai properti aplikasi Anda dan siap dijalankan. Contoh aplikasi dimulai pada layar Mode Akun Tunggal. Cakupan default, user.read, disediakan secara default, yang digunakan saat membaca data profil Anda sendiri selama panggilan Microsoft Graph API. URL untuk panggilan Microsoft Graph API disediakan secara default. Anda dapat mengubah kedua hal ini jika Anda mau.

MSAL sample app showing single and multiple account usage

Gunakan menu aplikasi untuk mengubah antara mode satu dan beberapa akun.

Dalam mode satu akun, masuklah menggunakan akun kantor atau rumah:

Pilih Dapatkan data grafik secara interaktif untuk meminta kredensial pengguna. Anda akan melihat output dari panggilan ke Microsoft Graph API di bagian bawah layar.
Setelah masuk, pilih Dapatkan data grafik secara diam-diam untuk melakukan panggilan ke Microsoft Graph API tanpa meminta kredensial lagi kepada pengguna. Anda akan melihat output dari panggilan ke Microsoft Graph API di bagian bawah layar.

Dalam beberapa mode akun, Anda dapat mengulangi langkah yang sama. Selain itu, Anda dapat menghapus akun masuk, yang juga menghapus token cache untuk akun tersebut.

Catatan

Enter_the_Supported_Account_Info_Here

Cara kerja sampel

Screenshot of the sample app

Kode diatur ke dalam fragmen yang menunjukkan cara menulis satu dan beberapa akun aplikasi MSAL. File kode diatur sebagai berikut:

File	Menunjukkan
MainActivity	Mengelola UI
MSGraphRequestWrapper	Memanggil Microsoft Graph API menggunakan token yang disediakan oleh MSAL
MultipleAccountModeFragment	Menginisialisasi aplikasi multi-akun, memuat akun pengguna, dan mendapatkan token untuk memanggil Microsoft Graph API
SingleAccountModeFragment	Menginisialisasi aplikasi satu akun, memuat akun pengguna, dan mendapatkan token untuk memanggil Microsoft Graph API
res/auth_config_multiple_account.json	File konfigurasi beberapa akun
res/auth_config_single_account.json	File konfigurasi akun tunggal
Gradle Scripts/build.grade (Module:app)	Dependensi pustaka MSAL ditambahkan di sini

Sekarang kita akan melihat file-file ini secara lebih rinci dan memanggil kode khusus MSAL di masing-masing.

Menambahkan MSAL ke aplikasi

MSAL (com.microsoft.identity.client) adalah pustaka yang digunakan untuk masuk pengguna dan meminta token yang digunakan untuk mengakses API yang dilindungi oleh platform identitas Microsoft. Gradle 3.0+ menginstal pustaka saat Anda menambahkan yang berikut ke Gradle Scripts>build.gradle (Module: app) di bawah Dependensi:

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

Yang menginstruksikan Gradle untuk mengunduh dan membangun MSAL dari maven central.

Anda juga harus menambahkan referensi ke maven ke bagian repositori allprojects> bagian dari build.gradle (Module: app) seperti ini:

allprojects {
    repositories {
        mavenCentral()
        google()
        mavenLocal()
        maven {
            url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
        }
        maven {
            name "vsts-maven-adal-android"
            url "https://identitydivision.pkgs.visualstudio.com/_packaging/AndroidADAL/maven/v1"
            credentials {
                username System.getenv("ENV_VSTS_MVN_ANDROIDADAL_USERNAME") != null ? System.getenv("ENV_VSTS_MVN_ANDROIDADAL_USERNAME") : project.findProperty("vstsUsername")
                password System.getenv("ENV_VSTS_MVN_ANDROIDADAL_ACCESSTOKEN") != null ? System.getenv("ENV_VSTS_MVN_ANDROIDADAL_ACCESSTOKEN") : project.findProperty("vstsMavenAccessToken")
            }
        }
        jcenter()
    }
}

Impor MSAL

Impor yang relevan dengan perpustakaan MSAL adalah com.microsoft.identity.client.*. Misalnya, Anda akan melihat import > com.microsoft.identity.client.PublicClientApplication;namespace untuk PublicClientApplication kelas, yang mewakili aplikasi klien publik Anda.

SingleAccountModeFragment.java

File ini menunjukkan cara membuat aplikasi MSAL satu akun dan memanggil Microsoft Graph API.

Aplikasi akun tunggal hanya digunakan oleh satu pengguna. Misalnya, Anda mungkin hanya memiliki satu akun yang Anda masuk ke aplikasi pemetaan.

Inisialisasi MSAL akun tunggal

Diauth_config_single_account.json, dalamonCreateView(), satu akunPublicClientApplication dibuat menggunakan informasi konfigurasi yang disimpan dalam auth_config_single_account.json file. Ini adalah cara Anda menginisialisasi pustaka MSAL untuk digunakan dalam aplikasi MSAL satu akun:

...
// Creates a PublicClientApplication object with res/raw/auth_config_single_account.json
PublicClientApplication.createSingleAccountPublicClientApplication(getContext(),
        R.raw.auth_config_single_account,
        new IPublicClientApplication.ISingleAccountApplicationCreatedListener() {
            @Override
            public void onCreated(ISingleAccountPublicClientApplication application) {
                /**
                 * This test app assumes that the app is only going to support one account.
                 * This requires "account_mode" : "SINGLE" in the config json file.
                 **/
                mSingleAccountApp = application;
                loadAccount();
            }

            @Override
            public void onError(MsalException exception) {
                displayError(exception);
            }
        });

Dalam SingleAccountModeFragment.java, kode untuk masuk pengguna tersediainitializeUI(), di signInButtonklik handel.

Panggilan signIn() sebelum mencoba memperoleh token. signIn() berperilaku seolah-olah acquireToken() dipanggil, menghasilkan permintaan interaktif bagi pengguna untuk masuk.

Memasukkan pengguna adalah operasi asinkron. Panggil balik dilewatkan yang memanggil Microsoft Graph API dan memperbarui UI setelah pengguna masuk:

mSingleAccountApp.signIn(getActivity(), null, getScopes(), getAuthInteractiveCallback());

Keluarkan pengguna

Dalam SingleAccountModeFragment.java, kode untuk keluar pengguna yang ada di dalaminitializeUI(), di signOutButtonklik handel. Mengeluarkan pengguna merupakan operasi asinkron. Mengeluarkan pengguna juga menghapus cache token untuk akun tersebut. Panggil balik dibuat untuk memperbarui UI setelah akun pengguna keluar:

mSingleAccountApp.signOut(new ISingleAccountPublicClientApplication.SignOutCallback() {
    @Override
    public void onSignOut() {
        updateUI(null);
        performOperationOnSignOut();
    }

    @Override
    public void onError(@NonNull MsalException exception) {
        displayError(exception);
    }
});

Dapatkan token secara interaktif atau diam-diam

Untuk menyajikan jumlah permintaan terkecil kepada pengguna, Biasanya Anda akan mendapatkan token secara diam-diam. Kemudian, jika ada kesalahan, upaya untuk mendapatkan token secara interaktif. Pertama kali aplikasi memanggilsignIn(), aplikasi secara efektif bertindak sebagai panggilan ke acquireToken(), yang akan meminta kredensial kepada pengguna.

Beberapa situasi saat pengguna mungkin diminta untuk memilih akun mereka, memasukkan kredensial mereka, atau menyetujui izin yang diminta aplikasi Anda adalah:

Pertama kali pengguna masuk ke aplikasi
Jika pengguna mengatur ulang kata sandi, mereka harus memasukkan kredensial mereka
Jika persetujuan dicabut
Jika aplikasi Anda secara eksplisit memerlukan persetujuan
Ketika aplikasi Anda meminta akses ke sumber daya untuk pertama kalinya
Ketika MFA atau kebijakan Akses Bersyarat lainnya diperlukan

Kode untuk mendapatkan token secara interaktif, berada di UI yang akan melibatkan pengguna, yang ada di dalam SingleAccountModeFragment.java, di initializeUI(), di callGraphApiInteractiveButton klik handel:

/**
 * If acquireTokenSilent() returns an error that requires an interaction (MsalUiRequiredException),
 * invoke acquireToken() to have the user resolve the interrupt interactively.
 *
 * Some example scenarios are
 *  - password change
 *  - the resource you're acquiring a token for has a stricter set of requirement than your Single Sign-On refresh token.
 *  - you're introducing a new scope which the user has never consented for.
 **/
mSingleAccountApp.acquireToken(getActivity(), getScopes(), getAuthInteractiveCallback());

Jika pengguna sudah masuk, acquireTokenSilentAsync() memungkinkan aplikasi untuk meminta token secara senyap seperti yang ditunjukkan dalam >initializeUI(), di callGraphApiSilentButton klik handel:

/**
 * Once you've signed the user in,
 * you can perform acquireTokenSilent to obtain resources without interrupting the user.
 **/
  mSingleAccountApp.acquireTokenSilentAsync(getScopes(), AUTHORITY, getAuthSilentCallback());

Memuat akun

Kode untuk memuat akun berada SingleAccountModeFragment.java di loadAccount(). Memuat akun pengguna adalah operasi asinkron, jadi fitur panggil balik untuk menangani ketika akun dimuat, diubah, atau kesalahan terjadi akan diteruskan ke MSAL. Kode berikut juga menangani onAccountChanged(), yang terjadi ketika akun dihapus, pengguna berubah ke akun lain, dan sebagainya.

private void loadAccount() {
    ...

    mSingleAccountApp.getCurrentAccountAsync(new ISingleAccountPublicClientApplication.CurrentAccountCallback() {
        @Override
        public void onAccountLoaded(@Nullable IAccount activeAccount) {
            // You can use the account data to update your UI or your app database.
            updateUI(activeAccount);
        }

        @Override
        public void onAccountChanged(@Nullable IAccount priorAccount, @Nullable IAccount currentAccount) {
            if (currentAccount == null) {
                // Perform a cleanup task as the signed-in account changed.
                performOperationOnSignOut();
            }
        }

        @Override
        public void onError(@NonNull MsalException exception) {
            displayError(exception);
        }
    });

Memanggil Microsoft Graph

Ketika pengguna masuk, panggilan ke Microsoft Graph dilakukan melalui permintaan HTTP callGraphAPI() yang didefinisikan dalam SingleAccountModeFragment.java. Fungsi ini adalah pembungkus yang menyederhanakan sampel dengan melakukan beberapa tugas seperti mendapatkan token akses dariauthenticationResult dan mengemas panggilan ke MSGraphRequestWrapper, dan menampilkan hasil panggilan.

private void callGraphAPI(final IAuthenticationResult authenticationResult) {
    MSGraphRequestWrapper.callGraphAPIUsingVolley(
            getContext(),
            graphResourceTextView.getText().toString(),
            authenticationResult.getAccessToken(),
            new Response.Listener<JSONObject>() {
                @Override
                public void onResponse(JSONObject response) {
                    /* Successfully called graph, process data and send to UI */
                    ...
                }
            },
            new Response.ErrorListener() {
                @Override
                public void onErrorResponse(VolleyError error) {
                    ...
                }
            });
}

auth_config_single_account.json

Ini adalah file konfigurasi untuk aplikasi MSAL yang menggunakan satu akun.

Lihat Memahami file konfigurasi MSAL Android untuk penjelasan tentang kolom ini.

Perhatikan keberadaan "account_mode" : "SINGLE", yang mengonfigurasi aplikasi ini untuk menggunakan satu akun.

"client_id" telah dikonfigurasi untuk menggunakan pendaftaran objek aplikasi yang dikelola Microsoft. "redirect_uri"telah dikonfigurasi untuk menggunakan kunci masuk yang disediakan dengan sampel kode.

{
  "client_id" : "0984a7b6-bc13-4141-8b0d-8f767e136bb7",
  "authorization_user_agent" : "DEFAULT",
  "redirect_uri" : "msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "account_mode" : "SINGLE",
  "broker_redirect_uri_registered": true,
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

MultipleAccountModeFragment.java

File ini menunjukkan cara membuat aplikasi MSAL beberapa akun dan memanggil Microsoft Graph API.

Contoh aplikasi beberapa akun adalah aplikasi email yang memungkinkan Anda bekerja dengan beberapa akun pengguna seperti akun kantor dan akun pribadi.

Inisialisasi MSAL beberapa akun

Dalam MultipleAccountModeFragment.java file, dalam onCreateView(), objek aplikasi beberapa akun (IMultipleAccountPublicClientApplication) dibuat menggunakan informasi konfigurasi yang disimpan di auth_config_multiple_account.json file:

// Creates a PublicClientApplication object with res/raw/auth_config_multiple_account.json
PublicClientApplication.createMultipleAccountPublicClientApplication(getContext(),
        R.raw.auth_config_multiple_account,
        new IPublicClientApplication.IMultipleAccountApplicationCreatedListener() {
            @Override
            public void onCreated(IMultipleAccountPublicClientApplication application) {
                mMultipleAccountApp = application;
                loadAccounts();
            }

            @Override
            public void onError(MsalException exception) {
                ...
            }
        });

Objek MultipleAccountPublicClientApplication yang dibuat disimpan dalam variabel anggota kelas sehingga dapat digunakan untuk berinteraksi dengan pustaka MSAL untuk memperoleh token dan memuat dan menghapus akun pengguna.

Memuat akun

Beberapa aplikasi akun biasanya memanggil getAccounts() untuk memilih akun yang akan digunakan untuk operasi MSAL. Kode untuk memuat akun ada di file MultipleAccountModeFragment.java, di loadAccounts(). Memuat akun pengguna adalah operasi asinkron. Jadi fitur panggil balik akan menangani situasi ketika akun dimuat, diubah, atau kesalahan terjadi.

/**
 * Load currently signed-in accounts, if there's any.
 **/
private void loadAccounts() {
    if (mMultipleAccountApp == null) {
        return;
    }

    mMultipleAccountApp.getAccounts(new IPublicClientApplication.LoadAccountsCallback() {
        @Override
        public void onTaskCompleted(final List<IAccount> result) {
            // You can use the account data to update your UI or your app database.
            accountList = result;
            updateUI(accountList);
        }

        @Override
        public void onError(MsalException exception) {
            displayError(exception);
        }
    });
}

Dapatkan token secara interaktif atau diam-diam

Beberapa situasi saat pengguna mungkin diminta untuk memilih akun mereka, memasukkan kredensial mereka, atau menyetujui izin yang diminta aplikasi Anda adalah:

Pertama kali pengguna masuk ke aplikasi
Jika pengguna mengatur ulang kata sandi, mereka harus memasukkan kredensial mereka
Jika persetujuan dicabut
Jika aplikasi Anda secara eksplisit memerlukan persetujuan
Ketika aplikasi Anda meminta akses ke sumber daya untuk pertama kalinya
Ketika MFA atau kebijakan Akses Bersyarat lainnya diperlukan

Beberapa aplikasi akun biasanya harus memperoleh token secara interaktif, yaitu dengan UI yang melibatkan pengguna, dengan panggilan ke acquireToken(). Kode untuk mendapatkan token secara interaktif ada dalam MultipleAccountModeFragment.java file diinitializeUI> (), di callGraphApiInteractiveButtonklik handel:

/**
 * Acquire token interactively. It will also create an account object for the silent call as a result (to be obtained by > getAccount()).
 *
 * If acquireTokenSilent() returns an error that requires an interaction,
 * invoke acquireToken() to have the user resolve the interrupt interactively.
 *
 * Some example scenarios are
 *  - password change
 *  - the resource you're acquiring a token for has a stricter set of requirement than your SSO refresh token.
 *  - you're introducing a new scope which the user has never consented for.
 **/
mMultipleAccountApp.acquireToken(getActivity(), getScopes(), getAuthInteractiveCallback());

Aplikasi seharusnya tidak mengharuskan pengguna untuk masuk setiap kali mereka meminta token. Jika pengguna telah masuk, acquireTokenSilentAsync() memungkinkan aplikasi untuk meminta token tanpa meminta pengguna, seperti yang ditunjukkan dalam MultipleAccountModeFragment.java file, di dalam initializeUI() di callGraphApiSilentButton klik handel:

/**
 * Performs acquireToken without interrupting the user.
 *
 * This requires an account object of the account you're obtaining a token for.
 * (can be obtained via getAccount()).
 */
mMultipleAccountApp.acquireTokenSilentAsync(getScopes(),
    accountList.get(accountListSpinner.getSelectedItemPosition()),
    AUTHORITY,
    getAuthSilentCallback());

Menghapus akun

Kode untuk menghapus akun, dan token cache untuk akun, ada di dalam MultipleAccountModeFragment.java file di initializeUI()dalam handel untuk tombol hapus akun. Sebelum Anda dapat menghapus akun, Anda memerlukan objek akun, yang Anda peroleh dari metode MSAL seperti getAccounts() dan acquireToken(). Karena menghapus akun adalah operasi asinkron, onRemoved panggil balik diberikan untuk memperbarui UI.

/**
 * Removes the selected account and cached tokens from this app (or device, if the device is in shared mode).
 **/
mMultipleAccountApp.removeAccount(accountList.get(accountListSpinner.getSelectedItemPosition()),
        new IMultipleAccountPublicClientApplication.RemoveAccountCallback() {
            @Override
            public void onRemoved() {
                ...
                /* Reload account asynchronously to get the up-to-date list. */
                loadAccounts();
            }

            @Override
            public void onError(@NonNull MsalException exception) {
                displayError(exception);
            }
        });

auth_config_multiple_account.json

Ini adalah file konfigurasi untuk aplikasi MSAL yang menggunakan beberapa akun.

Lihat Memahami file konfigurasi MSAL Android untuk penjelasan dari berbagai bidang.

Tidak seperti file konfigurasi auth_config_single_account.json, file konfigurasi ini memiliki "account_mode" : "MULTIPLE""account_mode" : "SINGLE"karena ini adalah aplikasi beberapa akun.

{
  "client_id" : "0984a7b6-bc13-4141-8b0d-8f767e136bb7",
  "authorization_user_agent" : "DEFAULT",
  "redirect_uri" : "msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",
  "account_mode" : "MULTIPLE",
  "broker_redirect_uri_registered": true,
  "authorities" : [
    {
      "type": "AAD",
      "audience": {
        "type": "AzureADandPersonalMicrosoftAccount",
        "tenant_id": "common"
      }
    }
  ]
}

Bantuan dan dukungan

Jika Anda memerlukan bantuan, ingin melaporkan masalah, atau ingin mempelajari opsi dukungan, lihat Bantuan dan dukungan bagi pengembang.

Langkah berikutnya

Beralih ke tutorial Android di mana Anda membuat aplikasi Android yang mendapatkan token akses dari platform identitas Microsoft dan menggunakannya untuk memanggil Microsoft Graph API.

Tutorial: Memasukkan pengguna dan memanggil Microsoft Graph dari aplikasi Android

Mulai cepat: Masuk pengguna dan menghubungi Microsoft Graph API dari aplikasi Android

Prasyarat

Langkah 1: Konfigurasikan aplikasi di portal Microsoft Azure

Langkah 2: Unduh proyek

Langkah 3: Aplikasi Anda dikonfigurasi dan siap dijalankan

Cara kerja sampel

Menambahkan MSAL ke aplikasi

Impor MSAL

SingleAccountModeFragment.java

Inisialisasi MSAL akun tunggal

Masukkan pengguna

Keluarkan pengguna

Dapatkan token secara interaktif atau diam-diam

Memuat akun

Memanggil Microsoft Graph

auth_config_single_account.json

MultipleAccountModeFragment.java

Inisialisasi MSAL beberapa akun

Memuat akun

Dapatkan token secara interaktif atau diam-diam

Menghapus akun

auth_config_multiple_account.json

Bantuan dan dukungan

Langkah berikutnya

Sumber Daya Tambahan: