Uso de Identity para proteger un back-end de API web para SPA

ASP.NET Core Identity proporciona API que controlan la autenticación, la autorización y la administración de identidades. Las API permiten proteger los puntos de conexión de un back-end de API web con autenticación basada en cookie. Existe una opción basada en tokens para los clientes que no pueden usar cookie.

En este artículo se muestra cómo usar Identity para proteger un back-end de API web para SPA como aplicaciones de Angular, React y Vue. Las mismas API de back-end se pueden usar para proteger aplicaciones Blazor WebAssembly.

Requisitos previos

Los pasos que se muestran en este artículo agregan autenticación y autorización a una aplicación de API web principal de ASP.NET que:

• Aún no está configurado para la autenticación.
• Tiene como destino net8.0 o una versión posterior.
• Puede ser una API mínima o una API basada en controladores.

Algunas de las instrucciones de prueba de este artículo usan la interfaz de usuario de Swagger que se incluye con la plantilla de proyecto. La interfaz de usuario de Swagger no es necesaria para usarIdentity con un back-end de API web.

Instalación de paquetes NuGet

Instale los siguientes paquetes NuGet:

• Microsoft.AspNetCore.Identity.EntityFrameworkCore: permite que Identity trabaje con Entity Framework Core (EF Core).
• Uno que permite que EF Core trabaje con una base de datos, como uno de los siguientes paquetes:
  • Microsoft.EntityFrameworkCore.SqlServer o
  • Microsoft.EntityFrameworkCore.Sqlite o
  • Microsoft.EntityFrameworkCore.InMemory.

Para obtener la forma más rápida de empezar, use la base de datos en memoria.

Cambie la base de datos más adelante a SQLite o SQL Server para guardar los datos de usuario entre sesiones al realizar pruebas o para su uso en producción. Esto presenta cierta complejidad en comparación con la memoria, ya que requiere que la base de datos se cree a través de migraciones, como se muestra en el EF Core tutorial de introducción.

Instale estos paquetes mediante el administrador de paquetes NuGet en Visual Studio o el comando de la CLI dotnet add package.

Cree una clave privada RSA IdentityDbContext.

Agregue una clase denominada ApplicationDbContext que herede 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)
    { }
}

El código que se muestra proporciona un constructor especial que permite configurar la base de datos para distintos entornos.

Agregue una o varias de las siguientes directivas using según sea necesario al agregar el código que se muestra en estos pasos.

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

Configuración del contexto EF Core

Como ya se ha indicado anteriormente, la manera más sencilla de empezar es usar la base de datos en memoria. Con la memoria, cada ejecución comienza con una base de datos nueva y no es necesario usar migraciones. Después de la llamada a WebApplication.CreateBuilder(args), agregue el código siguiente a fin de configurar Identity para que use una base de datos en memoria:

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

Para guardar los datos de usuario entre sesiones al realizar pruebas o para su uso en producción, cambie la base de datos más adelante a SQLite o SQL Server.

Adición de servicios Identity al contenedor

Después de la llamada a WebApplication.CreateBuilder(args), llame a AddAuthorization para agregar servicios al contenedor de inserción de dependencias (DI):

builder.Services.AddAuthorization();

Activación de las API de Identity

Después de la llamada a WebApplication.CreateBuilder(args), llame a AddIdentityApiEndpoints<TUser>(IServiceCollection) y a AddEntityFrameworkStores<TContext>(IdentityBuilder).

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

De forma predeterminada, se activan los tokens cookie y de propiedad. Cookies y tokens se emiten al iniciar sesión si el parámetro de cadena de consulta useCookies en el punto de conexión de inicio de sesión es true.

Asignación de rutas Identity

Después de la llamada a builder.Build(), llame a MapIdentityApi<TUser>(IEndpointRouteBuilder) para asignar los puntos de conexión Identity:

app.MapIdentityApi<IdentityUser>();

Protección de los puntos de conexión seleccionados

Para proteger un punto de conexión, use el método de extensión RequireAuthorization en la llamada Map{Method} que define la ruta. Por ejemplo:

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

El método RequireAuthorization también se puede usar para:

• Proteger los puntos de conexión de la interfaz de usuario de Swagger, como se muestra en el siguiente ejemplo:

  app.MapSwagger().RequireAuthorization();
  

• Proteger con una notificación o permiso específicos, como se muestra en el siguiente ejemplo:

  .RequireAuthorization("Admin");
  

En un proyecto de API web basado en controlador, proteja los puntos de conexión aplicando el atributo [Authorize] a un controlador o a una acción.

Prueba de la API

Una manera rápida de probar la autenticación es usar la base de datos en memoria y la interfaz de usuario de Swagger que se incluye con la plantilla de proyecto. Los pasos siguientes muestran cómo probar la API con la interfaz de usuario de Swagger. Asegúrese de que los puntos de conexión de la interfaz de usuario de Swagger no están protegidos.

Intento de acceso a un punto de conexión protegido

• Ejecute la aplicación y vaya a la interfaz de usuario de Swagger.
• Expanda un punto de conexión protegido, como /weatherforecast en un proyecto creado por la plantilla de API web.
• Haga clic en Probar.
• Seleccione Execute(Ejecutar). La respuesta es 401 - not authorized.

Registro de pruebas

• Expanda /register y seleccione Pruébelo.

• En la sección Parámetros de la interfaz de usuario, se muestra un cuerpo de solicitud de ejemplo:

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

• Reemplace "string" por una dirección de correo electrónico y una contraseña válidas y, a continuación, seleccione Ejecutar.

  Para cumplir las reglas de validación de contraseña predeterminadas, la contraseña debe tener al menos seis caracteres y contener al menos uno de los siguientes caracteres:

  • Letra en mayúscula
  • Letra en minúscula
  • Dígito numérico
  • Carácter no alfanumérico

  Si escribe una dirección de correo electrónico no válida o una contraseña incorrecta, el resultado incluirá los errores de validación. Este es un ejemplo de un cuerpo de respuesta con errores de validación:

  {
    "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')."
      ]
    }
  }
  

  Los errores se devuelven en el formato ProblemDetails para que el cliente pueda analizarlos y mostrar los errores de validación según sea necesario.

  Un registro correcto da como resultado una respuesta 200 - OK.

Prueba del inicio de sesión

• Expanda /login y seleccione Pruébelo. El cuerpo de la solicitud de ejemplo muestra dos parámetros adicionales:

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

  Las propiedades JSON adicionales no son necesarias para este ejemplo y se pueden eliminar. Establezca useCookies en true.

• Reemplace "string" por la dirección de correo electrónico y la contraseña que usó para registrarse y, a continuación, seleccione Ejecutar.

  Un inicio de sesión correcto da como resultado una respuesta 200 - OK con un elemento cookie el encabezado de respuesta.

Volver a probar el punto de conexión protegido

Después de un inicio de sesión correcto, vuelva a ejecutar el punto de conexión protegido. La autenticación cookie se envía automáticamente con la solicitud y el punto de conexión se autoriza. La autenticación basada en Cookie está integrada en el explorador y "simplemente funciona".

Prueba con clientes que no son de explorador

Es posible que algunos clientes web no incluyan cookie en el encabezado de forma predeterminada:

• Si usa una herramienta para probar las API, es posible que tenga que habilitar cookie en la configuración.

• La API de JavaScript fetch no incluye cookie de forma predeterminada. Habilítelos estableciendo credentials en el valor include de las opciones.

• Un elemento de HttpClient ejecutándose en una aplicación Blazor WebAssembly necesita HttpRequestMessage para incluir credenciales, como el siguiente ejemplo:

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

Uso de la autenticación basada en tokens

Para los clientes que no admiten cookie, la API de inicio de sesión proporciona un parámetro para solicitar tokens. Se emite un token personalizado (uno que es propiedad de la plataforma de identidad de ASP.NET Core) que se puede usar para autenticar las solicitudes posteriores. El token se pasa en el encabezado Authorization como token de portador. También se proporciona un token de actualización. Este token permite a la aplicación solicitar un nuevo token cuando expira el antiguo sin forzar al usuario a iniciar sesión de nuevo.

Los tokens no son JStokens web ON estándar (JWT). El uso de tokens personalizados es intencional, ya que la API integrada Identity está pensada principalmente para escenarios simples. La opción de token no está pensada para ser un proveedor de servicios de identidad completo o un servidor de tokens, sino una alternativa a la opción cookie para los clientes que no pueden usar cookie.

Para usar la autenticación basada en tokens, establezca el parámetro de cadena de consulta useCookies en false al llamar al punto de conexión de /login. Los tokens usan el esquema de autenticación portador de. El uso del token devuelto desde la llamada a /login, las llamadas posteriores a los puntos de conexión protegidos deben agregar el encabezado Authorization: Bearer <token> donde <token> es el token de acceso. Para obtener más información, consulte Uso del punto de conexión de POST /login más adelante en este artículo.

Cerrar la sesión

Para proporcionar una manera de que el usuario cierre la sesión, defina un punto de conexión /logout como el siguiente ejemplo:

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

Proporcione un objeto JSON vacío ({}) en el cuerpo de la solicitud al llamar a este punto de conexión. El siguiente código es un ejemplo de una llamada al punto de conexión de cierre de sesión:

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

Puntos de conexión de MapIdentityApi<TUser>

La llamada a MapIdentityApi<TUser> agrega los siguientes puntos de conexión a la aplicación:

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

Uso del punto de conexión de POST /register

El cuerpo de la solicitud debe tener las propiedades Email y Password:

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

Para más información, vea:

• Pruebe el registro anteriormente en este artículo.
• RegisterRequest.

Uso del punto de conexión de POST /login

En el cuerpo de la solicitud, Email y Password son necesarios. Si la autenticación en dos fases (2FA) está habilitada, se requiere TwoFactorCode o TwoFactorRecoveryCode. Si 2FA no está habilitado, omita twoFactorCode y twoFactorRecoveryCode. Para obtener más información, consulte Uso del punto de conexión de POST /manage/2fa más adelante en este artículo.

Este es un ejemplo de cuerpo de solicitud con 2FA sin habilitar:

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

Estos son ejemplos del cuerpo de la solicitud con 2FA habilitado:

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

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

El punto de conexión espera un parámetro de cadena de consulta:

• useCookies - Se establece en true para la autenticación basada en cookie. Establezca false u omita para la autenticación basada en tokens.

Para obtener más información sobre la autenticación basada en cookie, consulte Probar el inicio de sesión, mencionado previamente en este artículo.

Autenticación basada en tokens

Si useCookies es false o se omite, se habilita la autenticación basada en token. El cuerpo de la respuesta incluye las siguientes propiedades:

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

Para obtener más información acerca de estas propiedades, consulte AccessTokenResponse.

Coloque el token de acceso en un encabezado para realizar solicitudes autenticadas, como se muestra en el siguiente ejemplo

Authorization: Bearer {access token}

Cuando el token de acceso esté a punto de expirar, llame al punto de conexión /refresh.

Uso del punto de conexión de POST /refresh

Solo para uso con autenticación basada en token. Obtiene un nuevo token de acceso sin forzar al usuario a iniciar sesión de nuevo. Llame a este punto de conexión cuando el token de acceso esté a punto de expirar.

El cuerpo de la solicitud contiene solo el RefreshToken. Este es un ejemplo de cuerpo de solicitud:

{
  "refreshToken": "string"
}

Si la llamada se realiza correctamente, el cuerpo de la respuesta es un nuevo AccessTokenResponse, como se muestra en el siguiente ejemplo:

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

Uso del punto de conexión de GET /confirmEmail

Si Identity está configurado para la confirmación por correo electrónico, una llamada correcta al punto de conexión de /register envía un correo electrónico que contiene un vínculo al punto de conexión de /confirmEmail. El vínculo contiene los siguientes parámetros de cadena de consulta:

• userId
• code
• changedEmail: solo se incluye si el usuario cambió la dirección de correo electrónico durante el registro.

De forma predeterminada, el asunto del correo electrónico es "Confirmación por correo electrónico" y el cuerpo del correo electrónico es similar al siguiente ejemplo:

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

Si la propiedad RequireConfirmedEmail está establecida en true, el usuario no puede iniciar sesión hasta que se confirme la dirección de correo electrónico haciendo clic en el vínculo del correo electrónico. El punto de conexión de /confirmEmail:

• Confirma la dirección de correo electrónico y permite al usuario iniciar sesión.
• Devuelve el texto "Gracias por confirmar el correo electrónico" en el cuerpo de la respuesta.

Para configurar Identity para la confirmación por correo electrónico, agregue código en Program.cs para establecer RequireConfirmedEmail en true y agregue una clase que implemente IEmailSender en el contenedor de inserción de dependencias. Por ejemplo:

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

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

En el ejemplo anterior, EmailSender es una clase que implementa IEmailSender. Para obtener más información, incluido un ejemplo de una clase que implementa IEmailSender, consulte Confirmación de la cuenta y recuperación de contraseñas en ASP.NET Core.

Uso del punto de conexión de POST /resendConfirmationEmail

Envía un correo electrónico solo si la dirección es válida para un usuario registrado.

El cuerpo de la solicitud contiene solo el Email. Este es un ejemplo de cuerpo de solicitud:

{
  "email": "string"
}

Para obtener más información, consulte Uso del punto de conexión de GET /confirmEmail mencionado previamente en este artículo.

Uso del punto de conexión de POST /forgotPassword

Genera un correo electrónico que contiene un código de restablecimiento de contraseña. Envíe ese código a /resetPassword con una nueva contraseña.

El cuerpo de la solicitud contiene solo el Email. Este es un ejemplo:

{
  "email": "string"
}

Para obtener información sobre cómo habilitar Identity para enviar correos electrónicos, consulte Uso del punto de conexión de GET /confirmEmail.

Uso del punto de conexión de POST /resetPassword

Llame a este punto de conexión después de obtener un código de restablecimiento llamando al punto de conexión de /forgotPassword.

El cuerpo de la solicitud requiere Email, ResetCode y NewPassword. Este es un ejemplo:

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

Uso del punto de conexión de POST /manage/2fa

Configura la autenticación en dos fases (2FA) para el usuario. Cuando se habilita 2FA, el inicio de sesión correcto requiere un código generado por una aplicación autenticadora además de la dirección de correo electrónico y la contraseña.

Habilitación de la autenticación en dos fases

Para habilitar 2FA para el usuario autenticado actualmente:

• Llame al punto de conexión de /manage/2fa y envíe un JSobjeto ON ({}) vacío en el cuerpo de la solicitud.

• El cuerpo de la respuesta proporciona el SharedKey junto con otras propiedades que no son necesarias en este momento. La clave compartida se usa para configurar la aplicación autenticadora. Ejemplo de cuerpo de respuesta:

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

• Use la clave compartida para obtener una contraseña de un solo uso (TOTP) basada en tiempo. Para obtener más información, consulte Habilitación de la generación de código QR para aplicaciones de autenticación TOTP en ASP.NET Core.

• Llame al punto de conexión de /manage/2fa y envíe TOTP y "enable": true en el cuerpo de la solicitud. Por ejemplo:

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

• El cuerpo de la respuesta confirma que IsTwoFactorEnabled es true y proporciona el RecoveryCodes. Los códigos de recuperación se usan para iniciar sesión cuando la aplicación autenticadora no está disponible. Ejemplo de cuerpo de respuesta después de habilitar correctamente 2FA:

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

Inicio de sesión con 2FA

Llame al punto de conexión de /login y envíe la dirección de correo electrónico, la contraseña y TOTP en el cuerpo de la solicitud. Por ejemplo:

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

Si el usuario no tiene acceso a la aplicación autenticadora, inicie sesión llamando al punto de conexión de /login con uno de los códigos de recuperación proporcionados cuando se ha habilitado 2FA. El cuerpo de la solicitud se parece al siguiente ejemplo:

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

Restablecimiento los códigos de recuperación

Para obtener una nueva colección de códigos de recuperación, llame a este punto de conexión con ResetRecoveryCodes establecido en true. Este es un ejemplo de cuerpo de solicitud:

{
  "resetRecoveryCodes": true
}

Restablecimiento de la clave compartida

Para obtener una nueva clave compartida aleatoria, llame a este punto de conexión con ResetSharedKey establecido en true. Este es un ejemplo de cuerpo de solicitud:

{
  "resetSharedKey": true
}

Al restablecer la clave, se deshabilita automáticamente el requisito de inicio de sesión en dos fases para el usuario autenticado hasta que se vuelva a habilitar mediante una solicitud posterior.

Olvídate de la máquina

Para borrar la marca cookie "recuérdame" si está presente, llame a este punto de conexión con ForgetMachine establecido en true. Este es un ejemplo de cuerpo de solicitud:

{
  "forgetMachine": true
}

Este punto de conexión no afecta a la autenticación basada en tokens.

Uso del punto de conexión de GET /manage/info

Obtiene la dirección de correo electrónico y el estado de confirmación de correo electrónico del usuario que ha iniciado sesión. Las notificaciones se omiten de este punto de conexión por motivos de seguridad. Si se necesitan notificaciones, use las API del lado servidor para configurar un punto de conexión para las notificaciones. O bien, en lugar de compartir todas las notificaciones de los usuarios, proporcione un punto de conexión de validación que acepte una notificación y responda si el usuario lo tiene.

La solicitud no requiere ningún parámetro. El cuerpo de la respuesta incluye las propiedades Email y IsEmailConfirmed, como en el ejemplo siguiente:

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

Uso del punto de conexión de POST /manage/info

Actualiza la dirección de correo electrónico y la contraseña del usuario que ha iniciado sesión. Envíe NewEmail, NewPasswordy OldPassword en el cuerpo de la solicitud, como se muestra en el siguiente ejemplo:

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

Este es un ejemplo del cuerpo de la respuesta:

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

Consulte también

Para obtener más información, consulte los siguientes recursos:

• Elegir una solución de administración de identidades
• Soluciones de administración de Identity para aplicaciones web de .NET
• Autorización simple en ASP.NET Core
• Agregar, descargar y eliminar datos de usuario en Identity en un proyecto de ASP.NET Core
• Creación de una aplicación ASP.NET Core con datos de usuario protegidos por autorización
• Confirmación de las cuentas y recuperación de contraseñas en ASP.NET Core
• Habilitación de la generación de códigos QR para las aplicaciones de autenticación TOTP en ASP.NET Core
• Back-end de API web de ejemplo para SPA El archivo .http muestra la autenticación basada en tokens. Por ejemplo:
  • No establece useCookies
  • Usa el encabezado de autorización para pasar el token
  • Muestra la actualización para ampliar la sesión sin forzar al usuario a iniciar sesión de nuevo
• Aplicación Angular de ejemplo que usa Identity para proteger un back-end de API web