Acessando informações do usuário no serviço Aplicativos Web Estáticos

O serviço Aplicativos Web Estáticos do Azure fornece informações do usuário relacionadas à autenticação via um ponto de extremidade de acesso direto e para funções da API.

Muitas interfaces do usuário dependem expressivamente dos dados de autenticação de usuário. O ponto de extremidade de acesso direto é uma API utilitária que expõe informações do usuário sem a necessidade de implementar uma função personalizada. Além da conveniência, o ponto de extremidade de acesso direto não está sujeito a atrasos de inicialização a frios associados à arquitetura sem servidor.

Este artigo mostra como ler informações do usuário de um aplicativo implantado. Caso queira ler as informações do usuário emulado durante o desenvolvimento local, consulte Autorização e emulação de autenticação.

Dados da entidade de segurança do cliente.

O objeto de dados da entidade de segurança do cliente expõe informações de identificação do usuário para seu aplicativo. As propriedades a seguir são apresentadas no objeto de entidade de segurança do cliente:

Propriedade	Descrição
identityProvider	O nome do provedor de identidade.
userId	Um identificador exclusivo específico do serviço Aplicativo Web Estáticos do Azure do usuário. O valor é exclusivo por aplicativo. Por exemplo, o mesmo usuário retorna um valor userId diferente sobre um recurso diferente do serviço Aplicativos Web Estáticos. O valor persiste pelo tempo de vida de um usuário. Se você excluir e adicionar o mesmo usuário no aplicativo, um novo userId será gerado.
userDetails	Nome ou endereço de email do usuário. Alguns provedores retornam o endereço de email do usuário, enquanto outros enviam o identificador do usuário.
userRoles	Uma matriz das funções atribuídas do usuário.
claims	Uma matriz de declarações retornadas pelo seu provedor de autenticação personalizado. Acessível somente no ponto de extremidade de acesso direto.

O exemplo a seguir é de um objeto de entidade de segurança do cliente:

JSON

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

Ponto de extremidade de acesso direto

Você pode enviar uma solicitação de GET para a rota /.auth/me e receber acesso direto aos dados da entidade de segurança do cliente. Se o estado da sua exibição depender dos dados de autorização, use essa abordagem para obter o melhor desempenho.

Para usuários conectados, a resposta contém um objeto JSON da entidade de segurança do cliente. As solicitações de usuários não autenticados retornam null.

Com a API fetch¹, você pode acessar os dados da entidade de segurança do cliente usando a sintaxe a seguir.

JavaScript

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

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

Funções de API

As funções de API disponíveis em aplicativos Web estáticos por meio do back-end do Azure Functions têm acesso às mesmas informações de usuário que um aplicativo cliente, com exceção da matriz claims. Embora a API receba informações de identificação do usuário, ela não executa suas próprias verificações se o usuário é autenticado ou se corresponde a uma função necessária. As regras de controle de acesso são definidas no arquivo staticwebapp.config.json.

JavaScript

Os dados da entidade de segurança do cliente são passados para funções da API no cabeçalho da solicitação x-ms-client-principal. Os dados da entidade de segurança do cliente são enviados como uma cadeia de caracteres de codificação Base64 que contém um objeto JSON serializado.

A função de exemplo a seguir mostra como ler e retornar informações do usuário.

JavaScript

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

Supondo que a função acima seja denominada user, você pode usar a API de navegador fetch¹ para acessar a resposta da API usando a sintaxe a seguir.

JavaScript

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

console.log(await getUser());

C#

Em uma função C#, as informações do usuário estão disponíveis no cabeçalho x-ms-client-principal que seu aplicativo pode desserializar em um objeto ClaimsPrincipal ou em seu próprio tipo personalizado. O código a seguir demonstra como desempacotar o cabeçalho em um tipo intermediário, ClientPrincipal, que é então transformado em uma instância ClaimsPrincipal.

C#

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 um usuário está conectado, o cabeçalho x-ms-client-principal é adicionado às solicitações de informações do usuário por meio dos nós de borda dos Aplicativos Web Estáticos.

Observação

O cabeçalho x-ms-client-principal acessível na função de API não contém a matriz claims.

¹ A API fetch e o operador await não são compatíveis com o Internet Explorer.

Próximas etapas

Definir as configurações do aplicativo