Toegang tot gebruikersgegevens in Azure Static Web Apps

Azure Static Web Apps biedt verificatiegerelateerde gebruikersgegevens via een eindpunt voor directe toegang en api-functies.

Veel gebruikersinterfaces zijn sterk afhankelijk van gebruikersverificatiegegevens. Het eindpunt voor directe toegang is een hulpprogramma-API waarmee gebruikersgegevens worden weergegeven zonder dat u een aangepaste functie hoeft te implementeren. Buiten het gemak is het eindpunt voor directe toegang niet onderhevig aan koude startvertragingen die zijn gekoppeld aan serverloze architectuur.

Client-principalgegevens

Client principal-gegevensobject maakt gebruikersidentificeerbare informatie beschikbaar voor uw app. De volgende eigenschappen worden weergegeven in het client-principal-object:

Eigenschappen	Beschrijving
identityProvider	De naam van de id-provider.
userId	Een azure Static Web Apps-specifieke unieke id voor de gebruiker. De waarde is uniek per app. Dezelfde gebruiker retourneert bijvoorbeeld een andere userId waarde voor een andere Static Web Apps-resource. De waarde blijft behouden voor de levensduur van een gebruiker. Als u dezelfde gebruiker verwijdert en weer toevoegt aan de app, wordt er een nieuwe userId gegenereerd.
userDetails	Gebruikersnaam of e-mailadres van de gebruiker. Sommige providers retourneren het e-mailadres van de gebruiker, terwijl anderen de gebruikershandgreep verzenden.
userRoles	Een matrix van de toegewezen rollen van de gebruiker.
claims	Een matrix met claims die worden geretourneerd door uw aangepaste verificatieprovider. Alleen toegankelijk in het eindpunt voor directe toegang.

Het volgende voorbeeld is een voorbeeld van een client-principal-object:

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

Eindpunt voor directe toegang

U kunt een GET aanvraag verzenden naar de /.auth/me route en directe toegang tot de client-principalgegevens ontvangen. Wanneer de status van uw weergave afhankelijk is van autorisatiegegevens, gebruikt u deze methode voor de beste prestaties.

Voor aangemelde gebruikers bevat het antwoord een JSON-object van de client-principal. Aanvragen van niet-geverifieerde gebruikers retourneren null.

Met behulp van de fetch¹ API hebt u toegang tot de client-principalgegevens met behulp van de volgende syntaxis.

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

De API-functies die beschikbaar zijn in Static Web Apps via de Back-end van Azure Functions, hebben toegang tot dezelfde gebruikersgegevens als een clienttoepassing, met uitzondering van de claims matrix. Hoewel de API gebruikersgegevens ontvangt, voert de API geen eigen controles uit als de gebruiker is geverifieerd of als deze overeenkomt met een vereiste rol. Regels voor toegangsbeheer worden gedefinieerd in het staticwebapp.config.json bestand.

JavaScript

Client-principalgegevens worden doorgegeven aan API-functies in de x-ms-client-principal aanvraagheader. De client-principalgegevens worden verzonden als een met Base64 gecodeerde tekenreeks die een geserialiseerd JSON-object bevat.

In de volgende voorbeeldfunctie ziet u hoe u gebruikersgegevens leest en retourneert.

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

Ervan uitgaande dat de bovenstaande functie een naam userheeft, kunt u de fetch^{1-browser-API} gebruiken om toegang te krijgen tot het antwoord van de API met behulp van de volgende syntaxis.

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 een C#-functie zijn de gebruikersgegevens beschikbaar in de x-ms-client-principal header die uw app kan deserialiseren in een ClaimsPrincipal object of uw eigen aangepaste type. De volgende code laat zien hoe u de header uitpakt in een intermediair type, ClientPrincipaldat vervolgens wordt omgezet in een ClaimsPrincipal exemplaar.

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

Wanneer een gebruiker is aangemeld, wordt de x-ms-client-principal header toegevoegd aan de aanvragen voor gebruikersgegevens via de Edge-knooppunten van Static Web Apps.

Notitie

De x-ms-client-principal header die toegankelijk is in de API-functie bevat niet de claims matrix.

¹ De ophaal-API en de wachtoperator worden niet ondersteund in Internet Explorer.

Volgende stappen

App-instellingen configureren