Mengelola API dan versi runtime autentikasi App Service

  • Artikel

Artikel ini memperlihatkan cara mengkustomisasi API dan versi runtime dari autentikasi dan autorisasi bawaan di App Service.

Ada dua versi API manajemen untuk autentikasi App Service. Versi V2 diperlukan untuk pengalaman "Autentikasi" di portal Azure. Aplikasi yang sudah menggunakan API V1 dapat ditingkatkan ke versi V2 setelah beberapa perubahan dilakukan. Secara khusus, konfigurasi rahasia harus dipindah ke pengaturan aplikasi yang sticky-slot. Ini dapat dilakukan secara otomatis dari bagian "Autentikasi" dari portal untuk aplikasi Anda.

Perbarui versi konfigurasi

Peringatan

Migrasi ke V2 akan menonaktifkan manajemen fitur Autentikasi/Otorisasi App Service untuk aplikasi Anda melalui beberapa klien, seperti pengalaman yang ada di portal Azure, Azure CLI, dan Azure PowerShell. Ini tidak dapat dibalik.

API V2 tidak mendukung pembuatan atau pengeditan Akun Microsoft sebagai penyedia yang berbeda seperti yang dilakukan di V1. Sebaliknya, ini menggunakan platform identitas Microsoft yang dikonvergensikan untuk memasukkan pengguna dengan ID Microsoft Entra dan akun Microsoft pribadi. Saat beralih ke API V2, konfigurasi V1 Microsoft Entra digunakan untuk mengonfigurasi penyedia platform identitas Microsoft. Penyedia Akun Microsoft V1 akan diteruskan dalam proses migrasi dan terus beroperasi seperti biasa, tetapi Anda harus pindah ke model platform identitas Microsoft yang lebih baru. Lihat Dukungan untuk pendaftaran penyedia Microsoft Account untuk mempelajari selengkapnya.

Proses migrasi otomatis akan memindah rahasia penyedia ke pengaturan aplikasi lalu mengonversi konfigurasi lainnya ke dalam format baru. Untuk menggunakan migrasi otomatis:

  1. Navigasi ke aplikasi Anda di portal dan pilih opsi menu Autentikasi.
  2. Jika aplikasi dikonfigurasi menggunakan model V1, Anda akan melihat tombol Tingkatkan .
  3. Tinjau deskripsi dalam prompt konfirmasi. Jika Anda siap untuk melakukan migrasi, pilih Tingkatkan di perintah.

Mengelola migrasi secara manual

Langkah-langkah berikut akan memungkinkan Anda untuk memigrasikan aplikasi secara manual ke API V2 jika Anda tidak ingin menggunakan versi otomatis yang disebutkan di atas.

Memindahkan rahasia ke pengaturan aplikasi

  1. Dapatkan konfigurasi yang ada menggunakan API V1:

    az webapp auth show -g <group_name> -n <site_name>

    Dalam payload JSON yang dihasilkan, catat nilai rahasia yang digunakan untuk setiap penyedia yang telah Anda konfigurasi:

    • ID Microsoft Entra: clientSecret
    • Google: googleClientSecret
    • Facebook: facebookAppSecret
    • Twitter: twitterConsumerSecret
    • Microsoft Account: microsoftAccountClientSecret

    Penting

    Nilai rahasia adalah kredensial keamanan penting dan harus ditangani dengan hati-hati. Jangan bagikan nilai-nilai ini atau menyimpannya pada komputer lokal.

  2. Buat pengaturan aplikasi slot-stcky untuk setiap nilai rahasia. Anda dapat memilih nama setiap pengaturan aplikasi. Nilainya harus cocok dengan apa yang Anda peroleh di langkah sebelumnya atau mereferensikan rahasia Key Vault yang telah Anda buat dengan nilai tersebut.

    Untuk membuat pengaturan, Anda bisa menggunakan portal Azure atau menjalankan variasi berikut ini untuk setiap penyedia:

    # For Web Apps, Google example    
az webapp config appsettings set -g <group_name> -n <site_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

# For Azure Functions, Twitter example
az functionapp config appsettings set -g <group_name> -n <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

    Catatan

    Pengaturan aplikasi untuk konfigurasi ini harus ditandai sebagai slot-sticky, yang berarti bahwa tidak akan bergerak di antara lingkungan selama operasi swap slot. Ini karena konfigurasi autentikasi Anda sendiri terkait dengan lingkungan.

  3. Buat file JSON baru bernama authsettings.json. Ambil output yang Anda terima sebelumnya dan hapus setiap nilai rahasia darinya. Tulis sisa output ke file, pastikan bahwa tidak ada rahasia yang disertakan. Dalam beberapa kasus, konfigurasi mungkin memiliki array yang berisi string kosong. Pastikan tidak microsoftAccountOAuthScopes , dan jika tidak, alihkan nilai tersebut ke null.

  4. Tambahkan properti ke authsettings.json yang menunjuk ke nama pengaturan aplikasi yang Anda buat sebelumnya untuk setiap penyedia:

    • ID Microsoft Entra: clientSecretSettingName
    • Google: googleClientSecretSettingName
    • Facebook: facebookAppSecretSettingName
    • Twitter: twitterConsumerSecretSettingName
    • Microsoft Account: microsoftAccountClientSecretSettingName

    Contoh file setelah operasi ini mungkin terlihat mirip dengan yang berikut ini, dalam hal ini hanya dikonfigurasi untuk ID Microsoft Entra:

    {
    "id": "/subscriptions/00d563f8-5b89-4c6a-bcec-c1b9f6d607e0/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings",
    "name": "authsettings",
    "type": "Microsoft.Web/sites/config",
    "location": "Central US",
    "properties": {
        "enabled": true,
        "runtimeVersion": "~1",
        "unauthenticatedClientAction": "AllowAnonymous",
        "tokenStoreEnabled": true,
        "allowedExternalRedirectUrls": null,
        "defaultProvider": "AzureActiveDirectory",
        "clientId": "3197c8ed-2470-480a-8fae-58c25558ac9b",
        "clientSecret": "",
        "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
        "clientSecretCertificateThumbprint": null,
        "issuer": "https://sts.windows.net/0b2ef922-672a-4707-9643-9a5726eec524/",
        "allowedAudiences": [
            "https://mywebapp.azurewebsites.net"
        ],
        "additionalLoginParams": null,
        "isAadAutoProvisioned": true,
        "aadClaimsAuthorization": null,
        "googleClientId": null,
        "googleClientSecret": null,
        "googleClientSecretSettingName": null,
        "googleOAuthScopes": null,
        "facebookAppId": null,
        "facebookAppSecret": null,
        "facebookAppSecretSettingName": null,
        "facebookOAuthScopes": null,
        "gitHubClientId": null,
        "gitHubClientSecret": null,
        "gitHubClientSecretSettingName": null,
        "gitHubOAuthScopes": null,
        "twitterConsumerKey": null,
        "twitterConsumerSecret": null,
        "twitterConsumerSecretSettingName": null,
        "microsoftAccountClientId": null,
        "microsoftAccountClientSecret": null,
        "microsoftAccountClientSecretSettingName": null,
        "microsoftAccountOAuthScopes": null,
        "isAuthFromFile": "false"
    }   
}

  5. Kirim file ini sebagai konfigurasi Autentikasi/Otorisasi baru untuk aplikasi Anda:

    az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. Validasi bahwa aplikasi Anda masih beroperasi seperti yang diharapkan setelah gerakan ini.

  7. Hapus file yang digunakan di langkah-langkah sebelumnya.

Anda sekarang telah memigrasikan aplikasi untuk menyimpan rahasia idP sebagai pengaturan aplikasi.

Dukungan untuk pendaftaran penyedia Microsoft Account

Jika konfigurasi yang ada berisi penyedia Akun Microsoft dan tidak berisi penyedia Microsoft Entra, Anda dapat mengalihkan konfigurasi ke penyedia Microsoft Entra lalu melakukan migrasi. Cara melakukan:

  1. Buka Pendaftaran aplikasi di portal Azure dan temukan pendaftaran yang terkait dengan penyedia Microsoft Account Anda. Ini mungkin berada di bawah heading "Aplikasi dari akun pribadi".
  2. Navigasi ke halaman "Autentikasi" untuk pendaftaran. Di bagian "URI Pengalihan", Anda akan melihat entri yang berakhiran /.auth/login/microsoftaccount/callback. Salin URI ini.
  3. Tambahkan URI baru yang cocok dengan yang baru saja Anda salin, kecuali jika berakhiran dengan /.auth/login/aad/callback. Ini akan memungkinkan pendaftaran digunakan oleh konfigurasi Autentikasi/Otorisasi App Service.
  4. Navigasi ke konfigurasi Autentikasi / Otorisasi App Service untuk aplikasi Anda.
  5. Kumpulkan konfigurasi untuk penyedia Microsoft Account.
  6. Konfigurasikan penyedia Microsoft Entra menggunakan mode manajemen "Tingkat Lanjut", menyediakan ID klien dan nilai rahasia klien yang Anda kumpulkan di langkah sebelumnya. Untuk URL Pengeluar Sertifikat, gunakan <authentication-endpoint>/<tenant-id>/v2.0, dan ganti< titik> akhir autentikasi dengan titik akhir autentikasi untuk lingkungan cloud Anda (misalnya, "https://login.microsoftonline.com" untuk Azure global), juga mengganti <id> penyewa dengan ID Direktori (penyewa) Anda.
  7. Setelah Anda menyimpan konfigurasi, uji alur masuk dengan menavigasi di browser Anda ke /.auth/login/aad titik akhir di situs Anda dan selesaikan alur masuk.
  8. Pada titik ini, Anda telah berhasil menyalin konfigurasi, tetapi konfigurasi penyedia Akun Microsoft yang ada tetap ada. Sebelum Anda menghapusnya, pastikan bahwa semua bagian aplikasi Anda mereferensikan penyedia Microsoft Entra melalui tautan masuk, dll. Verifikasi bahwa semua bagian aplikasi Anda berfungsi seperti yang diharapkan.
  9. Setelah memvalidasi bahwa hal-hal berfungsi terhadap penyedia Microsoft Entra, Anda dapat menghapus konfigurasi penyedia Akun Microsoft.

Peringatan

Dimungkinkan untuk menyatukan dua pendaftaran dengan memodifikasi jenis akun yang didukung untuk pendaftaran aplikasi Microsoft Entra. Namun, ini akan memaksa permintaan persetujuan baru untuk pengguna Microsoft Account, dan klaim identitas pengguna tersebut mungkin berbeda dalam struktur, sub terutama yang mengubah nilai karena ID Aplikasi baru sedang digunakan. Pendekatan ini tidak dianjurkan kecuali dipahami secara menyeluruh. Anda harus menunggu dukungan untuk dua pendaftaran di permukaan API V2.

Beralih ke V2

Setelah langkah-langkah di atas dilakukan, navigasikan ke aplikasi di portal Azure. Pilih bagian "Autentikasi (pratinjau)".

Atau, Anda dapat membuat permintaan PUT terhadap sumber daya config/authsettingsv2 di bawah sumber daya situs. Skema untuk payload sama dengan yang diambil di Konfigurasi berbasis file.

Menyematkan aplikasi Anda ke versi runtime autentikasi tertentu

Saat Anda mengaktifkan autentikasi/otorisasi, middleware platform disuntikkan ke dalam alur permintaan HTTP Anda seperti yang dijelaskan dalam gambaran umum fitur. Middleware platform ini diperbarui secara berkala dengan fitur dan peningkatan baru sebagai bagian dari pembaruan platform rutin. Secara default, aplikasi web atau fungsi Anda akan berjalan pada versi terbaru middleware platform ini. Pembaruan otomatis ini selalu kompatibel dengan versi sebelumnya. Namun, jika pembaruan otomatis ini memperkenalkan masalah runtime untuk web atau aplikasi fungsi Anda, Anda dapat untuk sementara kembali ke versi middleware sebelumnya. Artikel ini menjelaskan cara menyematkan aplikasi untuk sementara ke versi middleware autentikasi tertentu.

Pembaruan versi otomatis dan manual

Anda dapat menyematkan aplikasi ke middleware platform versi tertentu dengan mengatur pengaturan runtimeVersion untuk aplikasi. Aplikasi Anda selalu berjalan pada versi terbaru kecuali Anda memilih untuk menyematkannya secara eksplisit kembali ke versi tertentu. Akan ada beberapa versi yang didukung pada satu waktu. Jika Anda menyematkan ke versi yang tidak valid yang tidak lagi didukung, aplikasi Anda akan menggunakan versi terbaru. Untuk selalu menjalankan versi terbaru, atur runtimeVersion ke ~1.

Menampilkan dan memperbarui versi runtime saat ini

Anda dapat mengubah versi runtime yang digunakan oleh aplikasi Anda. Versi runtime baru harus berlaku setelah memulai ulang aplikasi.

Melihat versi runtime saat ini

Anda dapat melihat versi middleware autentikasi platform saat ini baik menggunakan Azure CLI atau melalui salah satu titik akhir HTTP versi bawaan di aplikasi Anda.

Dari Azure CLI

Menggunakan Azure CLI, lihat versi middleware saat ini dengan perintah az webapp auth show.

az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>

Dalam kode ini, ganti <my_app_name> dengan nama aplikasi Anda. Ganti juga <my_resource_group> dengan nama grup sumber daya untuk aplikasi Anda.

Anda akan melihat runtimeVersion bidang di output CLI. Ini akan menyerupai contoh output berikut, yang telah dipotong untuk kejelasan:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Dari titik akhir versi

Anda juga dapat menekan titik akhir /.auth/version pada aplikasi juga untuk melihat versi middleware saat ini yang dijalankan aplikasi. Ini akan menyerupai contoh output berikut:

{
"version": "1.3.2"
}

Memperbarui versi runtime saat ini

Menggunakan Azure CLI, Anda dapat memperbarui runtimeVersion pengaturan di aplikasi dengan perintah az webapp auth update.

az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>

Ganti <my_app_name> dengan nama aplikasi Anda. Ganti juga <my_resource_group> dengan nama grup sumber daya untuk aplikasi Anda. Juga, ganti <version> dengan versi runtime 1.x yang valid atau ~1 untuk versi terbaru. Lihat catatan rilis untuk versi runtime yang berbeda untuk membantu menentukan versi yang akan disematkan.

Anda dapat menjalankan perintah ini dari Azure Cloud Shell dengan memilih Coba di sampel kode sebelumnya. Anda juga dapat menggunakan Azure CLI secara lokal untuk menjalankan perintah ini setelah menjalankan login az untuk masuk.

Langkah berikutnya

Tutorial: Mengautentikasi dan mengotorisasi pengguna secara menyeluruh