Como usar Identity para proteger um back-end da API Web para SPAs

A Identity do ASP.NET Core fornece APIs que lidam com autenticação, autorização e gerenciamento de identity. As APIs possibilitam proteger pontos de extremidade de um back-end da API Web com autenticação baseada em cookie. Uma opção baseada em token 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 em segurança. Recomendamos o uso de cookies para aplicativos baseados em navegador, pois, por padrão, o navegador os manipula automaticamente sem expô-los ao JavaScript.

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

Pré-requisitos

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

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

Algumas das instruções de testes contidas neste artigo usam a interface do usuário do Swagger que está incluída no modelo de projeto. A interface do usuário do Swagger não é necessária para usar a Identity com um back-end da Web API.

Instalar os pacotes NuGet

Instale os seguintes pacotes NuGet:

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

Para começar de maneira mais rápida, 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 ao testar ou para uso em produção. Isso introduz alguma complexidade em comparação com a memória, pois exige que o banco de dados seja criado por meio de migrações, conforme mostrado no EF Core tutorial de introdução.

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

Criar uma IdentityDbContext

Adicione uma classe nomeada 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 possibilita configurar o banco de dados para ambientes diferentes.

Adicione uma ou mais das seguintes using diretivas 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 a memória, cada execução começa com um banco de dados novo 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 a 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 ao testar ou para uso em produção, altere o banco de dados posteriormente para SQLite ou SQL Server.

Adiciona serviços Identity ao contêiner

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

builder.Services.AddAuthorization();

Ativar APIs Identity

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

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

Por padrão, os cookies e os tokens proprietários são ativados. Os cookies e tokens serão emitidos no logon se o parâmetro de useCookies da cadeia de caracteres de consulta no ponto de extremidade de logon for true.

Rotas de mapa Identity

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

app.MapIdentityApi<IdentityUser>();

Proteja os pontos de extremidade selecionados

Para proteger um ponto de extremidade, use o método de extensão RequireAuthorization na chamada 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 pontos de extremidade da interface do usuário do Swagger, conforme mostrado no exemplo a seguir:

  app.MapSwagger().RequireAuthorization();
  

• Proteger com uma declaração ou permissão específicas, conforme mostrado no exemplo a seguir:

  .RequireAuthorization("Admin");
  

Em um projeto de API Web baseado em controlador, proteja os pontos de extremidade aplicando o atributo [Authorize] a um controlador ou 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. Verifique se os pontos de extremidade da interface do usuário do Swagger não estão protegidos.

Tentar acessar um ponto de extremidade seguro

• Execute o aplicativo e navegue até a interface do usuário do Swagger.
• Expanda um ponto de extremidade protegido, como /weatherforecast em um projeto criado pelo modelo de API Web.
• Selecione Vamos experimentar.
• Selecione Executar. Observe que a resposta é 401 - not authorized.

Testar o registro

• Expanda /register e selecione Experimentar.

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

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

• Substitua "cadeia de caracteres" por um endereço de email e senha válidos e selecione Executar.

  Para cumprir as regras de validação de senha padrão, a senha deve ter pelo menos seis caracteres e conter pelo menos 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 email inválido ou uma senha inválida, 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 os erros de validação na medida do necessário.

  Um registro bem-sucedido resulta em uma resposta 200 - OK.

Testar o login

• Expanda /login e selecione Experimentar. 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. Definir useCookies para true.

• Substitua "cadeia de caracteres" pelo endereço de email e senha que você usou para registrar e selecione Executar.

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

Retestar o ponto de extremidade protegido

Após um logon bem-sucedido, execute novamente o ponto de extremidade protegido. A autenticação cookie é enviada automaticamente com a solicitação e o ponto de extremidade é autorizado. CookieA autenticação baseada em segurança é interna no navegador e "apenas funciona".

Testar com clientes que não sejam um navegador

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

• Se você estiver usando uma ferramenta para testar APIs, talvez seja necessário habilitar cookies nas configurações.

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

• Um HttpClient sendo executado em um aplicativo do Blazor WebAssembly precisa de uma HttpRequestMessage que inclua 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 navegador, pois, por padrão, o navegador os manipula automaticamente sem expô-los ao JavaScript.

Um token personalizado (proprietário da plataforma ASP.NET Core identity) é emitido e pode ser usado para autenticar solicitações subsequentes. O token é passado no cabeçalho Authorization como um token de 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 logon novamente.

Os tokens não são JWTs (Tokens JSON Web) padrão. O uso de tokens personalizados é intencional, pois a API interna Identity destina-se principalmente a cenários simples. A opção de token não pretende ser um provedor de serviço de identity ou servidor de token com todos os recursos, 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 useCookies da cadeia de caracteres de consulta como falsequando chamar o ponto de extremidade de /login. Os tokens usam o esquema de autenticação token de portador. Com o uso do 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 obter mais informações, confira Usar o ponto de extremidade POST /login mais à frente neste artigo.

Faça logoff

Para fornecer ao usuário uma maneira de se desconectar, defina um ponto de extremidade de /logout como o do 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 quando chamar esse ponto de extremidade. O código a seguir é um exemplo de uma chamada para o ponto de extremidade de logout:

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

Os pontos de extremidade de MapIdentityApi<TUser>

A chamada para MapIdentityApi<TUser> adiciona os seguintes pontos de extremidade ao aplicativo:

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

Usar o ponto de extremidade POST /register

O corpo da solicitação deve ter as propriedades Email e Password:

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

Para saber mais, veja:

• Testar o registro anteriormente neste artigo.
• RegisterRequest.

Usar o ponto de extremidade POST /login

No corpo da solicitação, serão necessários Email e Password. Se a autenticação de dois fatores (2FA) estiver habilitada, serão necessários TwoFactorCode ou TwoFactorRecoveryCode. Se a 2FA não estiver habilitada, omita tanto twoFactorCode quanto twoFactorRecoveryCode. Para obter mais informações, confira Usar o ponto de extremidade POST /manage/2fa mais à frente neste artigo.

Abaixo um exemplo do corpo da solicitação com a 2FA não habilitada:

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

Abaixo um exemplo do corpo da solicitação com a 2FA habilitada:

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

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

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

• useCookies — definido como true para a autenticação baseada em cookie. Defina como false ou omita a autenticação baseada em token.

Para obter mais informações sobre a autenticação baseada em cookie, confira Testar o login anteriormente neste artigo.

Autenticação baseada em token

Se useCookies for false ou estiver omitido, a autenticação baseada em token estará 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, confira 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 ponto de extremidade /refresh.

Usar o ponto de extremidade POST /refresh

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

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

{
  "refreshToken": "string"
}

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

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

Usar o ponto de extremidade GET /confirmEmail

Se Identity estiver configurado para confirmação por email, uma chamada bem-sucedida para o ponto de extremidade /register enviará um email 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 somente se o usuário tiver alterado o endereço de email durante o registro.

Identity fornece texto padrão para o email de confirmação. Por padrão, o assunto do email será "Confirme seu email" e o corpo do email será mais ou menos como o seguinte exemplo:

 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 antes de confirmar seu endereço de email clicando no link dentro do email. O ponto de extremidade /confirmEmail:

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

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

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

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

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

Identity fornece texto padrão para outros emails que também precisam ser enviados, como 2FA e redefinição de senha. Para personalizar esses emails, 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 implemente IEmailSender, confira Confirmação de conta e recuperação de senha no ASP.NET Core.

Usar o ponto de extremidade POST /resendConfirmationEmail

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

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

{
  "email": "string"
}

Para obter mais informações, confira Usar o ponto de extremidade GET /confirmEmail anteriormente neste artigo.

Usar o ponto de extremidade POST /forgotPassword

Gera um email contendo 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 habilitar a Identity para enviar emails, confira Usar o ponto de extremidade GET /confirmEmail.

Usar o ponto de extremidade POST /resetPassword

Chame esse ponto de extremidade após obter um código de redefinição ao chamar o ponto de extremidade /forgotPassword.

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

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

Usar o ponto de extremidade POST /manage/2fa

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

Habilitar 2FA

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

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

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

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

• Use a chave compartilhada para obter uma senha única baseada em tempo (TOTP). Para obter mais informações, confira Habilitar a geração de um código QR para aplicativos autenticadores de TOTP no ASP.NET Core.

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

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

• O corpo da resposta confirma que IsTwoFactorEnabled é verdadeiro e fornece RecoveryCodes. Os códigos de recuperação são usados para fazer login quando o aplicativo autenticador não estiver disponível. Exemplo de um corpo de resposta após habilitar a 2FA com sucesso:

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

Fazer login com 2FA

Chame o ponto de extremidade /login enviando o endereço de email, a senha e a 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, deve fazer login chamando o ponto de extremidade /login com um dos códigos de recuperação que foram fornecidos quando a 2FA foi habilitada. O corpo da solicitação é parecido com o seguinte exemplo:

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

Redefinir os códigos de recuperação

Para obter uma nova coleção de códigos de recuperação, chame esse ponto de extremidade com ResetRecoveryCodes definido como true. Abaixo um exemplo de corpo da solicitação:

{
  "resetRecoveryCodes": true
}

Redefinir a chave compartilhada

Para obter uma nova chave compartilhada aleatória, chame esse ponto de extremidade com ResetSharedKey definido como true. Abaixo um exemplo de corpo da solicitação:

{
  "resetSharedKey": true
}

Redefinir a chave desabilita automaticamente a exigência de um login com dois fatores para o usuário autenticado até que este seja habilitado novamente por uma solicitação posterior.

Esqueça o computador

Para limpar o cookie "sinalizador lembre-se de mim", caso esteja presente, chame esse ponto de extremidade com ForgetMachine definido como true. Abaixo um exemplo de corpo da solicitação:

{
  "forgetMachine": true
}

Esse ponto de extremidade não afeta a autenticação baseada em token.

Usar o ponto de extremidade GET /manage/info

Obtém o endereço de email e o status de confirmação de email do usuário conectado. As declarações foram omitidas desse ponto de extremidade por motivos de segurança. Se as declarações forem necessárias, use as APIs do lado do servidor para configurar um ponto de extremidade para declarações. Ou, em vez de compartilhar todas as declarações de 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 nenhum parâmetro. O corpo da resposta inclui as propriedades e Email e IsEmailConfirmed, como no seguinte exemplo:

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

Usar o ponto de extremidade POST /manage/info

Atualiza o endereço de email e a senha do usuário conectado. Envie NewEmail, NewPassword e 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
}

Confira também

Para saber mais, consulte os recursos a seguir:

• Escolha uma solução de gerenciamento de identity
• Soluções de gerenciamento de para aplicativos Web do .NETIdentity
• Autorização simples no ASP.NET Core
• Adicione, baixe e exclua dados do usuário para Identity em um projeto ASP.NET Core
• Criar um aplicativo ASP.NET Core com os dados do usuário protegidos por autorização
• Confirmação de conta e de recuperação de senha no ASP.NET Core
• Habilitar a geração de código QR para aplicativos de autenticador TOTP no ASP.NET Core
• Exemplo de back-end da API Web para SPAs O arquivo .http mostra a autenticação baseada em token. Por exemplo:
  • Não envia useCookies
  • Usa o cabeçalho autorização para passar o token
  • Mostra a atualização para estender a sessão sem forçar o usuário a fazer logon novamente
• Aplicativo Angular de exemplo que usa Identity para proteger um back-end da API Web