Zugreifen auf Benutzerinformationen in Azure Static Web Apps

Von Azure Static Web Apps werden authentifizierungsbezogene Benutzerinformationen über einen Direktzugriffsendpunkt und für API-Funktionen bereitgestellt.

Viele Benutzeroberflächen hängen stark von Benutzerauthentifizierungsdaten ab. Bei dem Direktzugriffsendpunkt handelt es sich um eine Hilfs-API, die Benutzerinformationen verfügbar macht, ohne eine benutzerdefinierte Funktion implementieren zu müssen. Der Direktzugriffsendpunkt sorgt für zusätzlichen Komfort und ist auch nicht von den Kaltstartverzögerungen einer serverlosen Architektur betroffen.

Clientprinzipaldaten

Durch das Clientprinzipaldatenobjekt werden benutzerbezogene Informationen für Ihre App verfügbar gemacht. Folgenden Eigenschaften sind im Clientprinzipalobjekt enthalten:

Eigenschaft	Beschreibung
identityProvider	Der Name des Identitätsanbieters.
userId	Ein Azure Static Web Apps-spezifischer Bezeichner für den Benutzer. Der Wert ist App-spezifisch eindeutig. Für den gleichen Benutzer wird also beispielsweise in einer anderen Static Web Apps-Ressource ein anderer Wert vom Typ userId zurückgegeben. Der Wert bleibt während der Lebensdauer eines Benutzers erhalten. Wenn Sie einen Benutzer löschen und wieder der App hinzufügen, wird ein neuer Wert vom Typ userId generiert.
userDetails	Der Benutzername oder die E-Mail-Adresse des Benutzers. Von einigen Anbietern wird die E-Mail-Adresse des Benutzers zurückgegeben, von anderen das Benutzerhandle.
userRoles	Ein Array der zugewiesenen Rollen des Benutzers.
claims	Ein Array mit Ansprüchen, die von Ihrem benutzerdefinierten Authentifizierungsanbieter zurückgegeben werden. Nur erreichbar im Endpunkt mit direktem Zugriff.

Beim folgenden Beispiel handelt es sich um ein exemplarisches Clientprinzipalobjekt:

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

Direktzugriffsendpunkt

Sie können eine Anforderung vom Typ GET an die Route /.auth/me senden und direkten Zugriff auf die Clientprinzipaldaten erhalten. Wenn der Zustand Ihrer Ansicht von Autorisierungsdaten abhängt, erzielen Sie mit diesem Ansatz die bestmögliche Leistung.

Für angemeldete Benutzer enthält die Antwort ein JSON-Clientprinzipalobjekt. Für Anforderungen von nicht authentifizierten Benutzern wird null zurückgegeben.

Mithilfe der Fetch¹-API können Sie unter Verwendung der folgenden Syntax auf die Clientprinzipaldaten zugreifen:

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-Funktionen

Die API-Funktionen, die in Static Web Apps über das Azure Functions-Back-End verfügbar sind, haben Zugriff auf dieselben Benutzerinformationen wie eine Clientanwendung, mit Ausnahme des claims-Arrays. Die API erhält zwar benutzerbezogene Informationen, führt aber keine eigenen Überprüfungen durch, ob der Benutzer authentifiziert ist oder ob sie einer erforderlichen Rolle entsprechen. Zugriffssteuerungsregeln werden in der Datei staticwebapp.config.json definiert.

JavaScript

Clientprinzipaldaten werden im Anforderungsheader x-ms-client-principal an API-Funktionen übergeben. Die Clientprinzipaldaten werden als Base64-codierte Zeichenfolge gesendet, die ein serialisiertes JSON-Objekt enthält.

Die folgende Beispielfunktion zeigt, wie Benutzerinformationen gelesen und zurückgegeben werden:

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

Mithilfe der Fetch¹-Browser-API können Sie unter Verwendung der folgenden Syntax auf die Antwort der API zugreifen. In diesem Beispiel wird davon ausgegangen, dass die obige Funktion user heißt:

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

console.log(await getUser());

C#

In einer C#-Funktion sind die Benutzerinformationen aus dem x-ms-client-principal-Header verfügbar, den Ihre App in ein ClaimsPrincipal-Objekt oder Ihren eigenen benutzerdefinierten Typ deserialisieren kann. Der folgende Code zeigt, wie der Header in einen Zwischentyp, ClientPrincipal, entpackt wird, der dann in eine ClaimsPrincipal-Instanz umgewandelt wird.

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

Wenn ein Benutzer angemeldet ist, wird der Header x-ms-client-principal den Anforderungen für Benutzerinformationen über die Static Web Apps Edgeknoten hinzugefügt.

Hinweis

Der x-ms-client-principal-Header, auf den in der API-Funktion zugegriffen werden kann, enthält das claims-Array nicht.

¹ Die fetch-API und der Operator await werden in Internet Explorer nicht unterstützt.

Nächste Schritte

Konfigurieren von App-Einstellungen