Añade autenticación a tu aplicación .NET Core (MVC)

tip

La siguiente demostración está construida sobre .NET Core 8.0. El SDK es compatible con .NET 6.0 o superior.
Los proyectos de ejemplo de .NET Core están disponibles en el repositorio de GitHub.

Prerrequisitos

Una cuenta de Logto Cloud o un Logto autoalojado.
Una aplicación web tradicional de Logto creada.

Instalación

Añade el paquete NuGet a tu proyecto:

dotnet add package Logto.AspNetCore.Authentication

Integración

Añadir autenticación de Logto

Abre Startup.cs (o Program.cs) y añade el siguiente código para registrar los servicios de autenticación de Logto:

Program.cs
using Logto.AspNetCore.Authentication;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddLogtoAuthentication(options =>
{
  options.Endpoint = builder.Configuration["Logto:Endpoint"]!;
  options.AppId = builder.Configuration["Logto:AppId"]!;
  options.AppSecret = builder.Configuration["Logto:AppSecret"];
});

El método AddLogtoAuthentication hará lo siguiente:

Establecer el esquema de autenticación predeterminado en LogtoDefaults.CookieScheme.
Establecer el esquema de desafío predeterminado en LogtoDefaults.AuthenticationScheme.
Establecer el esquema de cierre de sesión predeterminado en LogtoDefaults.AuthenticationScheme.
Añadir manejadores de autenticación de cookies y OpenID Connect al esquema de autenticación.

Flujos de inicio y cierre de sesión

Antes de continuar, hay dos términos confusos en el middleware de autenticación de .NET Core que necesitamos aclarar:

CallbackPath: El URI al que Logto redirigirá al usuario después de que haya iniciado sesión (el "URI de redirección" en Logto)
RedirectUri: El URI al que se redirigirá después de que se hayan realizado las acciones necesarias en el middleware de autenticación de Logto.

El proceso de inicio de sesión se puede ilustrar de la siguiente manera:

De manera similar, .NET Core también tiene SignedOutCallbackPath y RedirectUri para el flujo de cierre de sesión.

Para mayor claridad, nos referiremos a ellos de la siguiente manera:

Término que usamos	Término de .NET Core
URI de redirección de Logto	CallbackPath
URI de redirección post cierre de sesión de Logto	SignedOutCallbackPath
URI de redirección de la aplicación	RedirectUri

Sobre el inicio de sesión basado en redirección

Este proceso de autenticación sigue el protocolo OpenID Connect (OIDC), y Logto aplica medidas de seguridad estrictas para proteger el inicio de sesión del usuario.
Si tienes múltiples aplicaciones, puedes usar el mismo proveedor de identidad (Logto). Una vez que el usuario inicia sesión en una aplicación, Logto completará automáticamente el proceso de inicio de sesión cuando el usuario acceda a otra aplicación.

Para aprender más sobre la lógica y los beneficios del inicio de sesión basado en redirección, consulta Experiencia de inicio de sesión de Logto explicada.

Configurar URIs de redirección

nota

En los siguientes fragmentos de código, asumimos que tu aplicación está ejecutándose en http://localhost:3000/.

Primero, configuremos el URI de redirección de Logto. Agrega el siguiente URI a la lista de "URIs de redirección" en la página de detalles de la aplicación Logto:

http://http://localhost:3000//Callback

Para configurar el URI de redirección posterior al cierre de sesión de Logto, agrega el siguiente URI a la lista de "URIs de redirección posterior al cierre de sesión" en la página de detalles de la aplicación Logto:

http://http://localhost:3000//SignedOutCallback

Cambiar las rutas predeterminadas

El URI de redirección de Logto tiene una ruta predeterminada de /Callback, y el URI de redirección posterior al cierre de sesión de Logto tiene una ruta predeterminada de /SignedOutCallback.

Puedes dejarlos tal como están si no hay un requisito especial. Si deseas cambiarlo, puedes establecer la propiedad CallbackPath y SignedOutCallbackPath para LogtoOptions:

Program.cs
builder.Services.AddLogtoAuthentication(options =>
{
  // Otras configuraciones...
  options.CallbackPath = "/Foo";
  options.SignedOutCallbackPath = "/Bar";
});

Recuerda actualizar el valor en la página de detalles de la aplicación Logto en consecuencia.

Implementar botones de inicio y cierre de sesión

Primero, añade métodos de acciones a tu Controller, por ejemplo:

Controllers/HomeController.cs
public class HomeController : Controller
{
  public IActionResult SignIn()
  {
    // Esto redirigirá al usuario a la página de inicio de sesión de Logto.
    return Challenge(new AuthenticationProperties { RedirectUri = "/" });
  }

  // Usa la palabra clave `new` para evitar conflictos con el método `ControllerBase.SignOut`
  new public IActionResult SignOut()
  {
    // Esto limpiará la cookie de autenticación y redirigirá al usuario a la página de cierre de sesión de Logto
    // para limpiar también la sesión de Logto.
    return SignOut(new AuthenticationProperties { RedirectUri = "/" });
  }
}

Luego, añade los enlaces a tu Vista:

Views/Home/Index.cshtml
<p>Está autenticado: @User.Identity?.IsAuthenticated</p>
@if (User.Identity?.IsAuthenticated == true) {
  <a asp-controller="Home" asp-action="SignOut">Cerrar sesión</a>
} else {
  <a asp-controller="Home" asp-action="SignIn">Iniciar sesión</a>
}

Mostrará el enlace "Iniciar sesión" si el usuario no está autenticado, y mostrará el enlace "Cerrar sesión" si el usuario está autenticado.

Punto de control: Prueba tu aplicación

Ahora, puedes probar tu aplicación:

Ejecuta tu aplicación, verás el botón de inicio de sesión.
Haz clic en el botón de inicio de sesión, el SDK iniciará el proceso de inicio de sesión y te redirigirá a la página de inicio de sesión de Logto.
Después de iniciar sesión, serás redirigido de vuelta a tu aplicación y verás el botón de cierre de sesión.
Haz clic en el botón de cierre de sesión para limpiar el almacenamiento local y cerrar sesión.

Obtener información del usuario

Mostrar información del usuario

Para saber si el usuario está autenticado, puedes verificar la propiedad User.Identity?.IsAuthenticated.

Para obtener los reclamos del perfil del usuario, puedes usar la propiedad User.Claims:

Controllers/HomeController.cs
var claims = User.Claims;

// Obtener el ID del usuario
var userId = claims.FirstOrDefault(c => c.Type == LogtoParameters.Claims.Subject)?.Value;

Consulta LogtoParameters.Claims para la lista de nombres de reclamos y sus significados.

Solicitar reclamos adicionales

Es posible que encuentres que falta alguna información del usuario en el objeto devuelto desde User.Claims. Esto se debe a que OAuth 2.0 y OpenID Connect (OIDC) están diseñados para seguir el principio de privilegio mínimo (PoLP), y Logto está construido sobre estos estándares.

De forma predeterminada, se devuelven reclamos limitados. Si necesitas más información, puedes solicitar alcances adicionales para acceder a más reclamos.

info

Un "reclamo (Claim)" es una afirmación hecha sobre un sujeto; un "alcance (Scope)" es un grupo de reclamos. En el caso actual, un reclamo es una pieza de información sobre el usuario.

Aquí tienes un ejemplo no normativo de la relación alcance - reclamo:

tip

El reclamo "sub" significa "sujeto", que es el identificador único del usuario (es decir, el ID del usuario).

El SDK de Logto siempre solicitará tres alcances: openid, profile y offline_access.

Para solicitar alcances adicionales, puedes configurar la propiedad Scopes en el objeto options:

Program.cs
builder.Services.AddLogtoAuthentication(options =>
{
  // ...
  options.Scopes = new string[] {
    LogtoParameters.Scopes.Email,
    LogtoParameters.Scopes.Phone
  }
});

Luego puedes acceder a los reclamos adicionales a través de User.Claims:

Controllers/HomeController.cs
var claims = User.Claims;

// Obtener el correo electrónico del usuario
var email = claims.FirstOrDefault(c => c.Type == LogtoParameters.Claims.Email)?.Value;

Reclamos que necesitan solicitud de red

Para evitar sobrecargar el objeto de usuario, algunos reclamos requieren solicitudes de red para ser obtenidos. Por ejemplo, el reclamo custom_data no se incluye en el objeto de usuario incluso si se solicita en los alcances. Para obtener estos reclamos, puedes establecer GetClaimsFromUserInfoEndpoint en true en el objeto options:

Program.cs
builder.Services.AddLogtoAuthentication(options =>
{
  // ...
  options.GetClaimsFromUserInfoEndpoint = true;
});

Alcances y reclamos

Logto utiliza las convenciones de alcances y reclamos (scopes and claims) de OIDC para definir los alcances y reclamos para obtener información del usuario del Token de ID y del endpoint userinfo de OIDC. Tanto "alcance" como "reclamo" son términos de las especificaciones de OAuth 2.0 y OpenID Connect (OIDC).

Aquí está la lista de alcances (Scopes) soportados y los reclamos (Claims) correspondientes:

openid

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
sub	`string`	El identificador único del usuario	No

profile

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
name	`string`	El nombre completo del usuario	No
username	`string`	El nombre de usuario del usuario	No
picture	`string`	URL de la foto de perfil del usuario final. Esta URL DEBE referirse a un archivo de imagen (por ejemplo, un archivo de imagen PNG, JPEG o GIF), en lugar de a una página web que contenga una imagen. Ten en cuenta que esta URL DEBERÍA referirse específicamente a una foto de perfil del usuario final adecuada para mostrar al describir al usuario final, en lugar de una foto arbitraria tomada por el usuario final.	No
created_at	`number`	Momento en que se creó el usuario final. El tiempo se representa como el número de milisegundos desde la época Unix (1970-01-01T00:00:00Z).	No
updated_at	`number`	Momento en que se actualizó por última vez la información del usuario final. El tiempo se representa como el número de milisegundos desde la época Unix (1970-01-01T00:00:00Z).	No

Otros reclamos estándar incluyen family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo y locale también se incluirán en el alcance profile sin necesidad de solicitar el endpoint de userinfo. Una diferencia en comparación con los reclamos anteriores es que estos reclamos solo se devolverán cuando sus valores no estén vacíos, mientras que los reclamos anteriores devolverán null si los valores están vacíos.

nota

A diferencia de los reclamos estándar, los reclamos created_at y updated_at utilizan milisegundos en lugar de segundos.

email

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
email	`string`	La dirección de correo electrónico del usuario	No
email_verified	`boolean`	Si la dirección de correo electrónico ha sido verificada	No

phone

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
phone_number	`string`	El número de teléfono del usuario	No
phone_number_verified	`boolean`	Si el número de teléfono ha sido verificado	No

address

Por favor, consulta el OpenID Connect Core 1.0 para los detalles del reclamo de dirección.

custom_data

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
custom_data	`object`	Los datos personalizados del usuario	Sí

identities

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
identities	`object`	Las identidades vinculadas del usuario	Sí
sso_identities	`array`	Las identidades SSO vinculadas del usuario	Sí

urn:logto:scope:organizations

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
organizations	`string[]`	Los IDs de las organizaciones a las que pertenece el usuario	No
organization_data	`object[]`	Los datos de las organizaciones a las que pertenece el usuario	Sí

urn:logto:scope:organization_roles

Nombre del reclamo	Tipo	Descripción	¿Necesita userinfo?
organization_roles	`string[]`	Los roles de organización a los que pertenece el usuario con el formato `<organization_id>:<role_name>`	No

Considerando el rendimiento y el tamaño de los datos, si "¿Necesita userinfo?" es "Sí", significa que el reclamo no aparecerá en el Token de ID, pero se devolverá en la respuesta del endpoint de userinfo.

Recursos de API

Recomendamos leer primero 🔐 Control de acceso basado en roles (RBAC) para entender los conceptos básicos de Logto RBAC y cómo configurar correctamente los recursos de API.

Configurar recurso de API en tu aplicación

Una vez que hayas configurado los recursos de API, puedes agregarlos al configurar Logto en tu aplicación:

Program.cs
builder.Services.AddLogtoAuthentication(options =>
{
  // ...
  options.Resource = "https://<your-api-resource-indicator>";
});

Cada recurso de API tiene sus propios permisos (alcances).

Por ejemplo, el recurso https://shopping.your-app.com/api tiene los permisos shopping:read y shopping:write, y el recurso https://store.your-app.com/api tiene los permisos store:read y store:write.

Para solicitar estos permisos, puedes agregarlos al configurar Logto en tu aplicación:

Program.cs
builder.Services.AddLogtoAuthentication(options =>
{
  // ...
  options.Resource = "https://shopping.your-app.com/api";
  options.Scopes = new string[] {
    "openid",
    "profile",
    "offline_access",
    "read",
    "write"
  };
});

Puedes notar que los alcances se definen por separado de los recursos de API. Esto se debe a que Resource Indicators for OAuth 2.0 especifica que los alcances finales para la solicitud serán el producto cartesiano de todos los alcances en todos los servicios objetivo.

nota

Está bien solicitar alcances que no están definidos en los recursos de API. Por ejemplo, puedes solicitar el alcance email incluso si los recursos de API no tienen el alcance email disponible. Los alcances no disponibles serán ignorados de manera segura.

Después de un inicio de sesión exitoso, Logto emitirá los alcances apropiados a los recursos de API de acuerdo con los roles del usuario.

Obtener tokens

A veces puede que necesites obtener el token de acceso o el token de ID para llamadas de API. Puedes usar el método GetTokenAsync para obtener los tokens:

var accessToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.AccessToken);
var idToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.IdToken);

No necesitas preocuparte por la expiración del token, el middleware de autenticación actualizará automáticamente los tokens cuando sea necesario.

precaución

Aunque el middleware de autenticación actualizará automáticamente los tokens, los reclamos en el objeto de usuario no se actualizarán debido a la limitación del controlador de autenticación subyacente de OpenID Connect. Esto se puede resolver una vez que escribamos nuestro propio controlador de autenticación.

Ten en cuenta que el token de acceso mencionado es un token opaco para el endpoint de userinfo en OpenID Connect, que no es un token JWT. Si has especificado el recurso de API, necesitas usar LogtoParameters.Tokens.AccessTokenForResource para obtener el token de acceso para el recurso de API:

var accessToken = await HttpContext.GetTokenAsync(LogtoParameters.Tokens.AccessTokenForResource);

Este token será un token JWT con el recurso de API como la audiencia.

Lecturas adicionales

Flujos de usuario final: flujos de autenticación, flujos de cuenta y flujos de organización Configurar conectores Protege tu API

Prerrequisitos​

Instalación​

Integración​

Añadir autenticación de Logto​

Flujos de inicio y cierre de sesión​

Configurar URIs de redirección​

Cambiar las rutas predeterminadas​

Implementar botones de inicio y cierre de sesión​

Punto de control: Prueba tu aplicación​

Obtener información del usuario​

Mostrar información del usuario​

Solicitar reclamos adicionales​

Reclamos que necesitan solicitud de red​

Alcances y reclamos​

Recursos de API​

Configurar recurso de API en tu aplicación​

Obtener tokens​

Lecturas adicionales​

Prerrequisitos

Instalación

Integración

Añadir autenticación de Logto

Flujos de inicio y cierre de sesión

Configurar URIs de redirección

Cambiar las rutas predeterminadas

Implementar botones de inicio y cierre de sesión

Punto de control: Prueba tu aplicación

Obtener información del usuario

Mostrar información del usuario

Solicitar reclamos adicionales

Reclamos que necesitan solicitud de red

Alcances y reclamos

Recursos de API

Configurar recurso de API en tu aplicación

Obtener tokens

Lecturas adicionales