Bagikan melalui


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

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.

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

Prasyarat

Cara kerja sampel

Diagram memperlihatkan cara kerja aplikasi sampel yang dihasilkan oleh mulai cepat ini.

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.

Mendapatkan aplikasi sampel

Mendaftarkan aplikasi sampel

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

  1. Masuk ke pusat admin Microsoft Entra setidaknya sebagai Pengembang Aplikasi.

  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan ikon Pengaturan di menu atas untuk beralih ke penyewa tempat Anda ingin mendaftarkan aplikasi dari menu Direktori + langganan.

  3. Telusuri Aplikasi >Identitas>Pendaftaran aplikasi.

  4. Pilih Pendaftaran baru.

  5. Masukkan Nama untuk aplikasi Anda. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.

  6. Untuk Jenis akun yang didukung, pilih Akun di direktori organisasi apa pun (Direktori Microsoft Entra apa pun - Multipenyewa) dan akun Microsoft pribadi (misalnya Skype, Xbox). Untuk informasi tentang jenis akun yang berbeda, pilih opsi Bantu saya memilih .

  7. Pilih Daftarkan.

  8. Di bagian Kelola, pilih Autentikasi>Tambahkan platform>Android.

  9. Masukkan Nama Paket proyek Anda berdasarkan jenis sampel yang Anda unduh di atas.

    • Sampel Java - com.azuresamples.msalandroidapp
    • Sampel Kotlin - com.azuresamples.msalandroidkotlinapp
  10. Di bagian Hash tanda tangan dari panel Konfigurasikan aplikasi Android Anda, pilih Membuat Hash Tanda Tangan pengembangan. dan salin perintah KeyTool ke baris perintah Anda.

    • KeyTool.exe diinstal sebagai bagian dari Java Development Kit (JDK). Anda juga harus menginstal alat OpenSSL untuk menjalankan perintah KeyTool. Untuk informasi selengkapnya, lihat dokumentasi Android tentang membuat kunci untuk informasi selengkapnya.
  11. Masukkan Hash tanda tangan yang dihasilkan oleh KeyTool.

  12. Pilih Konfigurasikan dan simpan Konfigurasi MSAL yang muncul di panel konfigurasi Android sehingga Anda dapat memasukkannya saat mengonfigurasi aplikasi nanti.

  13. Pilih Selesai.

Mengonfigurasi aplikasi sampel

  1. Di panel proyek Android Studio, buka app\src\main\res.

  2. Klik kanan res dan pilih Direktori>Baru. Masukkan raw sebagai nama direktori baru dan pilih OK.

  3. Di aplikasi>src>main>res>raw, buka file JSON yang disebut auth_config_single_account.json dan tempelkan Konfigurasi MSAL yang Anda simpan sebelumnya.

    Di bawah URI pengalihan, tempel:

      "account_mode" : "SINGLE",
    

    File config harus menyerupai contoh ini:

    {
      "client_id": "00001111-aaaa-bbbb-3333-cccc4444",
      "authorization_user_agent": "WEBVIEW",
      "redirect_uri": "msauth://com.azuresamples.msalandroidapp/00001111%cccc4444%3D",
      "broker_redirect_uri_registered": true,
      "account_mode": "SINGLE",
      "authorities": [
        {
          "type": "AAD",
          "audience": {
            "type": "AzureADandPersonalMicrosoftAccount",
            "tenant_id": "common"
          }
        }
      ]
    }
    

    Karena tutorial ini hanya menunjukkan cara mengonfigurasi aplikasi dalam mode Akun Tunggal, lihat mode akun tunggal vs. beberapa dan mengonfigurasi aplikasi Anda untuk informasi selengkapnya

Menjalankan contoh aplikasi

Pilih emulator, atau perangkat fisik Anda, dari dropdown perangkat Android Studio yang tersedia dan jalankan aplikasi.

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.

Cuplikan layar aplikasi sampel MSAL memperlihatkan penggunaan satu dan beberapa akun.

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

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

  1. Pilih Dapatkan data grafik secara interaktif untuk meminta kredensial pengguna. Anda akan melihat output dari panggilan ke Microsoft Graph API di bagian bawah layar.
  2. 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.

Informasi Selengkapnya

Baca bagian ini untuk mempelajari lebih lanjut tentang mulai cepat ini.

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:5.1.0'
    implementation 'com.android.volley:volley:1.2.1'
    ...
}

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

Anda juga harus menambahkan referensi ke maven ke bagian repositori allprojects>dari settings.gradle (Module: app) di bawah dependencyResolutionManagement:

dependencyResolutionManagement {
...
maven 
{
 url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'
}
... 
}

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

Dalam SingleAccountModeFragment.javametode , dalam onCreateView() metode, 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);
            }
        });

Masukkan pengguna

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, coba dapatkan 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": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "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" 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": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "authorization_user_agent": "WEBVIEW",
  "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.