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.

Beim folgenden Beispiel handelt es sich um ein exemplarisches Clientprinzipalobjekt:

{
  "identityProvider": "github",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "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 Fetch1-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;
}

console.log(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. 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.

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['x-ms-client-principal'];
  const encoded = Buffer.from(header, 'base64');
  const decoded = encoded.toString('ascii');

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

Mithilfe der Fetch1-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());

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.

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

Nächste Schritte