Mulai cepat: Memanggil API web yang dilindungi oleh platform identitas Microsoft

Berlaku untuk: Penyewa Tenaga Kerja Penyewa eksternal (pelajari selengkapnya)

Dalam mulai cepat ini, Anda menggunakan contoh aplikasi web untuk menunjukkan kepada Anda cara melindungi API web ASP.NET dengan menggunakan platform identitas Microsoft. Sampel menggunakan Microsoft Authentication Library (MSAL) untuk menangani autentikasi dan otorisasi.

Prasyarat

• Sebuah akun Azure dengan langganan aktif. Buat akun secara gratis.
• Daftarkan aplikasi baru di pusat admin Microsoft Entra dan rekam pengidentifikasinya dari halaman Gambaran Umum aplikasi. Untuk informasi selengkapnya, lihat Mendaftarkan aplikasi.
  • Nama: NewWebAPI1
  • Jenis akun yang didukung: Akun dalam direktori organisasi ini saja (Penyewa tunggal)

ASP.NET

• Visual Studio 2022. Unduh Visual Studio secara gratis.

ASP.NET Core

• Visual Studio Code

Memperkenalkan API

Setelah API terdaftar, Anda dapat mengonfigurasi izinnya dengan menentukan cakupan yang diekspos API ke aplikasi klien. Aplikasi klien meminta izin untuk melakukan operasi dengan meneruskan token akses bersama dengan permintaannya ke API web yang dilindungi. API web kemudian melakukan operasi yang diminta hanya jika token akses yang diterimanya berisi cakupan yang diperlukan.

ASP.NET

1. Di bawah Kelola, pilih Ekspos API>Tambahkan cakupan. Terima URI ID Aplikasi yang diusulkan (api://{clientId}) dengan memilih Simpan dan lanjutkan, lalu masukkan informasi berikut:

   1. Untuk Nama cakupan, masukkan access_as_user.
   2. Untuk Siapa yang dapat menyetujui, pastikan bahwa opsi Admin dan pengguna dipilih.
   3. Dalam kotak Nama tampilan persetujuan admin , masukkan Access TodoListService as a user.
   4. Dalam kotak Deskripsi persetujuan admin , masukkan Accesses the TodoListService web API as a user.
   5. Dalam kotak Nama tampilan persetujuan pengguna , masukkan Access TodoListService as a user.
   6. Dalam kotak Deskripsi persetujuan pengguna , masukkan Accesses the TodoListService web API as a user.
   7. Untuk Status, tetap Aktifkan.

2. Pilih Tambahkan cakupan.

ASP.NET Core

Menambahkan izin yang didelegasikan (cakupan)

API perlu menerbitkan minimal satu cakupan, juga disebut Izin Yang Didelegasikan, agar aplikasi klien mendapatkan token akses bagi pengguna dengan sukses. Untuk menerbitkan cakupan, ikuti langkah-langkah di bawah ini:

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

2. Di bawah Kelola, pilih Ekspos 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 oleh API 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 Ruang Lingkup	ToDoList.Read
   Siapa yang dapat menyetujui	Hanya admin
   Nama tampilan persetujuan admin	Baca daftar ToDo pengguna menggunakan 'TodoListApi'
   Deskripsi persetujuan admin	Izinkan aplikasi membaca daftar ToDo pengguna menggunakan 'TodoListApi'.
   Negara	Diaktifkan

7. Pilih Tambahkan cakupan 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 Ruang Lingkup	ToDoList.ReadWrite
   Siapa yang dapat menyetujui	Hanya untuk admin
   Nama tampilan persetujuan admin	Membaca dan menulis daftar ToDo pengguna menggunakan 'ToDoListApi'
   Deskripsi persetujuan admin	Izinkan aplikasi membaca dan menulis daftar ToDo pengguna menggunakan 'ToDoListApi'
   Negara	Diaktifkan

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

Menambahkan izin aplikasi (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 Umumnya .

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 ToDo 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	ToDoList.ReadWrite.All
   Jenis anggota yang diizinkan	Aplikasi
   Nilai	ToDoList.ReadWrite.All
   Deskripsi	Izinkan aplikasi membaca dan menulis daftar ToDo setiap pengguna menggunakan 'ToDoListApi'
   Apakah Anda ingin mengaktifkan peran aplikasi ini?	Tetap periksa

Mengkloning atau mengunduh aplikasi sampel

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

ASP.NET

git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

• Unduh sebagai file ZIP.

Petunjuk / Saran

Untuk menghindari kesalahan yang disebabkan oleh keterbatasan panjang jalur di Windows, kami sarankan mengekstrak arsip atau mengkloning repositori ke direktori di dekat akar drive Anda.

ASP.NET Core

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 aplikasi sampel

Konfigurasikan sampel kode agar sesuai dengan API web terdaftar.

ASP.NET

1. Buka solusi di Visual Studio, lalu buka file appsettings.json di bawah akar proyek TodoListService.

2. Ganti nilai Enter_the_Application_Id_here dengan nilai ID Klien (ID Aplikasi) dari aplikasi yang Anda daftarkan di portal Pendaftaran Aplikasi baik pada properti ClientID maupun Audience.

Menambahkan cakupan baru ke file app.config

Untuk menambahkan cakupan baru ke file app.config TodoListClient, ikuti langkah-langkah berikut:

1. Di folder akar proyek TodoListClient, buka file app.config .

2. Tempelkan ID Aplikasi dari aplikasi yang Anda daftarkan untuk proyek TodoListService Anda di parameter TodoListServiceScope, menggantikan string {Enter the Application ID of your TodoListService from the app registration portal}.

Nota

Pastikan ID Aplikasi menggunakan format berikut: api://{TodoListService-Application-ID}/access_as_user (di mana {TodoListService-Application-ID} adalah GUID yang mewakili ID Aplikasi untuk aplikasi TodoListService Anda).

Mendaftarkan aplikasi web (TodoListClient)

Daftarkan aplikasi TodoListClient Anda di Pendaftaran aplikasi di pusat admin Microsoft Entra, lalu konfigurasikan kode dalam proyek TodoListClient. Jika klien dan server dianggap sebagai aplikasi yang sama, Anda dapat menggunakan kembali aplikasi yang terdaftar di langkah 2. Gunakan aplikasi yang sama jika Anda ingin pengguna masuk dengan akun Microsoft pribadi.

Mendaftarkan aplikasi

Untuk mendaftarkan aplikasi TodoListClient, ikuti langkah-langkah berikut:

1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.

2. Telusuri pendaftaranAplikasiEntra ID> dan pilih Pendaftaran baru.

3. Pilih Pendaftaran baru.

4. Saat halaman Daftarkan aplikasi terbuka, masukkan informasi pendaftaran aplikasi Anda:

   1. Di bagian Nama , masukkan nama aplikasi yang bermakna yang akan ditampilkan kepada pengguna aplikasi (misalnya, NativeClient-DotNet-TodoListClient).
   2. Untuk Jenis akun yang didukung, pilih Akun di direktori organisasi apa pun.
   3. Pilih Daftar untuk membuat aplikasi.

   Nota

   Dalam file app.config proyek TodoListClient, nilai ida:Tenant default diatur ke common. Nilai yang mungkin adalah:

   • common: Anda dapat masuk dengan menggunakan akun kerja atau sekolah atau akun Microsoft pribadi (karena Anda memilih Akun di direktori organisasi mana pun di langkah sebelumnya).
   • organizations: Anda dapat masuk dengan menggunakan akun kerja atau sekolah.
   • consumers: Anda hanya dapat masuk dengan menggunakan akun pribadi Microsoft.

5. Pada halaman Gambaran Umum aplikasi, pilih Autentikasi, lalu selesaikan langkah-langkah ini untuk menambahkan platform:

   1. Di bawah Konfigurasi platform, pilih tombol Tambahkan platform .
   2. Untuk Aplikasi seluler dan desktop, pilih Aplikasi seluler dan desktop.
   3. Untuk URI Pengalihan, pilih kotak https://login.microsoftonline.com/common/oauth2/nativeclient centang.
   4. Pilih Konfigurasikan.

6. Pilih izin API , lalu selesaikan langkah-langkah ini untuk menambahkan izin:

   1. Pilih tombol Tambahkan izin .
   2. Pilih tab API Saya .
   3. Dalam daftar API, pilih AppModelv2-NativeClient-DotNet-TodoListService API atau nama yang Anda masukkan untuk API web.
   4. Pilih kotak centang izin access_as_user jika belum dipilih. Gunakan kotak Pencarian jika perlu.
   5. Pilih tombol Tambahkan izin .

Konfigurasikan proyek Anda

Konfigurasikan proyek TodoListClient Anda dengan menambahkan ID Aplikasi ke file app.config .

1. Di portal Pendaftaran aplikasi, pada halaman Gambaran Umum, salin nilai ID Aplikasi (klien).

2. Dari folder akar proyek TodoListClient, buka file app.config , lalu tempelkan nilai ID Aplikasi dalam ida:ClientId parameter .

ASP.NET Core

1. Di IDE Anda, buka folder proyek, ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI, yang berisi sampel.

2. Buka file appsettings.json, yang berisi cuplikan kode berikut:

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   Temukan nilai berikut:

   • ClientId - Pengidentifikasi aplikasi, juga disebut sebagai klien. value Ganti teks dalam tanda kutip dengan ID Aplikasi (klien) yang direkam sebelumnya dari halaman Gambaran Umum aplikasi terdaftar.
   • TenantId - Pengidentifikasi penyewa tempat aplikasi terdaftar. value Ganti teks dalam tanda kutip dengan nilai ID Direktori (penyewa) yang direkam sebelumnya dari halaman Gambaran Umum aplikasi terdaftar.
   • Instance - Ini menentukan direktori tempat Microsoft Authentication Library (MSAL) dapat meminta token. Ganti Enter_the_Authority_URL_Here dengan salah satu nilai berikut tergantung pada skenario Anda:
     • Untuk penyewa tenaga kerja, gunakan https://login.microsoftonline.com/ sebagai instance.
     • Untuk penyewa eksternal, tambahkan URL otoritas dalam bentuk https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

Jalankan aplikasi sampel

ASP.NET

Mulai kedua proyek. Untuk pengguna Visual Studio;

1. Klik kanan pada solusi Visual Studio dan pilih properti

2. Di Properti Umum, pilih Proyek Startup lalu Beberapa proyek startup.

3. Untuk kedua proyek, pilih Mulai sebagai tindakan

4. Pastikan layanan TodoListService dimulai terlebih dahulu dengan memindahkannya ke posisi pertama dalam daftar, menggunakan panah atas.

Masuk untuk menjalankan proyek TodoListClient Anda.

1. Tekan F5 untuk memulai proyek. Halaman layanan serta aplikasi desktop terbuka.

2. Di TodoListClient, di kanan atas, pilih Masuk, lalu masuk dengan kredensial yang sama dengan yang Anda gunakan untuk mendaftarkan aplikasi Anda, atau masuk sebagai pengguna di direktori yang sama.

   Jika Anda masuk untuk pertama kalinya, Anda mungkin diminta untuk menyetujui API web TodoListService.

   Untuk membantu Anda mengakses API web TodoListService serta memanipulasi daftar Tugas, proses masuk juga meminta token akses untuk ruang lingkup access_as_user.

Pra-otorisasi aplikasi klien Anda

Anda dapat mengizinkan pengguna dari direktori lain mengakses API web Anda dengan melakukan pra-otorisasi aplikasi klien untuk mengakses API web Anda. Anda melakukan ini dengan menambahkan ID Aplikasi dari aplikasi klien ke daftar aplikasi yang telah diotorisasi untuk API web Anda. Dengan menambahkan klien yang diotorisasi sebelumnya, Anda mengizinkan pengguna untuk mengakses API web Anda tanpa harus memberikan persetujuan.

1. Di dalam portal Pendaftaran aplikasi , buka properti aplikasi TodoListService Anda.
2. Di bagian Mengekspos API , di bawah Aplikasi klien resmi, pilih Tambahkan aplikasi klien.
3. Dalam kotak ID Klien , tempelkan ID Aplikasi dari aplikasi TodoListClient.
4. Di bagian Cakupan resmi , pilih cakupan untuk api://<Application ID>/access_as_user API web.
5. Pilih Tambahkan aplikasi.

Jalankan proyek Anda

1. Tekan F5 untuk menjalankan proyek Anda. Aplikasi TodoListClient Anda terbuka.
2. Di kanan atas, pilih Masuk, lalu masuk dengan menggunakan akun Microsoft pribadi, seperti akun live.com atau hotmail.com , atau akun kantor atau sekolah.

Opsional: Membatasi akses masuk ke pengguna tertentu

Secara default, akun pribadi apa pun, seperti akun outlook.com atau live.com , atau akun kantor atau sekolah dari organisasi yang terintegrasi dengan ID Microsoft Entra dapat meminta token dan mengakses API web Anda.

Untuk menentukan siapa yang dapat masuk ke aplikasi Anda, dengan mengubah TenantId properti dalam file appsettings.json .

ASP.NET Core

1. Jalankan perintah berikut dari akar direktori proyek API web Anda untuk memulai aplikasi:

   dotnet run
   

2. Jika semuanya berfungsi dengan benar, terminal Anda menampilkan output yang mirip dengan yang berikut ini:

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   Rekam nomor port di URL https://localhost:{port}.

3. Untuk memverifikasi bahwa titik akhir dilindungi, perbarui URL dasar dalam perintah cURL berikut agar sesuai dengan yang Anda terima di langkah sebelumnya, lalu jalankan perintah:

   curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   Respons yang diharapkan adalah 401 Tidak Sah.

Langkah selanjutnya

Pelajari cara melindungi API web ASP.NET Core dengan platform identitas Microsoft.

Tutorial: Membangun dan mengamankan API web ASP.NET Core dengan platform identitas Microsoft