Panduan Cepat: Tambah Masuk dengan Microsoft ke Aplikasi Android - Microsoft identity platform

Selamat Datang! Ini mungkin bukan halaman yang Anda inginkan. Saat ini kami sedang mengerjakan perbaikan, tetapi untuk saat ini, silakan gunakan tautan di bawah ini - itu harus membawa Anda ke artikel yang tepat:

Panduan Cepat: Masuk pengguna dan panggil Microsoft Graph dari aplikasi Android

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

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

Lihat Cara kerja sampel untuk melihat ilustrasi.

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

Prasyarat

Sebuah 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

Sudah dikonfigurasi Aplikasi Anda dikonfigurasi dengan atribut ini

Langkah 2: Unduh proyek

Jalankan proyek 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. Aplikasi sampel 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 keduanya jika mau.

Aplikasi sampel MSAL memperlihatkan penggunaan satu dan beberapa akun

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

Dalam mode akun tunggal, masuk menggunakan akun kantor atau rumah:

Pilih Ambil data grafik secara interaktif untuk meminta pengguna memasukkan kredensial mereka. 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 yang masuk, yang juga menghapus token cache untuk akun tersebut.

Nota

Enter_the_Supported_Account_Info_Here

Cara kerja sampel

Cuplikan layar aplikasi sampel

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

Arsip	Menunjukkan
AktivitasUtama	Mengelola Antarmuka Pengguna
MSGraphRequestWrapper	Memanggil Microsoft Graph API menggunakan token yang disediakan oleh MSAL
FragmenModeBanyakAkun	Menginisialisasi aplikasi multi-akun, memuat akun pengguna, dan mendapatkan token untuk memanggil Microsoft Graph API
ModeAkunTunggalFragment	Menginisialisasi aplikasi akun tunggal, 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
Skrip Gradle/build.gradle (Modul:app)	Dependensi perpustakaan MSAL ditambahkan di sini

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

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.+'
    ...
}

Instruksikan Gradle untuk mengunduh dan membangun MSAL dari Maven Central.

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

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 namespace import > com.microsoft.identity.client.PublicClientApplication;, yang merupakan namespace untuk kelas PublicClientApplication, 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 untuk akun tunggal

Dalam auth_config_single_account.json, dalam onCreateView(), satu akun PublicClientApplication 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 ada di initializeUI(), di signInButton pengendali klik.

Hubungi 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());

Logout pengguna

Dalam SingleAccountModeFragment.java, kode untuk keluar pengguna ada di initializeUI(), di signOutButton klik handler. 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, coba akses 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, mereka harus memasukkan kredensial mereka
Jika persetujuan dicabut
Jika aplikasi Anda secara eksplisit memerlukan persetujuan
Saat aplikasi Anda meminta akses ke sumber daya untuk pertama kalinya
Saat MFA atau kebijakan Akses Bersyarat lainnya diperlukan

Kode untuk mendapatkan token secara interaktif, yaitu dengan UI yang akan melibatkan pengguna, terdapat di dalam SingleAccountModeFragment.java, di initializeUI(), dan di dalam pengelola klik callGraphApiInteractiveButton.

/**
 * 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 telah masuk, acquireTokenSilentAsync() memungkinkan aplikasi untuk meminta token secara diam-diam seperti yang ditunjukkan dalam >initializeUI(), di callGraphApiSilentButton penangan klik:

/**
 * 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 ada di SingleAccountModeFragment.java dalam loadAccount(). Memuat akun pengguna adalah operasi asinkron, jadi fungsi panggil balik untuk menangani kondisi ketika akun dimuat, diubah, atau ketika 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"dikonfigurasi untuk menggunakan kunci penandatanganan yang disediakan dengan sampel kode.

{
  "client_id" : "00001111-aaaa-2222-bbbb-3333cccc4444",
  "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 beberapa akun MSAL

Di dalam berkas MultipleAccountModeFragment.java, di dalam onCreateView(), objek aplikasi multi-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, mereka harus memasukkan kredensial mereka
Jika persetujuan dicabut
Jika aplikasi Anda secara eksplisit memerlukan persetujuan
Saat aplikasi Anda meminta akses ke sumber daya untuk pertama kalinya
Saat 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 memunculkan konfirmasi ke pengguna, seperti yang ditunjukkan dalam file MultipleAccountModeFragment.java, di dalam initializeUI() handler klik callGraphApiSilentButton.

/**
 * 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 yang disimpan di cache untuk akun tersebut ada di dalam MultipleAccountModeFragment.java pada initializeUI() di pengendali untuk tombol hapus akun. Sebelum Anda dapat menghapus akun, Anda memerlukan objek akun, yang Anda peroleh dari metode MSAL seperti getAccounts() dan acquireToken(). Karena penghapusan akun adalah proses yang bersifat asinkron, onRemoved callback disediakan 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" : "00001111-aaaa-2222-bbbb-3333cccc4444",
  "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 selanjutnya

Lanjutkan ke tutorial Android tempat 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

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-04-16

Mulai cepat: Memasukkan pengguna dan memanggil 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 untuk akun tunggal

Masuk sebagai pengguna

Logout pengguna

Dapatkan token secara interaktif atau diam-diam

Memuat akun

Memanggil Microsoft Graph

auth_config_single_account.json

MultipleAccountModeFragment.java

Inisialisasi beberapa akun MSAL

Memuat akun

Dapatkan token secara interaktif atau diam-diam

Menghapus akun

auth_config_multiple_account.json

Bantuan dan dukungan

Langkah selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: