Añade autenticación a tu aplicación Next Auth

Esta guía te mostrará cómo integrar Logto en tu aplicación Next.js con Next Auth.

tip

• En esta guía, asumimos que has configurado Next Auth en tu proyecto Next.js. Si no lo has hecho, consulta la documentación de Next Auth para comenzar.

Prerrequisitos

• Una cuenta de Logto Cloud o un Logto autoalojado.
• Una aplicación tradicional de Logto creada.
• Un proyecto Next.js con Next Auth, consulta la documentación de Next Auth.

Integración

Configurar el proveedor de Next Auth

Antes de profundizar en los detalles, aquí tienes una visión general rápida de la experiencia del usuario final. El proceso de inicio de sesión se puede simplificar de la siguiente manera:

1. Tu aplicación invoca el método de inicio de sesión.
2. El usuario es redirigido a la página de inicio de sesión de Logto. Para aplicaciones nativas, se abre el navegador del sistema.
3. El usuario inicia sesión y es redirigido de vuelta a tu aplicación (configurada como el URI de redirección).

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

1. 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.
2. 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.

---

nota

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

Configurar URI de redirección de inicio de sesión

Vamos a cambiar a la página de detalles de la aplicación en Logto Console. Añade un URI de redirección http://localhost:3000/api/auth/callback/logto y haz clic en "Guardar cambios".

Configurar el proveedor de Next Auth

tip

Puedes encontrar y copiar el "App Secret" desde la página de detalles de la aplicación en la Consola de Administración:

Modifica la configuración de la ruta de la API de Next Auth, si estás utilizando Pages Router, el archivo está en pages/api/auth/[...nextauth].js, si estás utilizando App Router, el archivo está en app/api/auth/[...nextauth]/route.ts.

El siguiente es un ejemplo de App Router:

Next Auth v5

import NextAuth from 'next-auth';

export const {
  handlers: { GET, POST },
  signIn,
  signOut,
  auth,
} = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      type: 'oidc',
      // Puedes obtener el valor del emisor desde la página de Detalles de la Aplicación de Logto,
      // en el campo "Punto de acceso del emisor"
      issuer: 'https://xxxx.logto.app/oidc',
      clientId: '<logto-app-id>',
      clientSecret: '<logto-app-secret>',
      authorization: {
        params: { scope: 'openid offline_access profile email' },
      },
      profile(profile) {
        // Puedes personalizar el mapeo del perfil de usuario aquí
        return {
          id: profile.sub,
          name: profile.name ?? profile.username,
          email: profile.email,
          image: profile.picture,
        };
      },
    },
  ],
});

1. Reemplaza la URL del issuer con el "Punto de acceso del emisor" de tu aplicación Logto.
2. Reemplaza el clientId y el clientSecret con el ID y el secreto de tu aplicación Logto.
3. Personaliza la función profile para mapear el perfil de usuario al objeto de usuario de Next Auth, el mapeo predeterminado se muestra en el ejemplo.

Next Auth v4

import NextAuth from 'next-auth';

const handler = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      type: 'oauth',
      // Puedes obtener la URL conocida desde la página de Detalles de la Aplicación de Logto,
      // en el campo "Punto de configuración del proveedor de OpenID"
      wellKnown: 'https://xxxx.logto.app/oidc/.well-known/openid-configuration',
      authorization: { params: { scope: 'openid offline_access profile email' } },
      clientId: '<logto-app-id>',
      clientSecret: '<logto-app-secret>',
      client: {
        id_token_signed_response_alg: 'ES384',
      },
      profile(profile) {
        // Puedes personalizar el mapeo del perfil de usuario aquí
        return {
          id: profile.sub,
          name: profile.name ?? profile.username,
          email: profile.email,
          image: profile.picture,
        };
      },
    },
  ],
});

export { handler as GET, handler as POST };

1. Reemplaza la URL de wellKnown con el "Punto de configuración del proveedor de OpenID" de tu aplicación Logto.
2. Reemplaza el clientId y el clientSecret con el ID y el secreto de tu aplicación Logto.
3. Personaliza la función profile para mapear el perfil de usuario al objeto de usuario de Next Auth, el mapeo predeterminado se muestra en el ejemplo.
4. Recuerda establecer el id_token_signed_response_alg en ES384.

Punto de control

Ahora, puedes probar tu aplicación para ver si la autenticación funciona como se espera.

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).

En resumen, cuando solicitas un alcance, obtendrás los reclamos correspondientes en la información del usuario. Por ejemplo, si solicitas el alcance `email`, obtendrás los datos `email` y `email_verified` del usuario.

Por defecto, Logto SDK siempre solicitará tres alcances: `openid`, `profile` y `offline_access`, y no hay forma de eliminar estos alcances predeterminados. Pero puedes añadir más alcances al configurar Logto:

const handler = NextAuth({
  providers: [
    {
      id: 'logto',
      name: 'Logto',
      // ... other options
      authorization: { params: { scope: 'openid offline_access profile email' } },
      // ... other options
    },
  ],
});

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.

Lecturas adicionales

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