Membuat REST API untuk peristiwa mulai penerbitan token di Azure Functions

Artikel ini menjelaskan cara membuat REST API dengan peristiwa mulai penerbitan token menggunakan Azure Functions di portal Azure. Anda membuat aplikasi Azure Function dan fungsi pemicu HTTP yang dapat mengembalikan klaim tambahan untuk token Anda.

Prasyarat

• Pemahaman dasar tentang konsep yang tercakup dalam Gambaran umum ekstensi autentikasi kustom.
• Langganan Azure dengan kemampuan untuk membuat Azure Functions. Jika Anda tidak memiliki akun Azure yang sudah ada, daftar untuk uji coba gratis atau gunakan manfaat Langganan Visual Studio saat Membuat akun.
• Penyewa ID Microsoft Entra. Anda dapat menggunakan pelanggan atau penyewa tenaga kerja untuk panduan cara ini.

Artikel ini menjelaskan cara membuat REST API untuk peristiwa mulai penerbitan token menggunakan pustaka NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents dan menyiapkannya untuk autentikasi. Anda akan membuat fungsi pemicu HTTP di Visual Studio atau Visual Studio Code, mengonfigurasinya untuk autentikasi, dan menyebarkannya ke portal Azure, tempat fungsi tersebut dapat diakses melalui Azure Functions.

Prasyarat

• Pemahaman dasar tentang konsep yang tercakup dalam Gambaran umum ekstensi autentikasi kustom.
• Langganan Azure dengan kemampuan untuk membuat Azure Functions. Jika Anda tidak memiliki akun Azure yang sudah ada, daftar untuk uji coba gratis atau gunakan manfaat Langganan Visual Studio saat Membuat akun.
• Penyewa ID Microsoft Entra. Anda dapat menggunakan pelanggan atau penyewa tenaga kerja untuk panduan cara ini.
• Salah satu ID Dan konfigurasi berikut:
  • Visual Studio dengan beban kerja Azure Development untuk Visual Studio dikonfigurasi.
  • Visual Studio Code, dengan ekstensi Azure Functions diaktifkan.

Catatan

Pustaka NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents saat ini dalam pratinjau. Langkah-langkah dalam artikel ini dapat berubah. Untuk implementasi ketersediaan umum penerapan peristiwa mulai penerbitan token, Anda dapat melakukannya menggunakan portal Azure.

Membuat aplikasi Azure Function

Di portal Azure, buat aplikasi Azure Function dan sumber daya terkait, sebelum terus membuat fungsi pemicu HTTP.

1. Masuk ke portal Azure setidaknya sebagai Administrator Aplikasi dan Administrator Autentikasi.

2. Pada menu portal Microsoft Azure atau halaman Beranda, pilih Buat sumber daya.

3. Cari dan pilih Aplikasi Fungsi dan pilih Buat.

4. Pada halaman Dasar , buat aplikasi fungsi menggunakan pengaturan seperti yang ditentukan dalam tabel berikut ini:

   Pengaturan	Nilai yang disarankan	Deskripsi
   Langganan	Langganan Anda	Langganan tempat aplikasi fungsi baru akan dibuat.
   Grup Sumber Daya	myResourceGroup	Pilih dan grup sumber daya yang sudah ada, atau beri nama untuk grup baru tempat Anda akan membuat aplikasi fungsi.
   Nama Aplikasi Fungsi	Nama unik secara global	Nama yang mengidentifikasi aplikasi fungsi baru. Karakter yang valid a-z (peka huruf besar dan kecil), 0-9, dan -.
   Menyebarkan kode atau gambar kontainer	Kode	Opsi untuk menerbitkan file kode atau sebuah kontainer Docker. Untuk tutorial ini, pilih Kode.
   Tumpukan runtime	.NET	Bahasa pemrograman pilihan Anda. Untuk tutorial ini, pilih .NET.
   Versi	6 (LTS) Dalam proses	Versi runtime .NET. Dalam proses menandakan bahwa Anda dapat membuat dan memodifikasi fungsi di portal, yang direkomendasikan untuk panduan ini
   Wilayah	Wilayah pilihan	Pilih wilayah yang ada di dekat Anda atau di dekat layanan lain yang dapat diakses oleh fungsi Anda.
   Sistem Operasi	Windows	Sistem operasi telah dipilih sebelumnya untuk Anda berdasarkan pilihan tumpukan runtime Anda.
   Jenis paket	Konsumsi (Tanpa Server)	Paket hosting yang menentukan cara sumber daya dialokasikan ke aplikasi fungsi Anda.

5. Pilih Tinjau + buat untuk meninjau pilihan konfigurasi aplikasi lalu pilih Buat. Penyebaran membutuhkan waktu beberapa menit.

6. Setelah disebarkan, pilih Buka sumber daya untuk melihat aplikasi fungsi baru Anda.

Membuat fungsi pemicu HTTP

Setelah aplikasi Azure Function dibuat, buat fungsi pemicu HTTP dalam aplikasi. Pemicu HTTP memungkinkan Anda memanggil fungsi dengan permintaan HTTP dan dirujuk oleh ekstensi autentikasi kustom Microsoft Entra Anda.

1. Dalam halaman Gambaran Umum aplikasi fungsi Anda, pilih panel Fungsi dan pilih Buat fungsi di bawah Buat di portal Azure.
2. Di jendela Buat Fungsi , biarkan properti Lingkungan pengembangan sebagai Kembangkan di portal. Di bawah Templat, pilih pemicu HTTP.
3. Di bawah Detail templat, masukkan CustomAuthenticationExtensionsAPI untuk properti Fungsi Baru.
4. Untuk tingkat Otorisasi, pilih Fungsi.
5. Pilih Buat.

Mengedit fungsi

Kode membaca objek JSON masuk dan MICROSOFT Entra ID mengirimkan objek JSON ke API Anda. Dalam contoh ini, ia membaca nilai ID korelasi. Kemudian, kode mengembalikan kumpulan klaim yang dikustomisasi, termasuk asli CorrelationId, ApiVersion fungsi Azure Anda, DateOfBirth dan CustomRoles yang dikembalikan ke ID Microsoft Entra.

1. Dari menu, di bawah Pengembang, pilih Kode + Uji.

2. Ganti seluruh kode dengan cuplikan berikut, lalu pilih Simpan.

   #r "Newtonsoft.Json"
   using System.Net;
   using Microsoft.AspNetCore.Mvc;
   using Microsoft.Extensions.Primitives;
   using Newtonsoft.Json;
   public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
   {
       log.LogInformation("C# HTTP trigger function processed a request.");
       string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
       dynamic data = JsonConvert.DeserializeObject(requestBody);
   
       // Read the correlation ID from the Microsoft Entra request    
       string correlationId = data?.data.authenticationContext.correlationId;
   
       // Claims to return to Microsoft Entra
       ResponseContent r = new ResponseContent();
       r.data.actions[0].claims.CorrelationId = correlationId;
       r.data.actions[0].claims.ApiVersion = "1.0.0";
       r.data.actions[0].claims.DateOfBirth = "01/01/2000";
       r.data.actions[0].claims.CustomRoles.Add("Writer");
       r.data.actions[0].claims.CustomRoles.Add("Editor");
       return new OkObjectResult(r);
   }
   public class ResponseContent{
       [JsonProperty("data")]
       public Data data { get; set; }
       public ResponseContent()
       {
           data = new Data();
       }
   }
   public class Data{
       [JsonProperty("@odata.type")]
       public string odatatype { get; set; }
       public List<Action> actions { get; set; }
       public Data()
       {
           odatatype = "microsoft.graph.onTokenIssuanceStartResponseData";
           actions = new List<Action>();
           actions.Add(new Action());
       }
   }
   public class Action{
       [JsonProperty("@odata.type")]
       public string odatatype { get; set; }
       public Claims claims { get; set; }
       public Action()
       {
           odatatype = "microsoft.graph.tokenIssuanceStart.provideClaimsForToken";
           claims = new Claims();
       }
   }
   public class Claims{
       [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
       public string CorrelationId { get; set; }
       [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
       public string DateOfBirth { get; set; }
       public string ApiVersion { get; set; }
       public List<string> CustomRoles { get; set; }
       public Claims()
       {
           CustomRoles = new List<string>();
       }
   }
   

3. Dari menu atas, pilih Dapatkan Url Fungsi, dan salin nilai URL . URL fungsi ini dapat digunakan saat menyiapkan ekstensi autentikasi kustom.

Membuat dan membangun aplikasi Azure Function

Dalam langkah ini, Anda membuat API fungsi pemicu HTTP menggunakan IDE Anda, menginstal paket NuGet yang diperlukan dan menyalin dalam kode sampel. Anda membangun proyek dan menjalankan fungsi untuk mengekstrak URL fungsi lokal.

Buat aplikasi

Untuk membuat aplikasi Azure Function, ikuti langkah-langkah berikut:

Visual Studio

1. Buka Visual Studio, lalu pilih Buat proyek baru.
2. Cari dan pilih Azure Functions, lalu pilih Berikutnya.
3. Beri nama proyek, seperti AuthEventsTrigger. Ada baiknya mencocokkan nama solusi dengan nama proyek.
4. Pilih lokasi untuk proyek. Pilih Selanjutnya.
5. Pilih .NET 6.0 (Dukungan Jangka Panjang) sebagai kerangka kerja target.
6. Pilih Pemicu Http sebagai jenis Fungsi , dan tingkat Otorisasi tersebut diatur ke Fungsi. Pilih Buat.
7. Di Penjelajah Solusi, ganti nama file Function1.cs menjadi AuthEventsTrigger.cs, dan terima saran perubahan nama.

Visual Studio Code

1. Buka Visual Studio Code.

2. Pilih ikon Folder Baru di jendela Explorer, dan buat folder baru untuk proyek Anda, misalnya AuthEventsTrigger.

3. Pilih ikon ekstensi Azure di sisi kiri layar. Masuk ke akun Azure Anda jika Anda belum melakukannya.

4. Di bawah bilah Ruang Kerja, pilih ikon >Azure Functions Buat Proyek Baru.

   

5. Di bilah atas, pilih lokasi untuk membuat proyek.

6. Pilih C# sebagai bahasa, dan .NET 6.0 LTS sebagai runtime .NET.

7. Pilih pemicu HTTP sebagai templat.

8. Berikan nama untuk proyek, seperti AuthEventsTrigger.

9. Terima Company.Function sebagai namespace layanan, dengan AccessRights diatur ke Function.

Menginstal paket NuGet dan membangun proyek

Setelah membuat proyek, Anda harus menginstal paket NuGet yang diperlukan dan membangun proyek.

Visual Studio

1. Di menu atas Visual Studio, pilih Proyek, lalu Kelola paket NuGet.
2. Pilih tab Telusuri , lalu cari dan pilih Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents di panel kanan. Pilih Instal.
3. Terapkan dan terima perubahan dalam popup yang muncul.

Visual Studio Code

1. Buka Terminal di Visual Studio Code, dan navigasikan ke folder proyek.

2. Masukkan perintah berikut ke konsol untuk menginstal paket NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents .

   dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents
   

Menambahkan kode sampel

API fungsi adalah sumber klaim tambahan untuk token Anda. Untuk tujuan artikel ini, kami melakukan hardcoding nilai untuk aplikasi sampel. Dalam produksi, Anda dapat mengambil informasi tentang pengguna dari penyimpanan data eksternal. Lihat Kelas WebJobsAuthenticationEventsContext untuk properti yang ada.

Dalam file AuthEventsTrigger.cs Anda, ganti seluruh konten file dengan kode berikut:

using System;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;

namespace AuthEventsTrigger
{
    public static class AuthEventsTrigger
    {
        [FunctionName("onTokenIssuanceStart")]
        public static WebJobsAuthenticationEventResponse Run(
            [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log)
        {
            try
            {
                // Checks if the request is successful and did the token validation pass
                if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful)
                {
                    // Fetches information about the user from external data store
                    // Add new claims to the token's response
                    request.Response.Actions.Add(
                        new WebJobsProvideClaimsForToken(
                            new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"),
                            new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"),
                            new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"),
                            new WebJobsAuthenticationEventsTokenClaim(
                                "correlationId", 
                                request.Data.AuthenticationContext.CorrelationId.ToString())));
                }
                else
                {
                    // If the request fails, such as in token validation, output the failed request status, 
                    // such as in token validation or response validation.
                    log.LogInformation(request.StatusMessage);
                }
                return request.Completed();
            }
            catch (Exception ex) 
            { 
                return request.Failed(ex);
            }
        }
    }
}

Membangun dan menjalankan proyek secara lokal

Proyek telah dibuat, dan kode sampel telah ditambahkan. Dengan menggunakan IDE Anda, kita perlu membangun dan menjalankan proyek secara lokal untuk mengekstrak URL fungsi lokal.

Visual Studio

1. Navigasi ke Bangun di menu atas, dan pilih Bangun Solusi.
2. Tekan F5 atau pilih AuthEventsTrigger dari menu atas untuk menjalankan fungsi.
3. Salin url Fungsi dari terminal yang muncul saat menjalankan fungsi. Ini dapat digunakan saat menyiapkan ekstensi autentikasi kustom.

Visual Studio Code

1. Di menu atas, pilih Jalankan>Mulai Penelusuran Kesalahan atau tekan F5 untuk menjalankan fungsi.
2. Di terminal, salin url Fungsi yang muncul. Ini dapat digunakan saat menyiapkan ekstensi autentikasi kustom.

Jalankan fungsi secara lokal (disarankan)

Sebaiknya uji fungsi secara lokal sebelum menyebarkannya ke Azure. Kita dapat menggunakan isi JSON dummy yang meniru permintaan yang dikirim id Microsoft Entra ke REST API Anda. Gunakan alat pengujian API pilihan Anda untuk memanggil fungsi secara langsung.

1. Di IDE Anda, buka local.settings.json dan ganti kode dengan JSON berikut. Kita dapat mengatur "AuthenticationEvents__BypassTokenValidation" ke true untuk tujuan pengujian lokal.

   {
     "IsEncrypted": false,
     "Values": {
       "AzureWebJobsStorage": "",
       "AzureWebJobsSecretStorageType": "files",
       "FUNCTIONS_WORKER_RUNTIME": "dotnet",
       "AuthenticationEvents__BypassTokenValidation" : true
     }
   }
   

2. Menggunakan alat pengujian API pilihan Anda, buat permintaan HTTP baru dan atur metode HTTP ke POST.

3. Gunakan isi JSON berikut yang meniru permintaan yang dikirim microsoft Entra ID ke REST API Anda.

   {
       "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
       "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
           "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
           "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
           "authenticationContext": {
               "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                   "mail": "casey@contoso.com",
                   "onPremisesSamAccountName": "Casey Jensen",
                   "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                   "onPremisesUserPrincipalName": "Casey Jensen",
                   "preferredLanguage": "en-us",
                   "surname": "Jensen",
                   "userPrincipalName": "casey@contoso.com",
                   "userType": "Member"
               }
           }
       }
   }
   
   

4. Pilih Kirim, dan Anda akan menerima respons JSON yang mirip dengan yang berikut ini:

   {
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                   "claims": {
                       "customClaim1": "customClaimValue1",
                       "customClaim2": [
                           "customClaimString1",
                           "customClaimString2" 
                       ]
                   }
               }
   
           ]
       }
   }
   

Menyebarkan fungsi dan menerbitkan ke Azure

Fungsi ini perlu disebarkan ke Azure menggunakan IDE kami. Periksa apakah Anda masuk dengan benar ke akun Azure Anda sehingga fungsi dapat diterbitkan.

Visual Studio

1. Di Penjelajah Solusi, klik kanan proyek dan pilih Terbitkan.

2. Di Target, pilih Azure, lalu pilih Berikutnya.

3. Pilih Aplikasi Fungsi Azure (Windows) untuk Target Tertentu, pilih Aplikasi Fungsi Azure (Windows), lalu pilih Berikutnya.

4. Dalam instans Fungsi, gunakan menu dropdown Nama langganan untuk memilih langganan tempat aplikasi fungsi baru akan dibuat.

5. Pilih tempat Anda ingin menerbitkan aplikasi fungsi baru, dan pilih Buat Baru.

6. Pada halaman Aplikasi Fungsi (Windows), gunakan pengaturan aplikasi fungsi seperti yang ditentukan dalam tabel berikut, lalu pilih Buat.

   Pengaturan	Nilai yang disarankan	Deskripsi
   Nama	Nama unik secara global	Nama yang mengidentifikasi aplikasi fungsi baru. Karakter yang valid a-z (peka huruf besar dan kecil), 0-9, dan -.
   Langganan	Langganan Anda	Langganan tempat aplikasi fungsi baru dibuat.
   Grup Sumber Daya	myResourceGroup	Pilih grup sumber daya yang sudah ada, atau beri nama yang baru tempat Anda akan membuat aplikasi fungsi.
   Jenis paket	Konsumsi (Tanpa Server)	Paket hosting yang menentukan cara sumber daya dialokasikan ke aplikasi fungsi Anda.
   Location	Wilayah pilihan	Pilih wilayah yang ada di dekat Anda atau di dekat layanan lain yang dapat diakses oleh fungsi Anda.
   Azure Storage	Akun penyimpanan Anda	Akun Azure Storage diperlukan oleh runtime Fungsi. Pilih Baru untuk mengonfigurasi akun penyimpanan serba guna.
   Application Insights	Default	Fitur Azure Monitor. Ini dipilih secara otomatis, pilih yang ingin Anda gunakan atau konfigurasikan yang baru.

7. Tunggu beberapa saat agar aplikasi fungsi Anda disebarkan. Setelah jendela ditutup, pilih Selesai.

8. Panel Terbitkan baru terbuka. Di bagian atas, pilih Terbitkan. Tunggu beberapa menit agar aplikasi fungsi Anda disebarkan dan muncul di portal Azure.

Visual Studio Code

1. Pilih ikon ekstensi Azure. Di Sumber Daya, pilih + ikon untuk Membuat sumber daya.
2. Pilih Buat Aplikasi Fungsi di Azure. Gunakan pengaturan berikut untuk menyiapkan aplikasi fungsi Anda.
3. Beri nama aplikasi fungsi, seperti AuthEventsTriggerNuGet, dan tekan Enter.
4. Pilih tumpukan runtime .NET 6 (LTS) Dalam Proses.
5. Pilih lokasi untuk aplikasi fungsi, seperti US Timur.
6. Tunggu beberapa menit agar aplikasi fungsi Anda disebarkan dan muncul di portal Azure.

Mengonfigurasi autentikasi untuk Azure Function Anda

Ada tiga cara untuk menyiapkan autentikasi untuk Azure Function Anda:

• Menyiapkan autentikasi di portal Azure menggunakan variabel lingkungan (disarankan)
• Menyiapkan autentikasi dalam kode Anda menggunakan WebJobsAuthenticationEventsTriggerAttribute
• Autentikasi dan otorisasi layanan Azure App

Secara default, kode telah disiapkan untuk autentikasi di portal Azure menggunakan variabel lingkungan. Gunakan tab di bawah ini untuk memilih metode penerapan variabel lingkungan pilihan Anda, atau sebagai alternatif, lihat autentikasi dan otorisasi layanan Azure App bawaan. Untuk menyiapkan variabel lingkungan, gunakan nilai berikut:

Nama	Nilai
AuthenticationEvents__AudienceAppId	ID aplikasi ekstensi autentikasi kustom yang disiapkan di Mengonfigurasi penyedia klaim kustom untuk peristiwa penerbitan token
AuthenticationEvents__AuthorityUrl	• Penyewa tenaga kerja https://login.microsoftonline.com/<tenantID> • Penyewa eksternal https://<mydomain>.ciamlogin.com/<tenantID>
AuthenticationEvents__AuthorizedPartyAppId	99045fe1-7639-4a75-9d4a-577b6ca3810f atau pihak yang berwenang lainnya

Menyiapkan autentikasi di portal Azure

Menyiapkan autentikasi di portal Azure menggunakan variabel lingkungan

1. Masuk ke portal Azure setidaknya sebagai Administrator Aplikasi atau Administrator Autentikasi.
2. Navigasi ke aplikasi fungsi yang Anda buat, dan di bawah Pengaturan, pilih Konfigurasi.
3. Di bawah Pengaturan aplikasi, pilih Pengaturan aplikasi baru dan tambahkan variabel lingkungan dari tabel dan nilai terkaitnya.
4. Pilih Simpan untuk menyimpan pengaturan aplikasi.

Menyiapkan autentikasi dalam kode Anda

Menyiapkan autentikasi dalam kode Anda menggunakan WebJobsAuthenticationEventsTriggerAttribute

1. Buka file AuthEventsTrigger.cs di IDE Anda.
2. Ubah sertakan WebJobsAuthenticationEventsTriggerAttribute AuthorityUrlproperti , AudienceAppId dan AuthorizedPartyAppId , seperti yang ditunjukkan pada cuplikan di bawah ini.

    [FunctionName("onTokenIssuanceStart")]
    public static WebJobsAuthenticationEventResponse Run(
        [WebJobsAuthenticationEventsTriggerAttribute(
            AudienceAppId = "Enter custom authentication extension app ID here",
            AuthorityUrl = "Enter authority URI here", 
            AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log)

Langkah selanjutnya

Mengonfigurasi peristiwa penerbitan token penyedia klaim kustom