Añade autenticación a tu aplicación Capacitor JS

tip

La siguiente demostración está construida sobre Capacitor JS 5.0.6.

Prerrequisitos

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

Instalación

Instala Logto SDK y las dependencias pares a través de tu gestor de paquetes favorito:

npm
Yarn
pnpm

npm i @logto/capacitor
npm i @capacitor/browser @capacitor/app @capacitor/preferences

yarn add @logto/capacitor
yarn add @capacitor/browser @capacitor/app @capacitor/preferences

pnpm add @logto/capacitor
pnpm add @capacitor/browser @capacitor/app @capacitor/preferences

El paquete @logto/capacitor es el SDK para Logto. Los paquetes restantes son sus dependencias pares.

Integración

Iniciar cliente Logto

Agrega el siguiente código a tu proyecto Capacitor:

import LogtoClient, { type LogtoConfig } from '@logto/capacitor';

const logtoConfig: LogtoConfig = {
  endpoint: '<your-logto-endpoint>',
  appId: '<your-application-id>',
};

const logtoClient = new LogtoClient(config);

Implementar inicio de sesión

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

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.

Ahora, configuremos el URI de redirección. El URI de redirección se utiliza para redirigir al usuario de vuelta a tu aplicación después del flujo de autenticación.

Asegúrate de que el URI redirija a la aplicación Capacitor, por ejemplo, com.example.app://callback. El valor puede variar dependiendo de la configuración de tu aplicación Capacitor. Para más detalles, consulta Capacitor Deep Links.

Luego, agrega el siguiente código al controlador onClick del botón de inicio de sesión:

const onClick = async () => {
  await logtoClient.signIn('com.example.app://callback');
  console.log(await logtoClient.isAuthenticated()); // true
  console.log(await logtoClient.getIdTokenClaims()); // { sub: '...', ... }
};

Implementar cierre de sesión

Dado que Capacitor utiliza el Safari View Controller en iOS y Chrome Custom Tabs en Android, el estado de autenticación puede persistir por un tiempo. Sin embargo, a veces el usuario puede querer cerrar sesión de la aplicación inmediatamente. En este caso, podemos usar el método signOut para cerrar la sesión del usuario:

const onClick = async () => {
  await logtoClient.signOut();
  console.log(await logtoClient.isAuthenticated()); // false
};

El método signOut tiene un parámetro opcional para el URI de redirección posterior al cierre de sesión. Si no se proporciona, el usuario será redirigido a la página de cierre de sesión de Logto.

El usuario necesita hacer clic en "Hecho" para cerrar la vista web y regresar a la aplicación Capacitor. Si deseas redirigir automáticamente al usuario de vuelta a la aplicación Capacitor, puedes proporcionar el URI de redirección posterior al cierre de sesión, por ejemplo, com.example.app://callback/sign-out.

Asegúrate de que el URI de redirección posterior al cierre de sesión pueda redirigir a la aplicación Capacitor. Luego agrega el siguiente código al controlador onClick del botón de cierre de sesión:

const onClick = async () => {
  await logtoClient.signOut('com.example.app://callback/sign-out');
};

Punto de control: Activar el flujo de autenticación

Ejecuta la aplicación Capacitor y haz clic en el botón de inicio de sesión. Se abrirá una ventana del navegador, redirigiendo a la página de inicio de sesión de Logto.

Si el usuario cierra la ventana del navegador sin completar el flujo de autenticación, la aplicación Capacitor recibirá un LogtoClientError.

Obtener información del usuario

Mostrar información del usuario

Para mostrar la información del usuario, puedes usar el método getIdTokenClaims(). Por ejemplo, en una aplicación Capacitor:

const userClaims = await logtoClient.getIdTokenClaims();
console.log(userClaims);

Solicitar reclamos adicionales

Es posible que encuentres que falta alguna información del usuario en el objeto devuelto desde client.getIdTokenClaims(). 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 pasar los alcances al objeto LogtoConfig al inicializar el cliente. Por ejemplo:

const logtoConfig = {
  scopes: ['email', 'phone', 'custom_data', 'organizations'],
};

Luego puedes acceder a los reclamos adicionales en el valor de retorno de client.getIdTokenClaims():

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 se incluye en el objeto de usuario incluso si se solicita en los alcances. Para acceder a estos reclamos, puedes usar el método client.fetchUserInfo():

const userInfo = await logtoClient.fetchUserInfo();
console.log(userInfo);

Este método obtendrá la información del usuario solicitando al endpoint de userinfo. Para aprender más sobre los alcances y reclamos disponibles, consulta la sección de Alcances y reclamos.

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:

import { type LogtoConfig, UserScope } from '@logto/capacitor';

const config: LogtoConfig = {
  // ...other options
  scopes: [UserScope.Email, UserScope.Phone], // Añade los alcances que necesites
};

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 y organizaciones

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 cliente de Logto

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

import { type LogtoConfig } from '@logto/capacitor';

const config: LogtoConfig = {
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Add API resources
};

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:

import { type LogtoConfig } from '@logto/capacitor';

const config: LogtoConfig = {
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.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:

import { type LogtoConfig } from '@logto/capacitor';

const config: LogtoConfig = {
  appId: '<your-application-id>',
  endpoint: '<your-logto-endpoint>',
  scopes: ['read', 'write'],
  resources: ['https://shopping.your-app.com/api', 'https://store.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

Para obtener el token de acceso para un recurso de API específico, puedes usar el método getAccessToken:

const token = await logtoClient.getAccessToken('https://shopping.your-app.com/api');

Este método devolverá un token de acceso JWT que se puede usar para acceder al recurso de API cuando el usuario tiene permisos relacionados. Si el token de acceso en caché actual ha expirado, este método intentará automáticamente usar un token de actualización para obtener un nuevo token de acceso.

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 UserScope.Organizations al configurar el cliente Logto:

import { type LogtoConfig, UserScope } from '@logto/capacitor';

const config: LogtoConfig = {
  // ...other configs
  scopes: [UserScope.Organizations],
};

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

await logtoClient.getOrganizationToken(organizationId);

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​

Iniciar cliente Logto​

Implementar inicio de sesión​

Implementar cierre de sesión​

Punto de control: Activar el flujo de autenticación​

Obtener información del usuario​

Mostrar información del usuario​

Solicitar reclamos adicionales​

Reclamos que necesitan solicitudes de red​

Alcances y reclamos​

Recursos de API y organizaciones​

Configurar el cliente de Logto​

Obtener token de acceso para el recurso de API​

Obtener tokens de organización​

Lecturas adicionales​