Como usar Identity para proteger um backend de API Web para SPAs

ASP.NET Core Identity fornece APIs que lidam com autenticação, autorização e gerenciamento de identidade. As APIs permitem assegurar os terminais de um back-end de API Web com autenticação baseada em cookie. Uma opção baseada em tokens está disponível para clientes que não podem usar cookies, mas ao usá-la você é responsável por garantir que os tokens sejam mantidos seguros. Recomendamos o uso de cookies para aplicativos baseados em navegador, porque, por padrão, o navegador os manipula automaticamente sem expô-los ao JavaScript.

Este artigo mostra como usar o Identity para proteger um back-end de API da Web para SPAs como aplicativos Angular, React e Vue. As mesmas APIs de back-end podem ser usadas para proteger aplicativos Blazor WebAssembly.

Pré-requisitos

As etapas mostradas neste artigo adicionam autenticação e autorização a um aplicativo ASP.NET Core Web API que:

• Ainda não está configurado para autenticação.
• Alvos net8.0 ou posteriores.
• Pode ser API mínima ou API baseada em controlador.

Algumas das instruções de teste neste artigo usam a interface Swagger UI incluída no template de projeto. A Interface de Usuário do Swagger não é necessária para usar Identity com um back-end de API Web.

Instalar pacotes NuGet

Instale os seguintes pacotes NuGet:

• Microsoft.AspNetCore.Identity.EntityFrameworkCore - Permite que Identity trabalhem com o Entity Framework Core (EF Core).
• Um que permite que EF Core trabalhem com um banco de dados, como um dos seguintes pacotes:
  • Microsoft.EntityFrameworkCore.SqlServer ou
  • Microsoft.EntityFrameworkCore.Sqlite ou
  • Microsoft.EntityFrameworkCore.InMemory.

Para obter a maneira mais rápida de começar, use o banco de dados na memória.

Altere o banco de dados posteriormente para SQLite ou SQL Server para salvar dados do usuário entre sessões durante o teste ou para uso em produção. Isso introduz alguma complexidade em comparação com o armazenamento em memória, pois requer que o banco de dados seja criado por meio de migrações , como mostrado no tutorial de introdução EF Core.

Instale esses pacotes usando o gerenciador de pacotes NuGet no Visual Studio ou o comando dotnet add package CLI.

Criar um IdentityDbContext

Adicione uma classe chamada ApplicationDbContext que herda de IdentityDbContext<TUser>:

using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) :
        base(options)
    { }
}

O código mostrado fornece um construtor especial que torna possível configurar o banco de dados para diferentes ambientes.

Adicione uma ou mais das seguintes diretivas using, conforme necessário, ao adicionar o código mostrado nestas etapas.

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

Configurar o contexto EF Core

Como observado anteriormente, a maneira mais simples de começar é usar o banco de dados na memória. Com in-memory, cada execução começa com um novo banco de dados e não há necessidade de usar migrações. Após a chamada para WebApplication.CreateBuilder(args), adicione o seguinte código para configurar Identity para usar um banco de dados na memória:

builder.Services.AddDbContext<ApplicationDbContext>(
    options => options.UseInMemoryDatabase("AppDb"));

Para salvar dados do usuário entre sessões durante o teste ou para uso em produção, altere o banco de dados posteriormente para SQLite ou SQL Server.

Adicionar Identity serviços ao contêiner

Após a chamada para WebApplication.CreateBuilder(args), chame AddAuthorization para adicionar serviços ao contentor de injeção de dependência (DI):

builder.Services.AddAuthorization();

Ativar Identity APIs

Após a chamada para WebApplication.CreateBuilder(args), ligue para AddIdentityApiEndpoints<TUser>(IServiceCollection) e AddEntityFrameworkStores<TContext>(IdentityBuilder).

builder.Services.AddIdentityApiEndpoints<IdentityUser>()
    .AddEntityFrameworkStores<ApplicationDbContext>();

Por padrão, tanto os cookies quanto os tokens proprietários são ativados. Cookies e tokens são emitidos no login se o parâmetro de cadeia de caracteres de consulta useCookies no ponto de extremidade de login for true.

Rotas do Mapa Identity

Após a chamada de builder.Build(), chame MapIdentityApi<TUser>(IEndpointRouteBuilder) para mapear os Identity terminais.

app.MapIdentityApi<IdentityUser>();

Proteger os pontos finais selecionados

Para proteger um endereço final, use o método de extensão RequireAuthorization durante a chamada de Map{Method} que define a rota. Por exemplo:

app.MapGet("/weatherforecast", (HttpContext httpContext) =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        })
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi()
.RequireAuthorization();

O método RequireAuthorization também pode ser usado para:

• Proteger os endpoints da interface do Swagger, conforme mostrado no exemplo a seguir:

  app.MapSwagger().RequireAuthorization();
  

• Proteja-se com uma declaração ou permissão específica, conforme mostrado no exemplo a seguir:

  .RequireAuthorization("Admin");
  

Em um projeto de API da Web baseado em controlador, proteja os pontos de extremidade aplicando o atributo [Authorize] a um controlador ou a uma ação.

Testar a API

Uma maneira rápida de testar a autenticação é usar o banco de dados na memória e a interface do usuário do Swagger incluída no modelo de projeto. As etapas a seguir mostram como testar a API com a interface do usuário do Swagger. Certifique-se de que os endpoints da IU do Swagger não estejam protegidos.

Tentar aceder a um endpoint seguro

• Execute o aplicativo e navegue até a interface do usuário do Swagger.
• Expanda um endpoint seguro, como /weatherforecast, num projeto criado pelo modelo de API web.
• Selecione Experimente.
• Selecione Executar. A resposta é 401 - not authorized.

Inscrição no teste

• Expanda /register e selecione Experimente.

• Na seção Parâmetros da interface do utilizador, um corpo de solicitação de exemplo é mostrado:

  {
    "email": "string",
    "password": "string"
  }
  

• Substitua "string" por um endereço de e-mail e senha válidos e selecione Executar.

  Para estar em conformidade com as regras de validação de senha padrão, a senha deve ter pelo menos seis caracteres e conter pelo menos um de cada um dos seguintes caracteres:

  • Letra maiúscula
  • Letra minúscula
  • Dígito numérico
  • Caractere não alfanumérico

  Se você inserir um endereço de e-mail inválido ou uma senha incorreta, o resultado incluirá os erros de validação. Aqui está um exemplo de um corpo de resposta com erros de validação:

  {
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
      "PasswordTooShort": [
        "Passwords must be at least 6 characters."
      ],
      "PasswordRequiresNonAlphanumeric": [
        "Passwords must have at least one non alphanumeric character."
      ],
      "PasswordRequiresDigit": [
        "Passwords must have at least one digit ('0'-'9')."
      ],
      "PasswordRequiresLower": [
        "Passwords must have at least one lowercase ('a'-'z')."
      ]
    }
  }
  

  Os erros são retornados no formato ProblemDetails para que o cliente possa analisá-los e exibir erros de validação, conforme necessário.

  Um registo bem-sucedido resulta numa resposta 200 - OK.

Teste de login

• Expanda /login e selecione Experimente. O corpo da solicitação de exemplo mostra dois parâmetros adicionais:

  {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
    "twoFactorRecoveryCode": "string"
  }
  

  As propriedades JSON extras não são necessárias para este exemplo e podem ser excluídas. Defina useCookies para true.

• Substitua "string" pelo endereço de e-mail e senha que você usou para se registrar e, em seguida, selecione Executar.

  Um login bem-sucedido resulta em uma resposta 200 - OK com um cookie no cabeçalho da resposta.

Teste novamente o ponto de extremidade seguro

Após um login bem-sucedido, reexecute o endpoint seguro. A autenticação cookie é enviada automaticamente com a solicitação, e a interface é autorizada. A autenticação baseada em Cookieé incorporada com segurança ao navegador e "simplesmente funciona".

Testar com clientes não baseados em navegador

Alguns clientes da Web podem não incluir cookies no cabeçalho por padrão:

• Se estiver a utilizar uma ferramenta para testar APIs, poderá ter de ativar os cookies nas definições.

• A API de fetch JavaScript não inclui cookies por padrão. Habilite-os definindo credentials para o valor include nas opções.

• Um HttpClient em execução em um aplicativo Blazor WebAssembly precisa do HttpRequestMessage para incluir credenciais, como o exemplo a seguir:

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

Usar autenticação baseada em token

Recomendamos o uso de cookies em aplicativos baseados em navegadores, porque, por padrão, o navegador os manipula automaticamente sem expô-los ao JavaScript.

É emitido um token personalizado (proprietário da plataforma de identidade ASP.NET Core) que pode ser usado para autenticar solicitações subsequentes. O token é passado no cabeçalho Authorization como um token portador. Um token de atualização também é fornecido. Esse token permite que o aplicativo solicite um novo token quando o antigo expirar sem forçar o usuário a fazer login novamente.

Os tokens não são JSON Web Tokens (JWTs) padrão. O uso de tokens personalizados é intencional, pois a API de Identity interna destina-se principalmente a cenários simples. A opção de token não se destina a ser um provedor de serviços de identidade completo ou servidor de token, mas sim uma alternativa à opção cookie para clientes que não podem usar cookies.

Para usar a autenticação baseada em token, defina o parâmetro de cadeia de caracteres de consulta useCookies como false ao chamar o ponto de extremidade /login. Os tokens usam o esquema de autenticação por portador . Usando o token retornado da chamada para /login, as chamadas subsequentes para pontos de extremidade protegidos devem adicionar o cabeçalho Authorization: Bearer <token> onde <token> é o token de acesso. Para mais informações, veja utilizer o endpoint POST /login mais adiante neste artigo.

Terminar sessão

Para fornecer uma forma de o utilizador terminar sessão, defina um ponto de extremidade /logout como no exemplo a seguir:

app.MapPost("/logout", async (SignInManager<IdentityUser> signInManager,
    [FromBody] object empty) =>
{
    if (empty != null)
    {
        await signInManager.SignOutAsync();
        return Results.Ok();
    }
    return Results.Unauthorized();
})
.WithOpenApi()
.RequireAuthorization();

Forneça um objeto JSON vazio ({}) no corpo da solicitação ao chamar esse ponto de extremidade. O código a seguir é um exemplo de uma chamada para o endpoint de logout.

public signOut() {
  return this.http.post('/logout', {}, {
    withCredentials: true,
    observe: 'response',
    responseType: 'text'

Os MapIdentityApi<TUser> pontos finais

A chamada para MapIdentityApi<TUser> adiciona os seguintes pontos de extremidade à aplicação:

• POST /register
• POST /login
• POST /refresh
• GET /confirmEmail
• POST /resendConfirmationEmail
• POST /forgotPassword
• POST /resetPassword
• POST /manage/2fa
• GET /manage/info
• POST /manage/info

Use o ponto de extremidade POST /register

O corpo do pedido deve ter as propriedades Email e Password.

{
  "email": "string",
  "password": "string",
}

Para mais informações, consulte:

• Registo de teste anteriormente neste artigo.
• RegisterRequest.

Use o ponto de extremidade POST /login

Os dados Email e Password são obrigatórios no corpo do pedido. Se a autenticação de dois fatores (2FA) estiver habilitada, será necessário TwoFactorCode ou TwoFactorRecoveryCode. Se o 2FA não estiver habilitado, omita twoFactorCode e twoFactorRecoveryCode. Para mais informações, veja utilizer o endpoint POST /manage/2fa mais adiante neste artigo.

Aqui está um exemplo de corpo de solicitação com 2FA não habilitado:

{
  "email": "string",
  "password": "string"
}

Aqui estão exemplos de corpo de solicitação com 2FA habilitado:

• {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
  }
  

• {
    "email": "string",
    "password": "string",
    "twoFactorRecoveryCode": "string"
  }
  

O ponto de extremidade espera um parâmetro de cadeia de consulta:

• useCookies - Defina como true para autenticação baseada em cookie. Defina como false ou omitir para autenticação baseada em token.

Para obter mais informações acerca da autenticação baseada em cookie, consulte a seção Teste de login na seção anterior deste artigo.

Autenticação baseada em tokens

Se useCookies é false ou omitido, a autenticação baseada em tokens é habilitada. O corpo da resposta inclui as seguintes propriedades:

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

Para obter mais informações sobre essas propriedades, consulte AccessTokenResponse.

Coloque o token de acesso em um cabeçalho para fazer solicitações autenticadas, conforme mostrado no exemplo a seguir

Authorization: Bearer {access token}

Quando o token de acesso estiver prestes a expirar, chame o endpoint /refresh.

Use o ponto de extremidade POST /refresh

Para uso somente com autenticação baseada em token. Obtém um novo token de acesso sem forçar o usuário a fazer login novamente. Chame este endpoint quando o token de acesso estiver prestes a expirar.

O corpo da solicitação contém apenas o RefreshToken. Aqui está um exemplo de corpo de solicitação:

{
  "refreshToken": "string"
}

Se a chamada for bem-sucedida, o corpo da resposta será um novo AccessTokenResponse, conforme mostrado no exemplo a seguir:

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

Use o ponto de extremidade GET /confirmEmail

Se Identity estiver configurado para confirmação de email, uma chamada bem-sucedida para o ponto de extremidade /register enviará um e-mail contendo um link para o ponto de extremidade /confirmEmail. O link contém os seguintes parâmetros de cadeia de caracteres de consulta:

• userId
• code
• changedEmail - Incluído apenas se o utilizador alterou o endereço de e-mail durante o registo.

Identity fornece texto padrão para o e-mail de confirmação. Por padrão, o assunto do e-mail é "Confirmar seu e-mail" e o corpo do e-mail se parece com o exemplo a seguir:

 Please confirm your account by <a href='https://contoso.com/confirmEmail?userId={user ID}&code={generated code}&changedEmail={new email address}'>clicking here</a>.

Se a propriedade RequireConfirmedEmail estiver definida como true, o usuário não poderá fazer login até que o endereço de e-mail seja confirmado clicando no link no e-mail. O ponto de extremidade /confirmEmail:

• Confirma o endereço de e-mail e permite que o usuário faça login.
• Devolve o texto "Obrigado por confirmar o seu e-mail." no corpo da resposta.

Para configurar Identity para confirmação de e-mail, adicione código em Program.cs definir RequireConfirmedEmail para true e adicione uma classe que implemente IEmailSender ao contêiner DI. Por exemplo:

builder.Services.Configure<IdentityOptions>(options =>
{
    options.SignIn.RequireConfirmedEmail = true;
});

builder.Services.AddTransient<IEmailSender, EmailSender>();

Para obter mais informações, consulte Confirmação de conta e recuperação de senha no ASP.NET Core.

Identity fornece texto padrão para os outros e-mails que também precisam ser enviados, como para 2FA e redefinição de senha. Para personalizar esses e-mails, forneça uma implementação personalizada da interface IEmailSender. No exemplo anterior, EmailSender é uma classe que implementa IEmailSender. Para obter mais informações, incluindo um exemplo de uma classe que implementa IEmailSender, consulte Confirmação de conta e recuperação de senha no ASP.NET Core.

Use o ponto de extremidade POST /resendConfirmationEmail

Envia um e-mail somente se o endereço for válido para um usuário registrado.

O corpo da solicitação contém apenas o Email. Aqui está um exemplo de corpo de solicitação:

{
  "email": "string"
}

Para obter mais informações, veja Uso do ponto de extremidade GET /confirmEmail anteriormente neste artigo.

Use o ponto de extremidade POST /forgotPassword

Gera um e-mail que contém um código de redefinição de senha. Envie esse código para /resetPassword com uma nova senha.

O corpo da solicitação contém apenas o Email. Aqui está um exemplo:

{
  "email": "string"
}

Para obter informações sobre como ativar Identity para enviar endereços de e-mail, consulte Utilizar o ponto final GET /confirmEmail.

Use o ponto de extremidade POST /resetPassword

Chame este endpoint depois de obter um código de redefinição chamando o endpoint /forgotPassword.

O corpo da solicitação requer Email, ResetCodee NewPassword. Aqui está um exemplo:

{
  "email": "string",
  "resetCode": "string",
  "newPassword": "string"
}

Use o ponto de extremidade POST /manage/2fa

Configura a autenticação de dois fatores (2FA) para o usuário. Quando o 2FA está ativado, o login bem-sucedido requer um código produzido por um aplicativo autenticador, além do endereço de e-mail e senha.

Ativar 2FA

Para habilitar o 2FA para o usuário autenticado no momento:

• Chame o endpoint /manage/2fa, enviando um objeto JSON vazio ({}) no corpo da solicitação.

• O corpo da resposta fornece o SharedKey juntamente com algumas outras propriedades que não são necessárias neste momento. A chave compartilhada é usada para configurar o aplicativo autenticador. Exemplo de corpo de resposta:

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 0,
    "recoveryCodes": null,
    "isTwoFactorEnabled": false,
    "isMachineRemembered": false
  }
  

• Utilize a chave partilhada para obter uma palavra-passe temporária baseada no tempo (TOTP). Para obter mais informações, consulte Habilitar a geração de código QR para aplicativos autenticadores TOTP no ASP.NET Core.

• Contacte o ponto de extremidade /manage/2fa, enviando o TOTP e "enable": true no corpo da solicitação. Por exemplo:

  {
    "enable": true,
    "twoFactorCode": "string"
  }
  

• O corpo de resposta confirma que IsTwoFactorEnabled é verdade e fornece RecoveryCodes. Os códigos de recuperação são usados para fazer login quando o aplicativo autenticador não está disponível. Exemplo de corpo de resposta depois de ativar com êxito o 2FA:

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 10,
    "recoveryCodes": [
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string"
    ],
    "isTwoFactorEnabled": true,
    "isMachineRemembered": false
  }
  

Faça login com 2FA

Chame o ponto final /login, enviando o endereço de e-mail, a palavra-passe e o TOTP no corpo da solicitação. Por exemplo:

{
  "email": "string",
  "password": "string",
  "twoFactorCode": "string"
}

Se o usuário não tiver acesso ao aplicativo autenticador, faça login chamando o ponto de extremidade /login com um dos códigos de recuperação fornecidos quando o 2FA foi habilitado. O corpo da solicitação se parece com o exemplo a seguir:

{
  "email": "string",
  "password": "string",
  "twoFactorRecoveryCode": "string"
}

Redefinir os códigos de recuperação

Para obter um novo conjunto de códigos de recuperação, utilize este endpoint com ResetRecoveryCodes definido como true. Aqui está um exemplo de corpo de solicitação:

{
  "resetRecoveryCodes": true
}

Redefinir a chave compartilhada

Para obter uma nova chave partilhada aleatória, utilize este endpoint com ResetSharedKey configurado para true. Aqui está um exemplo de corpo de solicitação:

{
  "resetSharedKey": true
}

A redefinição da chave desativa automaticamente o requisito de login de dois fatores para o usuário autenticado até que ele seja reativado por uma solicitação posterior.

Esqueça a máquina

Para limpar o cookie sinalizador "lembrar de mim", se presente, chame este endpoint com ForgetMachine definido como true. Aqui está um exemplo de corpo de solicitação:

{
  "forgetMachine": true
}

Este endpoint não tem impacto na autenticação baseada em token.

Use o ponto de extremidade GET /manage/info

Obtém o endereço de e-mail e o status de confirmação de e-mail do usuário conectado. Foram omitidas declarações desta interface por motivos de segurança. Se as reivindicações forem necessárias, use as APIs no servidor para configurar um endpoint para reivindicações. Ou, em vez de compartilhar todas as declarações dos usuários, forneça um ponto de extremidade de validação que aceite uma declaração e responda se o usuário a tem.

A solicitação não requer parâmetros. O corpo da resposta inclui as propriedades Email e IsEmailConfirmed, como no exemplo a seguir:

{
  "email": "string",
  "isEmailConfirmed": true
}

Use o ponto de extremidade POST /manage/info

Atualiza o endereço de e-mail e a senha do usuário conectado. Envie NewEmail, NewPassworde OldPassword no corpo da solicitação, conforme mostrado no exemplo a seguir:

{
  "newEmail": "string",
  "newPassword": "string",
  "oldPassword": "string"
}

Aqui está um exemplo do corpo da resposta:

{
  "email": "string",
  "isEmailConfirmed": false
}

Ver também

Para obter mais informações, consulte os seguintes recursos:

• Escolha uma solução de gerenciamento de identidades
• Soluções de gestão para aplicativos web .NET
• Autorização simples no ASP.NET Core
• Adicionar, baixar e excluir dados do usuário para Identity em um projeto ASP.NET Core
• Criar um aplicativo ASP.NET Core com dados do usuário protegidos por autorização
• Confirmação de conta e recuperação de senha no ASP.NET Core
• Habilite a geração de código QR para aplicativos autenticadores TOTP no ASP.NET Core
• Exemplo de back-end de API Web para SPAs O arquivo .http mostra a autenticação baseada em token. Por exemplo:
  • Não define useCookies
  • Usa o cabeçalho Authorization para passar o token
  • Mostra a atualização para estender a sessão sem forçar o usuário a fazer login novamente
• aplicativo Angular de exemplo que usa Identity para proteger um back-end de API Web