Bagikan melalui

Pemicu Peristiwa Autentikasi untuk pustaka klien Azure Functions untuk Node

Pemicu Peristiwa Autentikasi untuk Azure Functions menangani semua pemrosesan backend, (misalnya validasi skema token/json) untuk permintaan Http masuk untuk peristiwa Autentikasi. Dan memberi pengembang model objek berversi yang sangat di ketik untuk dikerjakan, yang berarti pengembang tidak perlu memiliki pengetahuan sebelumnya tentang payload json permintaan dan respons.

Kerangka kerja proyek ini menyediakan fitur-fitur berikut:

  • Validasi token untuk mengamankan panggilan API
  • Model objek, pengetikan, dan intellisense IDE
  • Validasi masuk dan keluar dari skema permintaan dan respons API
  • Penerapan versi
  • Tidak perlu kode boilerplate.

Memulai

Menginstal paket npm

npm install @azure/functions-authentication-events

Prasyarat

Mengautentikasi Klien

Ketika Azure AD layanan peristiwa autentikasi memanggil ekstensi kustom Anda, layanan tersebut akan mengirim Authorization header dengan Bearer {token}. Token ini akan mewakili autentikasi layanan ke layanan di mana:

  • 'Sumber daya', juga dikenal sebagai audiens, adalah aplikasi yang Anda daftarkan untuk mewakili API Anda. Ini diwakili oleh aud klaim dalam token.
  • 'Klien' adalah aplikasi Microsoft yang mewakili layanan peristiwa autentikasi Azure AD. Ini memiliki appId nilai 99045fe1-7639-4a75-9d4a-577b6ca3810f. Ini diwakili oleh:
    • Klaim azp dalam token jika properti aplikasi accessTokenAcceptedVersion Anda diatur ke 2.
    • Klaim appid dalam token jika properti aplikasi accessTokenAcceptedVersion sumber daya Anda diatur ke 1 atau null.

Ada tiga pendekatan untuk menangani token. Anda dapat menyesuaikan perilaku menggunakan pengaturan aplikasi seperti yang ditunjukkan di bawah ini atau melalui file local.settings.json di lingkungan lokal.

Memvalidasi token menggunakan integrasi autentikasi Azure Functions Azure AD

Saat menjalankan fungsi Anda dalam produksi, sangat disarankan untuk menggunakan integrasi autentikasi Azure Functions Azure AD untuk memvalidasi token masuk.

  1. Buka tab "Autentikasi" di Aplikasi Fungsi Anda
  2. Klik "Tambahkan IdP"
  3. Pilih "Microsoft" sebagai Penyedia Identitas
  4. Pilih "Berikan detail pendaftaran aplikasi yang ada"
  5. Masukkan Application ID aplikasi yang mewakili API Anda di Azure AD

Penerbit dan audiens yang diizinkan tergantung pada accessTokenAcceptedVersion properti aplikasi Anda (dapat ditemukan di "Manifes" aplikasi).

accessTokenAcceptedVersion Jika properti diatur ke 2: 6. Atur Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId')

accessTokenAcceptedVersion Jika properti diatur ke 1 atau null: 6. Atur Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known asidentifierUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}' jika menggunakan nama domain kustom.

Secara default, pemicu peristiwa Autentikasi akan memvalidasi bahwa integrasi autentikasi Azure Function dikonfigurasi dan akan memeriksa apakah klien dalam token diatur ke 99045fe1-7639-4a75-9d4a-577b6ca3810f (melalui azp klaim atau appid dalam token).

Jika Anda ingin menguji API terhadap beberapa klien lain yang tidak Azure AD layanan peristiwa autentikasi, seperti menggunakan Postman, Anda dapat mengonfigurasi pengaturan aplikasi opsional:

  • AuthenticationEvents__CustomCallerAppId - panduan klien yang Anda inginkan. Jika tidak disediakan, 99045fe1-7639-4a75-9d4a-577b6ca3810f diasumsikan.

Minta pemicu memvalidasi token

Di lingkungan atau lingkungan lokal yang tidak dihosting di layanan Azure Function, pemicu dapat melakukan validasi token. Atur pengaturan aplikasi berikut:

  • AuthenticationEvents__TenantId - ID penyewa Anda
  • AuthenticationEvents__AudienceAppId - nilai yang sama dengan "Audiens yang diizinkan" di opsi 1.
  • AuthenticationEvents__CustomCallerAppId (opsional) - panduan klien yang Anda inginkan. Jika tidak disediakan, 99045fe1-7639-4a75-9d4a-577b6ca3810f diasumsikan.

local.settings.json Contoh file:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8",
    "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038",
    "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038"
  }
}

Tidak ada validasi token

Jika Anda ingin tidak mengautentikasi token saat dalam pengembangan lokal, atur pengaturan aplikasi berikut:

  • AuthenticationEvents__BypassTokenValidation - nilai true akan membuat pemicu tidak memeriksa validasi token.

Mulai Cepat

  • Visual Studio Code
    • Mulai Visual Studio Code
    • Jalankan perintah func init . --worker-runtime node terminal melalui palet perintah
    • Jalankan perintah func new terminal melalui palet perintah
    • Ikuti perintah pembuatan proyek
    • Jalankan perintah npm install @azure/functions-authentication-events terminal melalui palet perintah
    • Jalankan perintah npm install terminal melalui palet perintah
    • Jalankan perintah npm run-script build terminal melalui palet perintah
  • Untuk tujuan pengembangan, ubah validasi token untuk pengujian:
  • Tambahkan kunci aplikasi AuthenticationEvents__BypassTokenValidation ke bagian "Nilai" di file local.settings.json dan atur nilainya ke true. Jika Anda tidak memiliki file local.settings.json di lingkungan lokal Anda, buat file tersebut di akar Aplikasi Fungsi Anda.
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}
  • Setelah proyek dimuat, Anda dapat menjalankan kode sampel dan Anda akan melihat aplikasi pengembang fungsi Azure memuat titik akhir Anda.

Konsep utama

Konsep utama Azure .NET SDK dapat ditemukan di sini

Dokumentasi

  • Salah satu fungsi telah diterbitkan, ada beberapa pembacaan yang baik tentang pengelogan dan metrik yang dapat ditemukan di sini

  • Untuk Dokumentasi API, silakan lihat (Tautan TBD)

  • Setelah ini bergerak ke pratinjau, kami kecuali tidak ada perubahan yang melanggar dan akan semampu menghapus sumber nuget yang menunjuk ke pratinjau privat.

Contoh

Untuk Menguji Augmentasi Token, lakukan hal berikut.

  • Buka proyek yang dibuat pada langkah sebelumnya. (Mulai Cepat)
  • Jalankan Aplikasi. func host start
  • Setelah aplikasi pengembang azure functions dimulai, salin url mendengarkan yang ditampilkan dengan aplikasi dimulai.
  • Catatan: Semua fungsi Autentikasi tercantum, dalam kasus kami memiliki satu pendengar fungsi yang terdaftar yang disebut "OnTokenIssuanceStart"
  • Titik akhir fungsi Anda kemudian akan menjadi kombinasi dari url dan fungsi yang mendengarkan, misalnya: "http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)& function=OnTokenIssuanceStart"
  • Posting payload berikut menggunakan sesuatu seperti Postman atau Fiddler.
  • Langkah-langkah untuk menggunakan Postman dapat ditemukan (Link TBD)
{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/00000001-0000-0ff1-ce00-000000000000/applications/ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "00000001-0000-0ff1-ce00-000000000000",
        "authenticationEventListenerId": "f2390d57-9664-4dde-b625-f0115925e1e2",
        "customAuthenticationExtensionId": "9cc1c1ed-5f04-4fdf-85c0-94a7c6ea819c",
        "authenticationContext": {
            "correlationId": "f4bd1870-b774-4fa5-ba78-e08ac6be14c0",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "resourceServicePrincipal": {
                "id": "eedfddb9-304e-4d62-aa83-24700a0bcf0e",
                "appId": "ef9e995c-efdb-4e76-97a9-8cdfc6e06afc",
                "appDisplayName": "",
                "displayName": "Test application"
            },
            "user": {
                "companyName": "Evo Sts Test",
                "country": "",
                "id": "69d24544-c420-4721-a4bf-106f2378d9f6",
                "mail": "testadmin@evostsoneboxtest.com",
                "onPremisesSamAccountName": "testadmin",
                "onPremisesSecurityIdentifier": "testadmin",
                "preferredDataLocation": "",
                "userPrincipalName": "testadmin@evostsoneboxtest.com"
            }
        }
    }
}
  • Anda akan melihat respons ini:
{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

Pemecahan Masalah

  • Visual Studio Code
    • Jika berjalan di Visual Studio Code, Anda mendapatkan kesalahan di sepanjang baris Emulator Azure Storage lokal tidak tersedia, Anda dapat memulai emulator secara manual.! (Catatan: Emulator Azure Storage sekarang tidak digunakan lagi dan penggantian yang disarankan adalah Azurite)
    • Jika menggunakan Visual Studio Code di Mac, silakan gunakan Azurite
    • Jika Anda melihat kesalahan berikut di Windows (ini adalah bug) saat mencoba menjalankan proyeksi yang dibuat.
    • Ini dapat diselesaikan dengan menjalankan perintah ini di powershell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine info lebih lanjut tentang ini dapat ditemukan di sini dan di sini

Langkah berikutnya

Untuk informasi selengkapnya tentang Azure SDK, silakan merujuk ke situs web ini

Terbitkan

  • Ikuti instruksi di sini untuk membuat dan menerbitkan Aplikasi Azure Anda. </azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure>
  • Untuk menentukan titik akhir posting yang diterbitkan, gabungkan titik akhir fungsi azure yang Anda buat, rutekan ke pendengar dan kode pendengar, kode dengar dapat ditemukan dengan menavigasi ke aplikasi fungsi azure Anda, memilih "Kunci Aplikasi" dan menyalin nilai AuthenticationEvents_extension.
  • Misalnya: "https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)& function=OnTokenIssuanceStart"
  • Pastikan lingkungan produksi Anda memiliki pengaturan aplikasi yang benar untuk autentikasi token.
  • Sekali lagi Anda dapat menguji fungsi yang diterbitkan dengan memposting payload di atas ke titik akhir baru.

Berkontribusi

Untuk detail tentang berkontribusi pada repositori ini, lihat panduan berkontribusi.

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repositori menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.

  • Last updated on