Accesso alle informazioni utente in App Web statiche di Azure

App Web statiche di Azure fornisce informazioni sull'utente correlate all'autenticazione tramite un endpoint di accesso diretto e a funzioni API.

Molte interfacce utente si basano principalmente sui dati di autenticazione utente. L'endpoint di accesso diretto è un'API di utilità che espone informazioni utente senza dover implementare una funzione personalizzata. Senza considerare la praticità, l'endpoint di accesso diretto non è soggetto a ritardi di avvio a freddo associati all'architettura serverless.

Dati dell'entità di sicurezza client

L'oggetto dati dell'entità di sicurezza client espone all'app le informazioni identificabili dall'utente. L'oggetto entità di sicurezza client prevede le proprietà seguenti:

Proprietà	Descrizione
identityProvider	Nome del provider di identità.
userId	Identificatore univoco specifico di App Web statiche di Azure per l'utente. Il valore è univoco in base alla singola app. Ad esempio, lo stesso utente restituisce un valore userId diverso in un'altra risorsa di App Web statiche. Il valore viene mantenuto per la durata di un utente. Se si elimina e si aggiunge di nuovo lo stesso utente all'app, viene generato un nuovo userId.
userDetails	Nome utente o indirizzo di posta elettronica dell'utente. Alcuni provider restituiscono l'indirizzo di posta elettronica dell'utente, mentre altri inviano il nome utente.
userRoles	Matrice dei ruoli assegnati dell'utente.
claims	Matrice di attestazioni restituite dal provider di autenticazione personalizzato. Accessibile solo nell'endpoint di accesso diretto.

L'esempio seguente si riferisce a un oggetto entità di sicurezza client di esempio:

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

Endpoint di accesso diretto

È possibile inviare una richiesta GET alla route /.auth/me e ricevere l'accesso diretto ai dati dell'entità di sicurezza client. Quando lo stato della visualizzazione si basa sui dati di autorizzazione, questo approccio garantisce prestazioni ottimali.

Per gli utenti connessi, la risposta contiene un oggetto entità di sicurezza client JSON. Le richieste che provengono da utenti non autenticati restituiscono null.

Usando l'API fetch¹, è possibile accedere ai dati dell'entità di sicurezza client con la sintassi seguente.

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

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

Funzioni API

Le funzioni API disponibili in App Web statiche tramite il back-end Funzioni di Azure hanno accesso alle stesse informazioni utente di un'applicazione client, ad eccezione della claims matrice. Anche se l'API riceve informazioni identificabili dall'utente, non esegue controlli personalizzati se l'utente è autenticato o se corrisponde a un ruolo obbligatorio. Le regole di controllo di accesso vengono definite nel staticwebapp.config.json file.

JavaScript

I dati dell'entità di sicurezza client vengono passati alle funzioni API nell'intestazione della richiesta x-ms-client-principal. I dati dell'entità di sicurezza client vengono inviati come stringa con codifica Base 64 che contiene un oggetto JSON serializzato.

La funzione di esempio seguente mostra come leggere e restituire informazioni utente.

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

Presupponendo che la funzione sopra indicata sia denominata user, è possibile usare l'API fetch¹ del browser per accedere alla risposta dell'API con la sintassi seguente.

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 una funzione C# le informazioni utente sono disponibili dall'intestazione x-ms-client-principal che può essere deserializzata in un ClaimsPrincipal oggetto o dal tipo personalizzato. Il codice seguente illustra come decomprimere l'intestazione in un tipo intermedio, ClientPrincipal, che viene quindi trasformato in un'istanza ClaimsPrincipal di .

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

Quando un utente è connesso, l'intestazione x-ms-client-principal viene aggiunta alle richieste di informazioni utente tramite i nodi perimetrali App Web statiche.

Nota

L'intestazione x-ms-client-principal accessibile nella funzione API non contiene la claims matrice.

¹ L'API fetch e l'operatore await non sono supportati in Internet Explorer.

Passaggi successivi

Configurare le impostazioni dell'app