Autentikasi dan otorisasi untuk Azure Static Web Apps

Artikel
07/27/2022
7 menit untuk membaca

Azure Static Web Apps menyediakan pengalaman autentikasi yang disederhanakan. Secara default, Anda memiliki akses ke serangkaian penyedia yang telah dikonfigurasi sebelumnya, atau opsi untuk mendaftarkan penyedia kustom.

Setiap pengguna dapat mengautentikasi dengan penyedia yang diaktifkan.
Setelah masuk, pengguna termasuk dalam peran anonymous dan authenticated secara default.
Pengguna yang berwenang mendapatkan akses ke rute terbatas berdasarkan aturan yang ditentukan staticwebapp.config.jspada file.
Pengguna diberi peran kustom menggunakan sistem undangan bawaan.
Pengguna dapat diberi peran kustom saat login oleh fungsi API secara terprogram.
Semua penyedia autentikasi diaktifkan secara default.
- Untuk membatasi penyedia autentikasi, akses blokir dengan aturan rute kustom. Mengonfigurasi penyedia kustom juga menonaktifkan penyedia yang telah dikonfigurasi sebelumnya.
Penyedia yang telah dikonfigurasi meliputi:
- Azure Active Directory ¹
- GitHub
- Twitter

¹ Penyedia Azure Active Directory yang telah dikonfigurasi sebelumnya memungkinkan Akun Microsoft mana pun untuk masuk. Untuk membatasi login ke penyewa Direktori Aktif tertentu, konfigurasikan penyedia Azure Active Directory kustom.

Subjek autentikasi dan otorisasi secara signifikan tumpang tindih dengan konsep perutean, yang diperinci dalam panduan konfigurasi aplikasi.

Folder sistem

Azure Static Web Apps menggunakan folder sistem /.auth untuk menyediakan akses ke API terkait otorisasi. Daripada mengekspos salah satu rute di bawah folder /.auth langsung ke pengguna akhir, pertimbangkan untuk membuat aturan perutean untuk membuat URL yang ramah.

Gunakan tabel berikut ini untuk menemukan rute khusus penyedia.

Penyedia otorisasi	Rute login
Azure Active Directory	`/.auth/login/aad`
GitHub	`/.auth/login/github`
Twitter	`/.auth/login/twitter`

Misalnya, untuk masuk dengan GitHub, Anda dapat menyertakan tautan seperti cuplikan berikut:

<a href="/.auth/login/github">Login</a>

Jika Anda memilih untuk mendukung lebih dari satu penyedia, maka Anda perlu mengekspos tautan khusus penyedia untuk masing-masing di situs web Anda.

Anda dapat menggunakan aturan rute untuk memetakan penyedia default ke rute yang ramah seperti /login.

{
  "route": "/login",
  "redirect": "/.auth/login/github"
}

Jika Anda ingin pengguna kembali ke halaman tertentu setelah masuk, berikan URL lengkap yang memenuhi syarat dalam parameter string kueri post_login_redirect_uri.

Contohnya:

<a href="/.auth/login/github?post_login_redirect_uri=https://zealous-water.azurestaticapps.net/success">Login</a>

Selain itu, Anda dapat mengalihkan pengguna yang tidak diautentikasi kembali ke halaman referensi setelah mereka masuk. Untuk mengonfigurasi perilaku ini, buat aturan penimpaanpost_login_redirect_uri respons yang diatur ke .referrer.

Contohnya:

{
  "responseOverrides": {
    "401": {
      "redirect": "/.auth/login/github?post_login_redirect_uri=.referrer",
      "statusCode": 302
    }
  }
}

Keluar

Rute /.auth/logout mencatat pengguna keluar dari situs web. Anda bisa menambahkan tautan ke navigasi situs Anda untuk memungkinkan pengguna keluar seperti yang diperlihatkan dalam contoh berikut.

<a href="/.auth/logout">Log out</a>

Anda dapat menggunakan aturan rute untuk memetakan rute yang ramah seperti /logout.

{
  "route": "/logout",
  "redirect": "/.auth/logout"
}

Pascapengalihan log keluar

Jika Anda ingin pengguna kembali ke halaman tertentu setelah log keluar, berikan URL dalam parameter string kueri post_logout_redirect_uri.

Memblokir penyedia autentikasi

Anda mungkin ingin membatasi aplikasi agar tidak menggunakan penyedia autentikasi. Misalnya, aplikasi Anda mungkin ingin menstandarkan hanya pada penyedia yang mengekspos alamat email.

Untuk memblokir penyedia, Anda dapat membuat aturan rute untuk mengembalikan kode status 404 untuk permintaan ke rute khusus penyedia yang diblokir. Misalnya, untuk membatasi Twitter sebagai penyedia, tambahkan aturan rute berikut.

{
  "route": "/.auth/login/twitter",
  "statusCode": 404
}

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 adalah milik 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 pengguna
Azure Active Directory	alamat email
GitHub	nama pengguna
Twitter	nama pengguna

Navigasi ke sumber daya Aplikasi Web Statis di portal Microsoft Azure.
Di bawah Pengaturan, klik Manajemen Peran.
Klik tombol Undang.
Pilih Penyedia otorisasi dari daftar opsi.
Tambahkan nama pengguna atau alamat email penerima dalam kotak Detail undangan.
- Untuk GitHub dan Twitter, Anda memasukkan nama pengguna. Untuk yang lainnya, masukkan alamat email penerima.
Pilih domain situs statis Anda dari drop-down Domain.
- Domain yang Anda pilih adalah domain yang muncul dalam undangan. Jika Anda memiliki domain kustom yang terkait dengan situs Anda, Anda mungkin ingin memilih domain kustom.
Tambahkan daftar nama peran yang dipisahkan koma dalam kotak Peran.
Masukkan jumlah jam maksimum yang Anda inginkan agar undangan tetap valid.
- Batas maksimum yang dimungkinkan adalah 168 jam, yaitu 7 hari.
Klik tombol Hasilkan.
Salin tautan dari kotak Tautan undang.
Kirim tautan undangan melalui email ke orang yang Anda berikan akses ke aplikasi Anda.

Saat pengguna mengklik tautan dalam undangan, mereka akan diminta untuk masuk dengan akun terkait mereka. 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 akan mencegah pengguna menerima undangan.

Memperbarui penetapan peran

Navigasi ke sumber daya Aplikasi Web Statis di portal Microsoft Azure.
Di bawah Pengaturan, klik Manajemen Peran.
Klik pengguna dalam daftar.
Edit daftar peran dalam kotak Peran.
Klik tombol Perbarui.

Menghapus pengguna

Navigasi ke sumber daya Aplikasi Web Statis di portal Microsoft Azure.
Di bawah Pengaturan, klik Manajemen Peran.
Temukan pengguna dalam daftar.
Centang kotak centang pada baris pengguna.
Klik tombol 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.

Alih-alih menggunakan sistem undangan bawaan, Anda dapat menggunakan fungsi tanpa server untuk menetapkan peran kepada pengguna saat masuk secara terprogram.

Untuk menetapkan peran kustom dalam suatu fungsi, Anda dapat menentukan fungsi API yang otomatis dipanggil setelah setiap kali pengguna berhasil mengautentikasi dengan penyedia identitas. Informasi pengguna diteruskan ke fungsi ini dari penyedia. Ini harus menampilkan daftar peran kustom yang ditetapkan kepada pengguna.

Contoh penggunaan fungsi ini meliputi:

Mengkueri database untuk menentukan peran yang harus ditetapkan pengguna
Memanggil API Microsoft Graph untuk menentukan peran pengguna berdasarkan keanggotaan grup Direktori Aktif mereka
Menentukan peran pengguna berdasarkan klaim yang ditampilkan oleh penyedia identitas

Catatan

Kemampuan untuk menetapkan peran melalui fungsi hanya tersedia saat autentikasi kustom dikonfigurasi.

Saat fitur ini diaktifkan, peran apa pun yang ditetapkan melalui sistem undangan bawaan diabaikan.

Mengonfigurasi fungsi untuk menetapkan peran

Untuk mengonfigurasi Static Web Apps agar menggunakan fungsi API sebagai fungsi penetapan peran, tambahkan properti rolesSource ke bagian authfile konfigurasi aplikasi Anda. Nilai properti rolesSource adalah jalur ke fungsi API.

{
  "auth": {
    "rolesSource": "/api/GetRoles",
    "identityProviders": {
      // ...
    }
  }
}

Catatan

Setelah dikonfigurasi, fungsi penetapan peran tidak dapat lagi diakses oleh permintaan HTTP eksternal.

Membuat fungsi untuk menetapkan peran

Setelah menentukan properti rolesSource dalam konfigurasi aplikasi Anda, tambahkan fungsi API di aplikasi web statis di jalur yang Anda tentukan. Anda dapat menggunakan aplikasi fungsi terkelola atau membawa aplikasi fungsi Anda sendiri.

Setiap kali pengguna berhasil mengautentikasi dengan penyedia identitas, fungsi yang ditentukan dipanggil melalui metode POST. Fungsi ini melewati objek JSON dalam isi permintaan yang berisi informasi pengguna dari penyedia. Untuk beberapa penyedia identitas, informasi pengguna juga mencakup accessToken yang fungsinya dapat digunakan untuk melakukan panggilan API menggunakan identitas pengguna.

Ini adalah contoh payload dari Azure Active Directory:

{
  "identityProvider": "aad",
  "userId": "72137ad3-ae00-42b5-8d54-aacb38576d76",
  "userDetails": "ellen@contoso.com",
  "claims": [
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
          "val": "ellen@contoso.com"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
          "val": "Contoso"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
          "val": "Ellen"
      },
      {
          "typ": "name",
          "val": "Ellen Contoso"
      },
      {
          "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier",
          "val": "7da753ff-1c8e-4b5e-affe-d89e5a57fe2f"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
          "val": "72137ad3-ae00-42b5-8d54-aacb38576d76"
      },
      {
          "typ": "http://schemas.microsoft.com/identity/claims/tenantid",
          "val": "3856f5f5-4bae-464a-9044-b72dc2dcde26"
      },
      {
          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
          "val": "ellen@contoso.com"
      },
      {
          "typ": "ver",
          "val": "1.0"
      }
  ],
  "accessToken": "eyJ0eXAiOiJKV..."
}

Fungsi ini dapat menggunakan informasi pengguna untuk menentukan peran mana yang akan ditetapkan kepada pengguna. Ini harus menampilkan respons HTTP 200 dengan isi JSON yang berisi daftar nama peran khusus untuk ditetapkan kepada pengguna.

Misalnya, untuk menetapkan pengguna ke peran Reader dan Contributor, tampilkan respons berikut:

{
  "roles": [
    "Reader",
    "Contributor"
  ]
}

Jika Anda tidak ingin menetapkan peran tambahan apa pun kepada pengguna, tampilkan array roles kosong.

Untuk mempelajari lebih lanjut, lihat Tutorial: Menetapkan peran kustom dengan fungsi dan Microsoft Graph.

Menghapus informasi identifikasi pribadi

Ketika Anda memberikan persetujuan untuk aplikasi sebagai pengguna akhir, aplikasi memiliki akses ke alamat email atau nama pengguna Anda bergantung pada penyedia identitas. Setelah informasi ini diberikan, pemilik aplikasi memutuskan cara mengelola informasi identifikasi pribadi.

Pengguna akhir perlu menghubungi administrator aplikasi web individual untuk mencabut informasi ini dari sistem mereka.

Untuk menghapus informasi identifikasi pribadi dari platform Azure Static Web Apps, dan mencegah platform memberikan informasi ini pada permintaan di masa mendatang, kirimkan permintaan menggunakan URL:

https://identity.azurestaticapps.net/.auth/purge/<AUTHENTICATION_PROVIDER_NAME>

Untuk mencegah platform memberikan informasi ini pada permintaan mendatang ke aplikasi individual, kirim permintaan ke URL berikut:

https://<WEB_APP_DOMAIN_NAME>/.auth/purge/<AUTHENTICATION_PROVIDER_NAME>

Perhatikan bahwa jika Anda menggunakan Azure Active Directory, gunakan aad sebagai nilai untuk <AUTHENTICATION_PROVIDER_NAME> placeholder.

Batasan

Lihat artikel Kuota untuk batasan dan pembatasan umum.

Langkah berikutnya

Mengakses data autentikasi dan otorisasi pengguna