Añade autenticación a tu aplicación Passport.js

Esta guía te mostrará cómo integrar Logto en tu aplicación con Passport.js y la estrategia OIDC.

tip:

• En esta guía, asumimos que has configurado Express con sesión en tu proyecto. Si no lo has hecho, visita el sitio web de Express.js para comenzar.

Requisitos previos

• Una cuenta de Logto Cloud o un Logto autoalojado.
• Una aplicación tradicional de Logto creada.
• Un proyecto de express con sesión configurada. Consulta el sitio web de Express.js.

Instalación

Instala Logto SDK a través de tu gestor de paquetes favorito:

npm

npm i passport passport-openidconnect

pnpm

pnpm add passport passport-openidconnect

yarn

yarn add passport passport-openidconnect

Integración

Inicializar Passport.js con la estrategia OIDC

passport.ts

import passport from 'passport';
import OpenIDConnectStrategy, { type Profile, type VerifyCallback } from 'passport-openidconnect';

const endpoint = '<your-logto-endpoint>';
const appId = '<your-application-id>';
const appSecret = '<your-application-secret>';

export default function initPassport() {
  passport.use(
    new OpenIDConnectStrategy(
      {
        issuer: `${endpoint}/oidc`,
        authorizationURL: `${endpoint}/oidc/auth`,
        tokenURL: `${endpoint}/oidc/token`,
        userInfoURL: `${endpoint}/oidc/me`,
        clientID: appId,
        clientSecret: appSecret,
        callbackURL: '/callback',
        scope: ['profile', 'offline_access'],
      },
      (issuer: string, profile: Profile, callback: VerifyCallback) => {
        callback(null, profile);
      }
    )
  );

  passport.serializeUser((user, callback) => {
    callback(null, user);
  });

  passport.deserializeUser(function (user, callback) {
    callback(null, user as Express.User);
  });
}

Este código inicializa Passport con la OpenIDConnectStrategy. Los métodos serialize y deserialize están configurados con fines de demostración.

Asegúrate de inicializar y adjuntar el middleware de Passport en tu aplicación:

your-app-entry.ts

import initPassport from './passport';

// ... otro código
initPassport();
// ... otro código
app.use(passport.authenticate('session'));
// ... otro código

Configurar URIs de redirección

Antes de entrar 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 URIs de redirección

Cambia a la página de detalles de la aplicación en Logto Console. Añade una URI de redirección http://localhost:3000/callback.

Al igual que al iniciar sesión, los usuarios deben ser redirigidos a Logto para cerrar la sesión de la sesión compartida. Una vez terminado, sería ideal redirigir al usuario de vuelta a tu sitio web. Por ejemplo, añade http://localhost:3000/ como la sección de URI de redirección posterior al cierre de sesión.

Luego haz clic en "Guardar" para guardar los cambios.

Implementar inicio y cierre de sesión

Ahora crearemos rutas específicas para los procesos de autenticación:

your-app-entry.ts

app.get('/sign-in', passport.authenticate('openidconnect'));
app.get(
  '/callback',
  passport.authenticate('openidconnect', {
    successReturnToOrRedirect: '/',
  })
);
app.get('/sign-out', (request, response, next) => {
  request.logout((error) => {
    if (error) {
      next(error);
      return;
    }
    response.redirect(`${endpoint}/oidc/session/end?client_id=${appId}`);
  });
});

Luego añade a la página de inicio

your-app-entry.ts

app.get('/', (request: Request, response) => {
  const { user } = request;
  response.setHeader('content-type', 'text/html');

  if (user) {
    response.end(
      `<h1>Hello Logto</h1><p>Signed in as ${JSON.stringify(
        user
      )}, <a href="/sign-out">Sign Out</a></p>`
    );
  } else {
    response.end(`<h1>Hello Logto</h1><p><a href="/sign-in">Sign In</a></p>`);
  }
});

Punto de control: Prueba tu aplicación

Ahora, puedes probar tu aplicación:

1. Ejecuta tu aplicación, verás el botón de inicio de sesión.
2. 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.
3. 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.
4. Haz clic en el botón de cierre de sesión para limpiar el almacenamiento de tokens y cerrar sesión.

Alcances y reclamos

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

Para los reclamos estándar de OIDC, la inclusión en el token de ID está estrictamente determinada por los alcances solicitados. Los reclamos extendidos (como custom_data y organizations) pueden configurarse adicionalmente para aparecer en el token de ID a través de la configuración de Token de ID personalizado.

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, el SDK de Logto 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:

export default function initPassport() {
  passport.use(
    new OpenIDConnectStrategy(
      {
        // ... other options
        clientID: appId,
        clientSecret: appSecret,
        callbackURL: '/callback',
        scope: ['openid', 'offline_access', 'profile', 'email'],
      }
      // ... other options
    )
  );
  // ... other options
}

Aquí tienes la lista de alcances (Alcances) soportados y los reclamos (Reclamos) correspondientes:

Alcances OIDC estándar

openid (predeterminado)

Claim name	Type	Description
sub	string	El identificador único del usuario

profile (predeterminado)

Claim name	Type	Description
name	string	El nombre completo del usuario
username	string	El nombre de usuario del usuario
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 referenciar específicamente 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.
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).
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).

Otros reclamos estándar incluyen family_name, given_name, middle_name, nickname, preferred_username, profile, website, gender, birthdate, zoneinfo y locale, que también se incluirán en el alcance profile sin necesidad de solicitar el endpoint 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

Claim name	Type	Description
email	string	La dirección de correo electrónico del usuario
email_verified	boolean	Si la dirección de correo electrónico ha sido verificada

phone

Claim name	Type	Description
phone_number	string	El número de teléfono del usuario
phone_number_verified	boolean	Si el número de teléfono ha sido verificado

address

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

info:

Los alcances marcados como (predeterminado) siempre son solicitados por el SDK de Logto. Los reclamos bajo los alcances OIDC estándar siempre se incluyen en el token de ID cuando se solicita el alcance correspondiente; no se pueden desactivar.

Alcances extendidos

Los siguientes alcances son extendidos por Logto y devolverán reclamos a través del endpoint userinfo. Estos reclamos también pueden configurarse para incluirse directamente en el token de ID a través de Consola > JWT personalizado. Consulta Token de ID personalizado para más detalles.

custom_data

Claim name	Type	Description	Included in ID token by default
custom_data	object	Los datos personalizados del usuario

identities

Claim name	Type	Description	Included in ID token by default
identities	object	Las identidades vinculadas del usuario
sso_identities	array	Las identidades SSO vinculadas del usuario

roles

Claim name	Type	Description	Included in ID token by default
roles	string[]	Los roles del usuario	✅

urn:logto:scope:organizations

Claim name	Type	Description	Included in ID token by default
organizations	string[]	Los IDs de las organizaciones a las que pertenece el usuario	✅
organization_data	object[]	Los datos de las organizaciones a las que pertenece el usuario

nota:

Estos reclamos de organización también pueden recuperarse a través del endpoint userinfo cuando se utiliza un token opaco. Sin embargo, los tokens opacos no pueden usarse como tokens de organización para acceder a recursos específicos de la organización. Consulta Token opaco y organizaciones para más detalles.

urn:logto:scope:organization_roles

Claim name	Type	Description	Included in ID token by default
organization_roles	string[]	Los roles de organización a los que pertenece el usuario con el formato <organization_id>:<role_name>	✅

Lecturas adicionales

Flujos de usuario final: flujos de autenticación, flujos de cuenta y flujos de organización Configurar conectores Autorización (Authorization)