Añade autenticación a tu aplicación Vanilla JS
Vanilla JS: Integra @logto/browser
- El SDK de vanilla-js es independiente del framework, puedes usarlo en cualquier framework frontend escribiendo un envoltorio para adaptarlo.
- El proyecto de ejemplo está disponible en nuestro repositorio de SDK.
Requisitos previos
- Una cuenta de Logto Cloud o un Logto autoalojado.
- Una aplicación de una sola página (SPA) creada en Logto Console.
- Un proyecto de aplicación vanilla JS.
Instalación
Elige tu gestor de paquetes favorito o utiliza el CDN para instalar el Logto Browser SDK.
- npm
- pnpm
- yarn
- CDN
npm i @logto/browser
pnpm add @logto/browser
yarn add @logto/browser
<!-- Agradecimientos especiales a jsdelivr -->
<script type="module">
import LogtoClient from 'https://cdn.jsdelivr.net/npm/@logto/[email protected]/+esm';
</script>
Integración
Inicializar LogtoClient
Importa e inicia una instancia de LogtoClient pasando la configuración:
import LogtoClient from '@logto/browser';
const logtoClient = new LogtoClient({
endpoint: '<your-logto-endpoint>',
appId: '<your-application-id>',
});
El endpoint y el appId se pueden encontrar en la página de detalles de la aplicación en Logto Console.
Configurar URIs de redirecció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.
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.
Manejar redirección
Todavía hay cosas por hacer después de que el usuario sea redirigido de vuelta a tu aplicación desde Logto. Vamos a manejarlo adecuadamente.
const callbackHandler = async (logtoClient) => {
await logtoClient.handleSignInCallback(window.location.href);
if (!logtoClient.isAuthenticated) {
// Manejar inicio de sesión fallido
alert('Error al iniciar sesión');
return;
}
// Manejar inicio de sesión exitoso
window.location.assign('/');
};
Implementar inicio y cierre de sesión
logtoClient proporciona los métodos signIn y signOut para ayudarte a gestionar fácilmente el flujo de autenticación.
Antes de llamar a .signIn(), asegúrate de haber configurado correctamente el URI de redirección en la Consola de Administración.
const isAuthenticated = await logtoClient.isAuthenticated();
const onClickSignIn = () => {
logtoClient.signIn('http://localhost:3000/callback');
};
const onClickSignOut = () => {
logtoClient.signOut('http://localhost:3000');
};
const button = document.createElement('button');
button.innerHTML = isAuthenticated ? 'Sign Out' : 'Sign In';
button.addEventListener('click', isAuthenticated ? onClickSignOut : onClickSignIn);
document.body.appendChild(button);
Llamar a .signOut() borrará todos los datos de Logto en la memoria y en localStorage si existen.
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 ID de usuario y el botón de cierre de sesión.
- Haz clic en el botón de cierre de sesión para cerrar sesión.
Obtener información del usuario
Mostrar información del usuario
Para mostrar la información del usuario, puedes usar el método logtoClient.getIdTokenClaims(). Por ejemplo, en tu página de inicio:
const userInfo = await logtoClient.getIdTokenClaims();
// Generar tabla de visualización para reclamos del token de ID
const table = document.createElement('table');
const thead = document.createElement('thead');
const tr = document.createElement('tr');
const thName = document.createElement('th');
const thValue = document.createElement('th');
thName.innerHTML = 'Nombre';
thValue.innerHTML = 'Valor';
tr.append(thName, thValue);
thead.append(tr);
table.append(thead);
const tbody = document.createElement('tbody');
for (const [key, value] of Object.entries(userInfo)) {
const tr = document.createElement('tr');
const tdName = document.createElement('td');
const tdValue = document.createElement('td');
tdName.innerHTML = key;
tdValue.innerHTML = typeof value === 'string' ? value : JSON.stringify(value);
tr.append(tdName, tdValue);
tbody.append(tr);
}
table.append(tbody);
Solicitar reclamos adicionales
Es posible que encuentres que falta alguna información del usuario en el objeto devuelto desde 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.
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:
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 las configuraciones de Logto:
import LogtoClient, { UserScope } from '@logto/browser';
const logtoClient = new LogtoClient({
appId: '<your-application-id>',
endpoint: '<your-logto-endpoint>',
scopes: [UserScope.Email, UserScope.Phone],
});
Luego puedes acceder a los reclamos adicionales en el valor de retorno de logtoClient.getIdTokenClaims():
const claims = await getIdTokenClaims();
// Ahora puedes acceder a los reclamos adicionales `claims.email`, `claims.phone`, etc.
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 logtoClient.fetchUserInfo():
const userInfo = await logtoClient.fetchUserInfo();
// Ahora puedes acceder al reclamo `userInfo.custom_data`
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.
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? |
|---|---|---|---|
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 cliente de Logto
Una vez que hayas configurado los recursos de API, puedes agregarlos al configurar Logto en tu aplicación:
import LogtoClient from '@logto/browser';
const logtoClient = new LogtoClient({
// ...other configs
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 LogtoClient from '@logto/browser';
const logtoClient = new LogtoClient({
// ...other configs
scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Add API resources
});
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 LogtoClient, { UserScope } from '@logto/browser';
const logtoClient = new LogtoClient({
// ...other configs
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.
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 accessToken = await logtoClient.getAccessToken('https://store.your-app.com/api');
console.log('Access token', accessToken);
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 LogtoClient, { UserScope } from '@logto/browser';
const logtoClient = new LogtoClient({
// ...other configs
scopes: [UserScope.Organizations],
});
Una vez que el usuario ha iniciado sesión, puedes obtener el token de organización para el usuario:
// Obtener organizationIds del userInfo
const claims = await logtoClient.getIdTokenClaims();
const organizationIds = claims.organizations;
/**
* O desde los reclamos del token de ID
*
* const claims = await logtoClient.getIdTokenClaims();
* const organizationIds = claims.organizations;
*/
// Obtener el token de acceso de la organización
if (organizationIds.length > 0) {
const organizationId = organizationIds[0];
const organizationAccessToken = await logtoClient.getOrganizationToken(organizationId);
console.log('Token de acceso de la organización', organizationAccessToken);
}
./code/_scopes-and-claims-code.mdx./code/_config-organization-code.mdx
Adjuntar token de acceso a los encabezados de solicitud
Coloca el token en el campo Authorization de los encabezados HTTP con el formato Bearer (Bearer YOUR_TOKEN), y estarás listo para continuar.
El flujo de integración del Token Bearer puede variar según el framework o solicitante que estés utilizando. Elige tu propia manera de aplicar el encabezado de solicitud Authorization.