الوصول إلى معلومات المستخدم في Azure Static Web Apps

توفر Azure Static Web Apps معلومات المستخدم المتعلقة بالمصادقة عبر نقطة نهاية الوصول المباشر وإلى وظائف واجهة برمجة التطبيقات.

تعتمد العديد من واجهات المستخدم بشكل كبير على بيانات مصادقة المستخدم. نقطة نهاية الوصول المباشر هي واجهة برمجة تطبيقات الأداة المساعدة التي تعرض معلومات المستخدم دون الحاجة إلى تنفيذ وظيفة مخصصة. بالإضافة إلى الراحة، لا تخضع نقطة نهاية الوصول المباشر لتأخيرات البدء الباردة المرتبطة بالبنية بلا خادم.

بيانات العميل الأساسية

يعرض كائن البيانات الأساسي للعميل معلومات تعريف المستخدم لتطبيقك. يتم عرض الخصائص التالية في كائن العميل الأساسي:

الخاصية	‏‏الوصف
identityProvider	اسم موفر الهوية.
userId	معرف فريد خاص ب Azure Static Web Apps للمستخدم. القيمة فريدة على أساس كل تطبيق. على سبيل المثال، يقوم المستخدم نفسه بإرجاع قيمة مختلفة userId على مورد Static Web Apps مختلف. تستمر القيمة طوال مدة بقاء المستخدم. إذا قمت بحذف المستخدم نفسه وإضافته مرة أخرى إلى التطبيق، إنشاء مستخدم جديد 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.

باستخدام إحضار¹ 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());
})();

دوال واجهة برمجة التطبيقات

تتمتع وظائف واجهة برمجة التطبيقات المتوفرة في Static Web Apps عبر الواجهة الخلفية لوظائف Azure بالوصول إلى نفس معلومات المستخدم مثل تطبيق العميل، باستثناء claims الصفيف. بينما تتلقى واجهة برمجة التطبيقات معلومات تعريف المستخدم، فإنها لا تجري عمليات التحقق الخاصة بها إذا تمت مصادقة المستخدم أو إذا تطابقت مع دور مطلوب. يتم تعريف قواعد التحكم بالوصول في staticwebapp.config.json الملف.

JavaScript

يتم تمرير بيانات العميل الأساسية إلى وظائف واجهة برمجة التطبيقات في x-ms-client-principal عنوان الطلب. يتم إرسال البيانات الأساسية للعميل كسلسلة مشفرة ب 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، يمكنك استخدام واجهة برمجة تطبيقات المستعرض إحضار¹ للوصول إلى استجابة واجهة برمجة التطبيقات باستخدام بناء الجملة التالي.

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.

إشعار

x-ms-client-principal لا يحتوي العنوان الذي يمكن الوصول إليه في دالة API على claims الصفيف.

¹لا يتم دعم واجهة برمجة تطبيقات الإحضار وعامل انتظار في Internet Explorer.

الخطوات التالية

تكوين إعدادات التطبيق