存取 Azure Static Web Apps 中的使用者資訊

Azure Static Web Apps 透過直接存取端點提供驗證相關的使用者資訊給 API 函式。

許多使用者介面高度依賴使用者驗證資料。 直接存取端點是公用程式 API，會公開使用者資訊，而不需要實作自訂函式。 除了便利之外，直接存取端點不會因與無伺服器架構相關聯的冷啟動延遲而變動。

用戶端主體資料

用戶端主體資料物件會將使用者識別資訊公開給您的應用程式。 下列屬性可在用戶端主體物件中精選使用：

屬性	說明
identityProvider	識別提供者的名稱。
userId	使用者的 Azure Static Web Apps 專用唯一識別碼。 每個應用程式中的這個值是唯一的。 例如，相同的使用者在不同的靜態 Web 應用程式資源上會傳回不同的 userId 值。 在使用者存留期，此值會持續存在。 如果您刪除並將相同的使用者新增回應用程式，會產生新的 userId。
userDetails	使用者的使用者名稱或電子郵件地址。 有些提供者會傳回使用者的電子郵件地址，有些則會傳送使用者控制碼。
userRoles	使用者獲派角色的陣列。
claims	自訂驗證提供者所傳回的宣告陣列。 只能在直接存取端點中存取。

以下是用戶端主體物件的範例：

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

直接存取端點

您可以將 GET 要求傳送至 /.auth/me 路由，並接收用戶端主體資料的直接存取權。 當您的檢視狀態依賴授權資料時，請使用此方法來獲得最佳效能。

針對已登入的使用者，回應會包含用戶端主體 JSON 物件。 未經驗證的使用者所提出的要求會傳回 null。

使用 fetch¹ API，您可以使用下列語法來存取用戶端主體資料。

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

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

API 函式

Static Web Apps 中透過 Azure Functions 後端提供的所有 API 函式，都可存取與用戶端應用程式相同的使用者資訊，但 claims 陣列除外。 雖然 API 確實會接收使用者識別資訊，但其不會針對使用者是否已通過驗證，或他們是否符合必要的角色執行自己的檢查。 存取控制規則會於 staticwebapp.config.json 檔案中定義。

JavaScript

用戶端主體資料會傳遞至 x-ms-client-principal 要求標頭中的 API 函式。 用戶端主體資料會以 Base64 編碼字串的形式傳送，其中包含已序列化的 JSON 物件。

下列範例函式顯示如何讀取和傳回使用者資訊。

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),
    },
  };
};

假設上述函式的名稱為 user，您可以使用 fetch¹ 瀏覽器 API，使用下列語法來存取 API 的回應。

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

console.log(await getUser());

C#

在 C# 函式中，使用者資訊可從 x-ms-client-principal 標頭取得，您的應用程式可以將其還原序列化為 ClaimsPrincipal 物件或您自己的自訂類型。 下列程式碼示範如何將標頭解開成中繼類型 ClientPrincipal，然後轉換成 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);
  }
}

當使用者登入時，x-ms-client-principal 標頭會透過 Static Web Apps 邊緣節點新增至對使用者資訊的要求。

注意

API 函式中可存取的 x-ms-client-principal 標頭不包含 claims 陣列。

¹ Internet Explorer 不支援 fetch API 和 await 運算子。

下一步

設定應用程式設定