Memasukkan pengguna dan memanggil API di contoh aplikasi Android dengan menggunakan autentikasi asli

Berlaku untuk: Penyewa eksternal (pelajari selengkapnya)

Dalam panduan cepat ini, Anda mempelajari cara mengonfigurasi sebuah contoh aplikasi seluler Android untuk mengakses API web ASP.NET Core.

Prasyarat

• Masuk pengguna pada contoh aplikasi mobile Android (Kotlin) dengan menggunakan autentikasi bawaan.
• Di pusat admin Microsoft Entra, daftarkan aplikasi baru untuk API web Anda dengan konfigurasi berikut. Untuk langkah-langkah terperinci, lihat Mendaftarkan aplikasi. Rekam ID Aplikasi (klien) dan ID Direktori (penyewa) untuk digunakan nanti.
  • Nama: ciam-ToDoList-api.
  • Jenis akun yang dapat didukung: Akun di direktori organisasi ini saja (Tenant tunggal)

Mengonfigurasi ruang lingkup API

API perlu menerbitkan minimal satu cakupan, juga disebut Delegated Permission, agar aplikasi klien berhasil mendapatkan token akses bagi pengguna. Untuk menerbitkan cakupan, ikuti langkah-langkah berikut:

1. Dari halaman Pendaftaran aplikasi, pilih aplikasi API yang Anda buat (ciam-ToDoList-api) untuk membuka halaman Gambaran Umum.

2. Di bawah Kelola, pilih Memaparkan API.

3. Di bagian atas halaman, di samping URI ID Aplikasi, pilih tautan Tambahkan untuk menghasilkan URI yang unik untuk aplikasi ini.

4. Terima URI ID Aplikasi yang diusulkan seperti api://{clientId}, dan pilih Simpan. Saat aplikasi web Anda meminta token akses untuk API web, aplikasi web menambahkan URI sebagai awalan untuk setiap cakupan yang Anda tentukan untuk API.

5. Di bawah Cakupan yang ditentukan olehAPI ini, pilih Tambahkan cakupan.

6. Masukkan nilai berikut yang menentukan akses baca ke API, lalu pilih Tambahkan cakupan untuk menyimpan perubahan Anda:

   Harta benda	Nilai
   Nama cakupan	DaftarTugas.Baca
   Siapa yang dapat menyetujui	Hanya admin
   Nama tampilan persetujuan admin	Membaca daftar ToDo milik pengguna menggunakan 'TodoListApi'
   Deskripsi persetujuan admin	Izinkan aplikasi membaca daftar ToDo pengguna menggunakan 'TodoListApi'.
   Negara	Diaktifkan

7. Pilih Tambahkan lingkup lagi, dan masukkan nilai berikut yang menentukan cakupan akses baca dan tulis ke API. Pilih Tambahkan cakupan untuk menyimpan perubahan Anda:

   Harta benda	Nilai
   Nama cakupan	ToDoList.ReadWrite
   Siapa yang dapat menyetujui	Hanya admin
   Nama tampilan persetujuan admin	Membaca dan menulis daftar ToDo milik pengguna menggunakan 'ToDoListApi'
   Deskripsi persetujuan admin	Izinkan aplikasi membaca dan menulis daftar tugas pengguna menggunakan 'ToDoListApi'
   Negara	Diaktifkan

Pelajari selengkapnya tentang prinsip hak istimewa paling sedikit saat menerbitkan izin untuk API web.

Mengonfigurasi peran aplikasi

API perlu menerbitkan minimal satu peran aplikasi untuk aplikasi, yang juga disebut sebagai izin aplikasi , sehingga aplikasi klien dapat mendapatkan token akses atas nama mereka sendiri. Izin aplikasi adalah jenis izin yang harus diterbitkan API ketika mereka ingin memungkinkan aplikasi klien berhasil mengautentikasi sebagai diri mereka sendiri dan tidak perlu memasukkan pengguna. Untuk menerbitkan izin aplikasi, ikuti langkah-langkah berikut:

1. Dari halaman Pendaftaran aplikasi, pilih aplikasi yang Anda buat (seperti ciam-ToDoList-api) untuk membuka halaman Gambaran Umum.

2. Di bawah Kelola, pilih peran Aplikasi .

3. Pilih Buat peran aplikasi, lalu masukkan nilai berikut, lalu pilih Terapkan untuk menyimpan perubahan Anda:

   Harta benda	Nilai
   Nama tampilan	ToDoList.Read.All
   Jenis anggota yang diizinkan	Aplikasi
   Nilai	ToDoList.Read.All
   Deskripsi	Izinkan aplikasi membaca daftar tugas setiap pengguna menggunakan 'TodoListApi'
   Apakah Anda ingin mengaktifkan peran aplikasi ini?	Tetap periksa

4. Pilih Buat peran aplikasi lagi, lalu masukkan nilai berikut untuk peran aplikasi kedua, lalu pilih Terapkan untuk menyimpan perubahan Anda:

   Harta benda	Nilai
   Nama tampilan	DaftarTugas.BacaTulis.Semuanya
   Jenis anggota yang diizinkan	Aplikasi
   Nilai	DaftarTugas.BacaTulis.Semuanya
   Deskripsi	Izinkan aplikasi membaca dan menulis daftar ToDo setiap pengguna menggunakan 'ToDoListApi'
   Apakah Anda ingin mengaktifkan peran aplikasi ini?	Tetap periksa

Pengaturan klaim opsional

Anda dapat menambahkan klaim opsional idtyp untuk membantu web API menentukan apakah token adalah token aplikasi atau token aplikasi + pengguna. Meskipun Anda dapat menggunakan kombinasi scp dan peran klaim untuk tujuan yang sama, menggunakan klaim idtyp adalah cara paling mudah untuk membedakan token aplikasi dan token pengguna + aplikasi. Misalnya, nilai klaim ini adalah aplikasi saat token adalah token hanya untuk aplikasi.

Memberikan izin API ke aplikasi sampel Android

Setelah mendaftarkan aplikasi klien dan API web dan Anda telah mengekspos API dengan membuat cakupan, Anda dapat mengonfigurasi izin klien ke API dengan mengikuti langkah-langkah berikut:

1. Dari halaman Pendaftaran aplikasi, pilih aplikasi yang Anda buat (seperti ciam-client-app) untuk membuka halaman Gambaran Umum.

2. Di bawah Kelola, pilih izin API .

3. Di bawah Izin yang dikonfigurasi, pilih Tambahkan izin.

4. Pilih tab pada API yang digunakan oleh organisasi saya.

5. Dalam daftar API, pilih API seperti ciam-ToDoList-api.

6. Pilih opsi izin yang didelegasikan.

7. Dari daftar izin, pilih ToDoList.Read, ToDoList.ReadWrite (gunakan kotak pencarian jika perlu).

8. Pilih tombol Tambahkan izin.

9. Pada titik ini, Anda telah menetapkan izin dengan benar. Namun, karena penyewa ini adalah penyewa dari pelanggan, pengguna konsumen secara langsung tidak dapat menyetujui izin ini. Untuk mengatasi hal ini, Anda sebagai admin harus menyetujui izin ini atas nama semua pengguna di penyewa:

   1. Pilih Berikan persetujuan admin untuk <nama penyewa Anda>, lalu pilih Ya.

   2. Pilih Refresh, lalu verifikasi bahwa Diberikan untuk <nama penyewa Anda> muncul di bawah Status untuk kedua izin tersebut.

10. Pilih izin ToDoList.Read dan ToDoList.ReadWrite dari daftar Izin yang Dikonnfigurasi, satu per satu, lalu salin URI lengkap izin untuk digunakan nanti. URI izin lengkap terlihat mirip dengan api://{clientId}/{ToDoList.Read} atau api://{clientId}/{ToDoList.ReadWrite}.

Mengkloning atau mengunduh sampel API web

Untuk mendapatkan aplikasi sampel, Anda dapat mengkloningnya dari GitHub atau mengunduhnya sebagai file .zip.

• Untuk mengkloning sampel, buka prompt perintah dan navigasi ke tempat Anda ingin membuat proyek, dan masukkan perintah berikut:

  git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git
  

• Unduh file .zip. Ekstrak ke jalur file di mana panjang nama kurang dari 260 karakter.

Mengonfigurasi dan menjalankan contoh API web

1. Di editor kode Anda, buka file 2-Authorization/1-call-own-api-aspnet-core-mvc/ToDoListAPI/appsettings.json.

2. Temukan pengganti sementara:

   • Gantilah Enter_the_Application_Id_Here dengan ID Aplikasi (klien) dari API web yang telah Anda salin sebelumnya.
   • Enter_the_Tenant_Id_Here dan ganti dengan ID Direktori (penyewa) yang Anda salin sebelumnya.
   • Enter_the_Tenant_Subdomain_Here kemudian gantilah dengan subdomain Direktori (penyewa). Misalnya, jika domain utama penyewa Anda contoso.onmicrosoft.com, gunakan contoso. Jika Anda tidak memiliki nama penyewa, pelajari cara membaca detail penyewa Anda.

Anda perlu menghosting API web Anda untuk aplikasi sampel Android untuk memanggilnya. Ikuti Quickstart : Terapkan aplikasi web ASP.NET guna menyebarkan API web Anda.

Mengonfigurasi contoh aplikasi seluler Android untuk memanggil API web

Sampel ini memungkinkan Anda mengonfigurasi beberapa titik akhir URL API Web dan serangkaian cakupan. Dalam hal ini, Anda hanya mengonfigurasi satu titik akhir URL API Web dan cakupan terkaitnya.

1. Di Android Studio Anda, buka file /app/src/main/java/com/azuresamples/msalnativeauthandroidkotlinsampleapp/AccessApiFragment.kt.

2. Temukan properti bernama WEB_API_URL_1 dan atur URL ke API web Anda.

   private const val WEB_API_URL_1 = "" // Developers should set the respective URL of their web API here
   

3. Temukan properti bernama scopesForAPI1 dan atur cakupan yang direkam di Berikan izin API ke aplikasi sampel Android.

   private val scopesForAPI1 = listOf<String>() // Developers should set the respective scopes of their web API here. For example, private val scopes = listOf<String>("api://{clientId}/{ToDoList.Read}", "api://{clientId}/{ToDoList.ReadWrite}")
   

Menjalankan aplikasi sampel Android dan memanggil API web

Untuk membuat dan menjalankan aplikasi Anda, ikuti langkah-langkah berikut:

1. Di toolbar, pilih aplikasi Anda dari menu konfigurasi eksekusi.

2. Di menu perangkat target, pilih perangkat tempat Anda ingin menjalankan aplikasi.

   Jika Anda tidak memiliki perangkat apa pun yang dikonfigurasi, Anda perlu membuat Perangkat Virtual Android untuk menggunakan Android Emulator atau menyambungkan perangkat fisik.

3. Pilih tombol Jalankan. Aplikasi terbuka di layar email dan kode akses satu kali.

4. Pilih tab API untuk menguji panggilan API. Panggilan yang berhasil ke API web mengembalikan HTTP 200, sementara HTTP 403 menandakan akses yang tidak sah.

Langkah berikutnya

Tutorial: Siapkan aplikasi Android Anda untuk autentikasi bawaan.