Añade autenticación a tu aplicación Auth.js (Next Auth)

Esta guía te mostrará cómo integrar Logto en tu aplicación Next.js con Auth.js, anteriormente conocido como 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 Auth.js, consulta la documentación de Auth.js.

Instalación

Instala Auth.js a través de tu gestor de paquetes favorito:

npm
pnpm
yarn

npm i next-auth@beta

pnpm add next-auth@beta

yarn add next-auth@beta

Consulta la documentación de Auth.js para más detalles.

Integración

Configura el proveedor Auth.js

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 tu API de Auth.js, añade Logto como un proveedor OIDC:

Auth.js v5
Next Auth v4

./app/api/auth/[...nextauth]/route.ts
import { handlers } from '@/auth';
export const { GET, POST } = handlers;

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, 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 final 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,
        };
      },
    },
  ],
});

Reemplaza la URL del issuer con el "Punto final del emisor" de tu aplicación Logto.
Reemplaza el clientId y el clientSecret con el ID y el secreto de tu aplicación Logto.
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.

Luego, también puedes añadir un Middleware opcional para mantener la sesión activa:

./middleware.ts
export { auth as middleware } from '@/auth';

app/api/auth/[...nextauth]/route.ts
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 final de configuración del proveedor 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 };

Reemplaza la URL de wellKnown con el "Punto final de configuración del proveedor OpenID" de tu aplicación Logto.
Reemplaza el clientId y el clientSecret con el ID y el secreto de tu aplicación Logto.
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.
Recuerda establecer el id_token_signed_response_alg en ES384.

Puedes encontrar más detalles en la documentación de Auth.js.

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:

Tu aplicación invoca el método de inicio de sesión.
El usuario es redirigido a la página de inicio de sesión de Logto. Para aplicaciones nativas, se abre el navegador del sistema.
El usuario inicia sesión y es redirigido de vuelta a tu aplicación (configurada como el URI de 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.

nota:

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

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

app/components/sign-in.tsx
import { signIn } from '@/auth';

export default function SignIn() {
  return (
    <form
      action={async () => {
        'use server';
        await signIn('logto');
      }}
    >
      <button type="submit">Iniciar sesión</button>
    </form>
  );
}

app/components/sign-out.tsx
import { signOut } from '@/auth';

export function SignOut() {
  return (
    <form
      action={async () => {
        'use server';
        await signOut();
      }}
    >
      <button type="submit">Cerrar sesión</button>
    </form>
  );
}

app/page.tsx
import SignIn from './components/sign-in';
import SignOut from './components/sign-out';
import { auth } from '@/auth';

export default function Home() {
  const session = await auth();

  return <div>{session?.user ? <SignOut /> : <SignIn />}</div>;
}

Arriba hay un ejemplo simple, puedes consultar la documentación de Auth.js para más detalles.

Punto de control

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

Obtener información del usuario

Mostrar información del usuario

Cuando el usuario ha iniciado sesión, el valor de retorno de auth() será un objeto que contiene la información del usuario. Puedes mostrar esta información en tu aplicación:

app/page.tsx
import { auth } from '@/auth';

export default async function Home() {
  const session = await auth();

  return (
    <main>
      {session?.user && (
        <div>
          <h2>Reclamos (Claims):</h2>
          <table>
            <thead>
              <tr>
                <th>Nombre</th>
                <th>Valor</th>
              </tr>
            </thead>
            <tbody>
              {Object.entries(session.user).map(([key, value]) => (
                <tr key={key}>
                  <td>{key}</td>
                  <td>{String(value)}</td>
                </tr>
              ))}
            </tbody>
          </table>
        </div>
      )}
    </main>
  );
}

Solicitar reclamos adicionales

Es posible que encuentres que falta alguna información del usuario en el objeto devuelto desde auth(). 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 los parámetros del proveedor de Logto:

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',,
      // ...
      authorization: {
        params: {
          scope: 'openid offline_access profile email',
        },
      },
      // ...
    },
  ],
});

Reclamos que necesitan solicitudes de red

Para evitar sobrecargar el Token de ID, algunos reclamos requieren solicitudes de red para ser obtenidos. Por ejemplo, el reclamo custom_data no está incluido en el objeto de usuario incluso si se solicita en los alcances. Para acceder a estos reclamos, necesitas hacer una solicitud de red para obtener la información del usuario.

Obtener token de acceso

Actualiza la configuración de NextAuth para que podamos obtener el token de acceso:

./auth.ts
export const { handlers, signIn, signOut, auth } = NextAuth({
  // ...
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        token.accessToken = account.access_token;
      }
      return token;
    },
    async session({ session, token }) {
      // Inyecta el token de acceso en el objeto de sesión
      session.accessToken = token.accessToken;
      return session;
    },
  },
});

Obtener información del usuario

Ahora accede al endpoint de información del usuario OIDC con el token de acceso:

./app/page.tsx
// ...

export default async function Home() {
  const session = await auth();
  // Reemplaza la URL con tu endpoint de Logto, debe terminar con `/oidc/me`
  const response = await fetch('https://xxx.logto.app/oidc/me', {
    headers: {
      Authorization: `Bearer ${session?.accessToken}`,
    },
  });
  const user = await response.json();
  console.log(user);

  // ...
}

Arriba hay un ejemplo simple. Recuerda manejar los casos de error.

Actualización del token de acceso

Un token de acceso es válido por un corto período de tiempo. Por defecto, Next.js solo obtendrá uno cuando se crea la sesión. Para implementar la actualización automática del token de acceso, consulta Rotación de token de actualización.

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 el proveedor Logto

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

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',,
      // ...
      authorization: {
        params: {
          scope: 'openid offline_access profile email',
          resource: 'https://shopping.your-app.com/api',
        },
      },
      // ...
    },
  ],
});

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:

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',,
      // ...
      authorization: {
        params: {
          scope: 'openid offline_access profile email shopping:read shopping:write',
          resource: 'https://shopping.your-app.com/api',
        },
      },
      // ...
    },
  ],
});

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.

Así, en el caso anterior, los alcances se pueden simplificar desde la definición en Logto, ambos recursos de API pueden tener alcances read y write sin el prefijo. Luego, en la configuración de Logto:

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',,
      // ...
      authorization: {
        params: {
          scope: 'openid offline_access profile read write',
          resource: 'https://shopping.your-app.com/api',
        },
      },
      // ...
    },
  ],
});

Para cada recurso de API, se solicitarán tanto los alcances read como write.

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 token de acceso para el recurso de API

Auth.js solo obtendrá el token de acceso una vez sin el parámetro de recurso. Necesitamos implementar la obtención del token de acceso por nosotros mismos.

Obtener token de actualización

Actualiza la configuración del proveedor de Logto, añade el parámetro "prompt" y configúralo en consent, y asegúrate de que el alcance offline_access esté incluido:

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  // ...
  authorization: {
    params: {
      prompt: 'consent',
      scope: 'openid offline_access shopping:read shopping:write',
      resource: 'https://shopping.your-app.com/api',
      // ...
    },
  },
  // ...
});

Luego añade un callback para guardar el refresh_token en la sesión:

./auth.ts
export const { handlers, signIn, signOut, auth } = NextAuth({
  // ...
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        // ...
        token.refreshToken = account.refresh_token;
      }
      return token;
    },
    async session({ session, token }) {
      // ...
      session.refreshToken = token.refreshToken;
      return session;
    },
  },
});

Obtener token de acceso

Con el refresh_token, podemos obtener el token de acceso desde el endpoint de token OIDC de Logto.

./app/page.tsx
// ...

export default async function Home() {
  const session = await auth();

  if (session?.refreshToken) {
    // Reemplaza el ID y el secreto de la aplicación con los tuyos propios, puedes verificar la sección "Integration".
    const basicAuth = Buffer.from('<logto-app-id>:<logto-app-secret>').toString('base64');

    // Reemplaza la URL con tu endpoint de Logto, debe terminar con `/oidc/token`
    const response = await fetch('https://xxx.logto.app/oidc/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        Authorization: `Basic ${basicAuth}`,
      },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: session.refreshToken,
        resource: 'https://shopping.your-app.com/api',
      }).toString(),
    });

    const data = await response.json();
    console.log(data.access_token);
  }

  // ...
}

Obtener tokens de organización

Si la organización es nueva para ti, por favor lee 🏢 Organizaciones (Multi-tenancy) para comenzar.

Necesitas añadir el alcance urn:logto:scope:organizations al configurar el cliente Logto:

./auth.ts
import NextAuth from 'next-auth';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: 'logto',
      // ...
      authorization: {
        params: {
          scope: 'openid offline_access urn:logto:scope:organizations',
        },
      },
      // ...
    },
  ],
});

Una vez que el usuario ha iniciado sesión, puedes obtener el token de organización para el usuario:

Similar al token de acceso para recursos de API, podemos usar el token de actualización para obtener el token de acceso de la organización.

./app/page.tsx
// ...

export default async function Home() {
  const session = await auth();

  if (session?.refreshToken) {
    // Reemplaza el ID y el secreto de la aplicación con los tuyos, puedes verificar la sección "Integration".
    const basicAuth = Buffer.from('<logto-app-id>:<logto-app-secret>').toString('base64');

    // Reemplaza la URL con tu endpoint de Logto, debe terminar con `/oidc/token`
    const response = await fetch('https://xxx.logto.app/oidc/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        Authorization: `Basic ${basicAuth}`,
      },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: session.refreshToken,
        resource: 'urn:logto:scope:organizations',
        organization_id: 'organization-id',
      }).toString(),
    });

    const data = await response.json();
    console.log(data.access_token);
  }

  // ...
}

Lecturas adicionales

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

Migrando la integración de Logto de NextAuth.js v4 a v5

Prerrequisitos​

Instalación​

Integración​

Configura el proveedor Auth.js​

Configura el URI de redirección de inicio de sesión​

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

Implementa el inicio y cierre de sesión​

Implementa el botón de inicio y cierre de sesión​

Muestra el botón de inicio y cierre de sesión en la página​

Punto de control​

Obtener información del usuario​

Mostrar información del usuario​

Solicitar reclamos adicionales​

Reclamos que necesitan solicitudes de red​

Obtener token de acceso​

Obtener información del usuario​

Actualización del token de acceso​

Alcances y reclamos​

Recursos de API​

Configurar el proveedor Logto​

Obtener token de acceso para el recurso de API​

Obtener token de actualización​

Obtener token de acceso​

Obtener tokens de organización​

Lecturas adicionales​

Prerrequisitos

Instalación

Integración

Configura el proveedor Auth.js

Configura el URI de redirección de inicio de sesión

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

Implementa el inicio y cierre de sesión

Implementa el botón de inicio y cierre de sesión

Muestra el botón de inicio y cierre de sesión en la página

Punto de control

Obtener información del usuario

Mostrar información del usuario

Solicitar reclamos adicionales

Reclamos que necesitan solicitudes de red

Obtener token de acceso

Obtener información del usuario

Actualización del token de acceso

Alcances y reclamos

Recursos de API

Configurar el proveedor Logto

Obtener token de acceso para el recurso de API

Obtener token de actualización

Obtener token de acceso

Obtener tokens de organización

Lecturas adicionales