Mengakses informasi pengguna di Azure Static Web Apps

Azure Static Web Apps menyediakan informasi pengguna terkait autentikasi melalui titik akhir akses langsung dan ke fungsi API.

Banyak antarmuka pengguna sangat bergantung pada data autentikasi pengguna. Titik akhir akses langsung adalah API utilitas yang memaparkan informasi pengguna tanpa harus mengimplementasikan fungsi kustom. Di luar kenyamanan, titik akhir akses langsung tidak tunduk pada penundaan mulai cold yang berhubungan dengan arsitektur tanpa server.

Data utama klien

Objek data utama klien memaparkan informasi yang dapat diidentifikasi pengguna ke aplikasi Anda. Properti berikut ditampilkan dalam objek utama klien:

Properti	Deskripsi
identityProvider	Nama penyedia identitas.
userId	Pengidentifikasi unik khusus Azure Static Web Apps untuk pengguna. Nilainya berbeda pada basis per-aplikasi. Misalnya, pengguna yang sama mengembalikan nilai userId yang berbeda pada sumber daya Static Web Apps yang berbeda. Nilai tersebut persisten selama masa pakai pengguna. Jika Anda menghapus dan menambahkan pengguna yang sama kembali ke aplikasi, userId baru akan dibuat.
userDetails	Nama pengguna atau alamat email pengguna. Beberapa penyedia mengembalikan alamat email pengguna, sementara penyedia lain mengirim nama pengguna.
userRoles	Array peran yang ditetapkan pengguna.
claims	Array klaim yang dikembalikan oleh penyedia autentikasi kustom Anda. Hanya dapat diakses di titik akhir akses langsung.

Contoh berikut adalah contoh objek utama klien:

{
  "identityProvider": "github",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "userDetails": "username",
  "userRoles": ["anonymous", "authenticated"],
  "claims": [{
    "typ": "name",
    "val": "Azure Static Web Apps"
  }]
}

Titik akhir akses langsung

Anda dapat mengirim permintaan GET ke rute /.auth/me dan menerima akses langsung ke data utama klien. Saat status tampilan Anda bergantung pada data otorisasi, gunakan pendekatan ini untuk performa terbaik.

Untuk pengguna yang masuk, responsnya berisi objek JSON utama klien. Permintaan dari pengguna yang tidak diautentikasi menampilkan null.

Dengan menggunakan API fetch¹, Anda dapat mengakses data utama klien menggunakan sintaksis berikut.

async function getUserInfo() {
  const response = await fetch('/.auth/me');
  const payload = await response.json();
  const { clientPrincipal } = payload;
  return clientPrincipal;
}

(async () => {
console.log(await getUserInfo());
})();

Fungsi API

Fungsi API yang tersedia di Static Web Apps melalui backend Azure Functions memiliki akses ke informasi pengguna yang sama dengan aplikasi klien, dengan pengecualian claims array. Meskipun API menerima informasi yang dapat diidentifikasi pengguna, API tidak melakukan pemeriksaannya sendiri jika pengguna diautentikasi atau jika mereka cocok dengan peran yang diperlukan. Aturan kontrol akses ditentukan dalam file staticwebapp.config.json.

JavaScript

Data utama klien diteruskan ke fungsi API di header permintaan x-ms-client-principal. Data utama klien dikirim sebagai untai berenkode Base64 yang berisi objek JSON berseri.

Contoh fungsi berikut memperlihatkan cara membaca dan menampilkan informasi pengguna.

module.exports = async function (context, req) {
  const header = req.headers.get('x-ms-client-principal');
  const encoded = Buffer.from(header, 'base64');
  const decoded = encoded.toString('ascii');

  context.res = {
    body: {
      clientPrincipal: JSON.parse(decoded),
    },
  };
};

Dengan asumsi fungsi di atas bernama user, Anda dapat menggunakan API browser fetch¹ untuk mengakses respons API menggunakan sintaksis berikut.

async function getUser() {
  const response = await fetch('/api/user');
  const payload = await response.json();
  const { clientPrincipal } = payload;
  return clientPrincipal;
}

console.log(await getUser());

C#

Dalam fungsi C#, informasi pengguna tersedia dari header x-ms-client-principal yang dapat dideserialisasi menjadi objek ClaimsPrincipal, atau jenis kustom Anda sendiri. Kode berikut menunjukkan cara membongkar header menjadi jenis perantara, ClientPrincipal, yang kemudian diubah menjadi instans ClaimsPrincipal.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Claims;
using System.Text;
using System.Text.Json;
using Microsoft.AspNetCore.Http;

public static class StaticWebAppsAuth
{
  private class ClientPrincipal
  {
      public string IdentityProvider { get; set; }
      public string UserId { get; set; }
      public string UserDetails { get; set; }
      public IEnumerable<string> UserRoles { get; set; }
  }

  public static ClaimsPrincipal Parse(HttpRequest req)
  {
      var principal = new ClientPrincipal();

      if (req.Headers.TryGetValue("x-ms-client-principal", out var header))
      {
          var data = header[0];
          var decoded = Convert.FromBase64String(data);
          var json = Encoding.UTF8.GetString(decoded);
          principal = JsonSerializer.Deserialize<ClientPrincipal>(json, new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
      }

      principal.UserRoles = principal.UserRoles?.Except(new string[] { "anonymous" }, StringComparer.CurrentCultureIgnoreCase);

      if (!principal.UserRoles?.Any() ?? true)
      {
          return new ClaimsPrincipal();
      }

      var identity = new ClaimsIdentity(principal.IdentityProvider);
      identity.AddClaim(new Claim(ClaimTypes.NameIdentifier, principal.UserId));
      identity.AddClaim(new Claim(ClaimTypes.Name, principal.UserDetails));
      identity.AddClaims(principal.UserRoles.Select(r => new Claim(ClaimTypes.Role, r)));

      return new ClaimsPrincipal(identity);
  }
}

Ketika pengguna masuk, header x-ms-client-principal ditambahkan ke permintaan informasi pengguna melalui simpul edge Static Web Apps.

Catatan

Header x-ms-client-principal yang dapat diakses dalam fungsi API tidak berisi claims array.

¹ API fetch dan operator menunggu tidak didukung di Internet Explorer.

Langkah berikutnya

Mengonfigurasi pengaturan aplikasi