Bagikan melalui

Autentikasi kustom di Azure Static Web Apps

  • Artikel

Azure Static Web Apps menyediakan autentikasi terkelola yang menggunakan pendaftaran penyedia yang dikelola oleh Azure. Untuk memungkinkan fleksibilitas yang lebih terhadap pendaftaran, Anda dapat mengganti default dengan pendaftaran kustom.

  • Autentikasi kustom juga memungkinkan Anda mengonfigurasi penyedia kustom yang mendukung OpenID Connect. Konfigurasi ini memungkinkan pendaftaran beberapa penyedia eksternal.

  • Menggunakan pendaftaran kustom apa pun menonaktifkan semua penyedia yang telah dikonfigurasi sebelumnya.

Catatan

Autentikasi kustom hanya tersedia dalam paket Azure Static Web Apps Standard.

Mengonfigurasi penyedia identitas kustom

Penyedia identitas kustom dikonfigurasi di bagian auth dari file konfigurasi.

Untuk menghindari menempatkan rahasia dalam kontrol sumber, konfigurasi memeriksa pengaturan aplikasi untuk mencari nama yang cocok dalam file konfigurasi. Anda mungkin juga memilih untuk menyimpan rahasia Anda di Azure Key Vault.

Untuk membuat pendaftaran, mulailah dengan membuat pengaturan aplikasi berikut:

Nama Pengaturan Nilai
AZURE_CLIENT_ID ID Aplikasi (klien) untuk pendaftaran aplikasi Microsoft Entra.
'AZURE_CLIENT_SECRET_APP_SETTING_NAME Nama pengaturan aplikasi yang menyimpan rahasia klien untuk pendaftaran aplikasi Microsoft Entra.

Selanjutnya, gunakan sampel berikut untuk mengonfigurasi penyedia di file konfigurasi.

Penyedia Microsoft Entra tersedia dalam dua versi berbeda. Versi 1 secara eksplisit mendefinisikan userDetailsClaim, yang memungkinkan payload agar menampilkan informasi pengguna. Sebaliknya, versi 2 menampilkan informasi pengguna secara default, dan ditunjuk oleh v2.0 di URL openIdIssuer.

Microsoft Entra Versi 1

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Pastikan untuk mengganti <TENANT_ID> dengan ID penyewa Microsoft Entra Anda.

Microsoft Entra Versi 2

{
  "auth": {
    "identityProviders": {
      "azureActiveDirectory": {
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
        }
      }
    }
  }
}

Pastikan untuk mengganti <TENANT_ID> dengan ID penyewa Microsoft Entra Anda.

Untuk informasi selengkapnya tentang cara mengonfigurasi ID Microsoft Entra, lihat dokumentasi Autentikasi /Otorisasi App Service tentang menggunakan pendaftaran yang sudah ada.

Untuk mengonfigurasi akun mana yang dapat masuk, lihat Mengubah akun yang didukung oleh aplikasi dan Membatasi aplikasi Microsoft Entra Anda ke sekumpulan pengguna di penyewa Microsoft Entra.

Catatan

Sementara bagian konfigurasi untuk ID Microsoft Entra adalah azureActiveDirectory, platform alias ini aad di URL untuk masuk, keluar, dan menghapus menyeluruh informasi pengguna. Lihat bagian autentikasi dan otorisasi untuk informasi selengkapnya.

Sertifikat kustom

Gunakan langkah-langkah berikut untuk menambahkan sertifikat kustom ke pendaftaran aplikasi ID Microsoft Entra Anda.

  1. Jika belum, unggah sertifikat Anda ke Microsoft Key Vault.

  2. Tambahkan identitas terkelola di Static Web App Anda.

    Untuk identitas terkelola yang ditetapkan pengguna, atur keyVaultReferenceIdentity properti pada objek situs statis Anda ke resourceId identitas terkelola yang ditetapkan pengguna.

    Lewati langkah ini jika identitas terkelola Anda ditetapkan sistem.

  3. Berikan identitas terkelola kebijakan akses berikut:

    • Rahasia: Dapatkan/Daftar
    • Sertifikat: Dapatkan/Daftar

  4. Perbarui bagian konfigurasi autentikasi dari bagian azureActiveDirectory konfigurasi dengan nilai seperti yang clientSecretCertificateKeyVaultReference ditunjukkan dalam contoh berikut:

    {
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      "azureActiveDirectory": {
        "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        "registration": {
          "openIdIssuer": "https://login.microsoftonline.com/common/v2.0",
          "clientIdSettingName": "AZURE_CLIENT_ID",
          "clientSecretCertificateKeyVaultReference": "@Microsoft.KeyVault(SecretUri=https://<KEY_VAULT_NAME>.azure.net/certificates/<CERTIFICATE_NAME>/<CERTIFICATE_VERSION_ID>)",
          "clientSecretCertificateThumbprint": "*"
        }
      }
    }
  }
}

    Pastikan untuk mengganti nilai Anda untuk tempat penampung yang dikelilingi oleh <>.

    Di URI rahasia, tentukan nama brankas kunci dan nama sertifikat. Jika Anda ingin menyematkan ke versi, sertakan versi sertifikat, jika tidak, hilangkan versi untuk mengizinkan runtime untuk memilih versi sertifikat terbaru.

    Atur clientSecretCertificateThumbprint sama dengan * untuk selalu menarik versi terbaru thumbprint sertifikat.

Panggilan balik autentikasi

Penyedia identitas memerlukan URL pengalihan untuk menyelesaikan permintaan masuk atau keluar. Sebagian besar penyedia mengharuskan Anda menambahkan URL panggilan balik ke daftar izin. Titik akhir berikut ini tersedia sebagai tujuan pengalihan.

Jenis Pola URL
Masuk https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback
Keluar https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback

Jika Anda menggunakan ID Microsoft Entra, gunakan aad sebagai nilai untuk <PROVIDER_NAME_IN_CONFIG> tempat penampung.

Catatan

URL ini disediakan oleh Azure Static Web Apps untuk menerima respons dari penyedia autentikasi, Anda tidak perlu membuat halaman di rute ini.

Rincian masuk, keluar, dan pengguna

Untuk menggunakan penyedia identitas kustom, gunakan pola URL berikut.

Perbuatan Pola
Masuk /.auth/login/<PROVIDER_NAME_IN_CONFIG>
Keluar /.auth/logout
Detail pengguna /.auth/me
Menghapus detail pengguna secara menyeluruh /.auth/purge/<PROVIDER_NAME_IN_CONFIG>

Jika Anda menggunakan ID Microsoft Entra, gunakan aad sebagai nilai untuk <PROVIDER_NAME_IN_CONFIG> tempat penampung.

Mengelola peran

Setiap pengguna yang mengakses aplikasi web statis milik satu atau beberapa peran. Ada dua peran bawaan yang dapat dimiliki pengguna:

  • anonim: Semua pengguna secara otomatis termasuk dalam peran anonim.
  • diautentikasi: Semua pengguna yang masuk termasuk dalam peran terautentikasi.

Selain peran bawaan, Anda dapat menetapkan peran kustom kepada pengguna, dan mereferensikannya dalam file staticwebapp.config.json.

Menambahkan pengguna ke peran

Untuk menambahkan pengguna ke peran, Anda menghasilkan undangan yang memungkinkan Anda mengaitkan pengguna ke peran tertentu. Peran didefinisikan dan dipertahankan dalam file staticwebapp.config.json.

Membuat undangan

Undangan khusus untuk penyedia otorisasi individual, jadi pertimbangkan kebutuhan aplikasi Anda saat Anda memilih penyedia mana yang akan didukung. Beberapa penyedia mengekspos alamat email pengguna, sementara yang lain hanya menyediakan nama pengguna situs.

Penyedia otorisasi Mengekspos
Microsoft Entra ID alamat email
GitHub Nama pengguna
X Nama pengguna

Gunakan langkah-langkah berikut untuk membuat undangan.

  1. Buka sumber daya Static Web Apps di portal Azure.
  2. Di bawah Pengaturan, pilih Manajemen Peran.
  3. Pilih Undang.
  4. Pilih Penyedia otorisasi dari daftar opsi.
  5. Tambahkan nama pengguna atau alamat email penerima dalam kotak Detail undangan.
    • Untuk GitHub dan X, masukkan nama pengguna. Untuk yang lainnya, masukkan alamat email penerima.
  6. Pilih domain situs statis Anda dari menu drop-down Domain .
    • Domain yang Anda pilih adalah domain yang muncul dalam undangan. Jika Anda memiliki domain kustom yang terkait dengan situs Anda, pilih domain kustom.
  7. Tambahkan daftar nama peran yang dipisahkan koma dalam kotak Peran.
  8. Masukkan jumlah jam maksimum yang Anda inginkan agar undangan tetap valid.
    • Batas maksimum yang mungkin adalah 168 jam, yaitu tujuh hari.
  9. Pilih Hasilkan.
  10. Salin tautan dari kotak Tautan undang.
  11. Kirim tautan undangan melalui email ke pengguna yang Anda berikan aksesnya.

Saat pengguna memilih tautan dalam undangan, mereka diminta untuk masuk dengan akun terkait. Setelah berhasil masuk, pengguna dikaitkan dengan peran yang dipilih.

Perhatian

Pastikan aturan rute Anda tidak berkonflik dengan penyedia autentikasi yang Anda pilih. Memblokir penyedia dengan aturan rute mencegah pengguna menerima undangan.

Memperbarui penetapan peran

  1. Buka sumber daya Static Web Apps di portal Azure.
  2. Di bawah Pengaturan, pilih Manajemen Peran.
  3. Pilih pengguna dalam daftar.
  4. Edit daftar peran dalam kotak Peran.
  5. Pilih Perbarui.

Menghapus pengguna

  1. Buka sumber daya Static Web Apps di portal Azure.
  2. Di bawah Pengaturan, pilih Manajemen Peran.
  3. Temukan pengguna dalam daftar.
  4. Centang kotak centang pada baris pengguna.
  5. Pilih Hapus.

Saat Anda menghapus pengguna, ingatlah item berikut:

  • Menghapus pengguna membatalkan izin mereka.
  • Penyebaran di seluruh dunia mungkin memakan waktu beberapa menit.
  • Jika pengguna ditambahkan kembali ke aplikasi, userId mengubah.

Langkah berikutnya

Mengatur peran pengguna secara terprogram