Saltar al contenido principal

Añade autenticación a tu aplicación Angular

Esta guía te mostrará cómo integrar Logto Angular SDK v2 en tu aplicación.

tip:
  • Esta guía utiliza el SDK oficial @logto/angular v2, que es compatible con Angular 20 y proporciona inyección de dependencias y Signals.
  • 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 Angular 20.

Instalación

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

npm i @logto/angular

Integración

Inicializar el proveedor de Logto

En tu proyecto Angular, registra provideLogto y las rutas de tu aplicación en app.config.ts:

app/app.config.ts
// Importaciones necesarias para la configuración de la aplicación Angular
import { type ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideLogto } from '@logto/angular';

import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
providers: [
provideLogto({
endpoint: '<your-logto-endpoint>',
appId: '<your-app-id>',
}),
provideRouter(routes),
// ...otros proveedores
],
};

provideLogto restaura el estado de autenticación automáticamente después del primer renderizado en el navegador. No necesitas llamar a un método de inicialización en tus componentes.

nota:

Cuando uses renderizado del lado del servidor (SSR), el estado de autenticación y los tokens solo están disponibles en el navegador. Usa isLoading() para mostrar un estado de carga hasta que finalice la inicialización. Si necesitas datos autenticados durante el renderizado en el servidor, utiliza un SDK de servidor o BFF.

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.

URI de redirección en Logto Console

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 la redirección

Crea un componente de callback para completar el inicio de sesión después de que Logto redirija al usuario de vuelta a tu aplicación. Usa afterNextRender para que el manejo del callback se ejecute solo en el navegador:

app/callback.component.ts
import { afterNextRender, Component, inject } from '@angular/core';
import { LogtoService } from '@logto/angular';

@Component({
selector: 'app-callback',
standalone: true,
template: `
@if (logto.error(); as error) {
<p role="alert">{{ error.message }}</p>
} @else {
<p>Completando el inicio de sesión...</p>
}
`,
})
export class CallbackComponent {
readonly logto = inject(LogtoService);

constructor() {
afterNextRender(() => {
void (async () => {
const callbackUri = window.location.href;

if (!(await this.logto.isSignInRedirected(callbackUri))) {
window.location.replace(window.location.origin);
return;
}

await this.logto.handleSignInCallback(callbackUri);
})().catch(() => {
// El SDK expone los errores del callback a través de logto.error() para la plantilla.
});
});
}
}

isSignInRedirected() verifica si la URL coincide con una sesión de inicio de sesión activa. Si alguien visita la ruta de callback sin una sesión activa, este ejemplo lo devuelve a la página principal de la aplicación en lugar de intentar completar el inicio de sesión.

Registra la ruta de callback en app.routes.ts. Debe coincidir con la ruta de tu URI de redirección y no debe requerir autenticación. Por ejemplo, usa callback para una URI de redirección que termine en /callback:

app/app.routes.ts
import { type Routes } from '@angular/router';

import { CallbackComponent } from './callback.component';

export const routes: Routes = [
{ path: 'callback', component: CallbackComponent },
// ...otras rutas
];

El componente raíz necesita un <router-outlet /> para renderizar esta ruta, como se muestra en el siguiente paso.

Implementar inicio y cierre de sesión

Inyecta LogtoService para iniciar el inicio y cierre de sesión. Pasa los URIs de redirección registrados a estos métodos. El postRedirectUri le indica al SDK a dónde navegar después de manejar correctamente el callback de inicio de sesión:

nota:

Antes de llamar a signIn(), asegúrate de haber configurado correctamente el URI de redirección en la Consola de Administración.

app/app.component.ts
import { Component, inject } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { LogtoService } from '@logto/angular';

@Component({
selector: 'app-root',
standalone: true,
imports: [RouterOutlet],
templateUrl: './app.component.html',
})
export class AppComponent {
readonly logto = inject(LogtoService);

async signIn() {
await this.logto.signIn({
redirectUri: 'http://localhost:3000/callback',
postRedirectUri: window.location.origin,
});
}

async signOut() {
await this.logto.signOut('http://localhost:3000/');
}
}

Lee las señales isLoading(), isAuthenticated() y error() directamente en la plantilla:

app/app.component.html
@if (logto.error(); as error) {
<p role="alert">{{ error.message }}</p>
} @if (logto.isLoading()) {
<p>Cargando...</p>
} @else if (logto.isAuthenticated()) {
<button type="button" (click)="signOut()">Cerrar sesión</button>
} @else {
<button type="button" (click)="signIn()">Iniciar sesión</button>
}

<router-outlet />

Mantén <router-outlet /> fuera de las condiciones de autenticación para que el callback pueda renderizarse antes de que el usuario inicie sesión.

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:

  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.

Obtener información del usuario

Mostrar información del usuario

Para mostrar la información del usuario, utiliza getIdTokenClaims() para leer los reclamos (claims) del token de ID sin una solicitud de red adicional. Añade un effect a tu AppComponent para cargar los reclamos cuando isAuthenticated() sea verdadero, incluso cuando se restaure una sesión existente. Importa JsonPipe para mostrar el resultado:

app/app.component.ts
import { JsonPipe } from '@angular/common';
import { Component, effect, inject, signal } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { LogtoService, type IdTokenClaims } from '@logto/angular';

@Component({
selector: 'app-root',
standalone: true,
imports: [JsonPipe, RouterOutlet],
templateUrl: './app.component.html',
})
export class AppComponent {
readonly logto = inject(LogtoService);
readonly user = signal<IdTokenClaims | undefined>(undefined);

constructor() {
effect(() => {
if (!this.logto.isAuthenticated()) {
this.user.set(undefined);
return;
}

void this.logto
.getIdTokenClaims()
.then((claims) => {
this.user.set(claims);
})
.catch(() => {
// El SDK expone el error a través de logto.error() para la plantilla.
});
});
}

// ...mantén los métodos signIn() y signOut() del paso anterior
}

Agrega lo siguiente dentro de la rama logto.isAuthenticated() de tu plantilla:

app/app.component.html
@if (user(); as claims) {
<pre>{{ claims | json }}</pre>
}

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.

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.

Agrega los alcances (scopes) a tu configuración de provideLogto:

app/app.config.ts
import { type ApplicationConfig } from '@angular/core';
import { provideLogto, UserScope } from '@logto/angular';

export const appConfig: ApplicationConfig = {
providers: [
provideLogto({
endpoint: '<your-logto-endpoint>',
appId: '<your-app-id>',
scopes: [
UserScope.Email,
UserScope.Phone,
UserScope.CustomData,
UserScope.Identities,
UserScope.Organizations,
],
}),
// ...otros proveedores
],
};

Vuelve a iniciar sesión después de cambiar los alcances. Los reclamos adicionales del token de ID, como email y phone_number, estarán disponibles desde getIdTokenClaims() y se mostrarán con el ejemplo anterior.

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 fetchUserInfo():

app/app.component.ts
// Agrega este método a AppComponent y llámalo después de iniciar sesión.
async loadUserInfo() {
const userInfo = await this.logto.fetchUserInfo();
// Ahora puedes acceder a userInfo.custom_data, userInfo.identities, etc.
return 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.

fetchUserInfo() se puede usar junto con los tokens de acceso a recursos de API. Configurar resources no impide que el SDK solicite información del usuario.

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.

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

Alcances OIDC estándar

openid (predeterminado)

Claim nameTypeDescription
substringEl identificador único del usuario

profile (predeterminado)

Claim nameTypeDescription
namestringEl nombre completo del usuario
usernamestringEl nombre de usuario del usuario
picturestringURL 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_atnumberMomento 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_atnumberMomento 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 nameTypeDescription
emailstringLa dirección de correo electrónico del usuario
email_verifiedbooleanSi la dirección de correo electrónico ha sido verificada

phone

Claim nameTypeDescription
phone_numberstringEl número de teléfono del usuario
phone_number_verifiedbooleanSi 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 nameTypeDescriptionIncluded in ID token by default
custom_dataobjectLos datos personalizados del usuario

identities

Claim nameTypeDescriptionIncluded in ID token by default
identitiesobjectLas identidades vinculadas del usuario
sso_identitiesarrayLas identidades SSO vinculadas del usuario

roles

Claim nameTypeDescriptionIncluded in ID token by default
rolesstring[]Los roles del usuario

urn:logto:scope:organizations

Claim nameTypeDescriptionIncluded in ID token by default
organizationsstring[]Los IDs de las organizaciones a las que pertenece el usuario
organization_dataobject[]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 nameTypeDescriptionIncluded in ID token by default
organization_rolesstring[]Los roles de organización a los que pertenece el usuario con el formato <organization_id>:<role_name>

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.

Configura el cliente de Logto

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

app/app.config.ts
import { type ApplicationConfig } from '@angular/core';
import { provideLogto } from '@logto/angular';

export const appConfig: ApplicationConfig = {
providers: [
provideLogto({
endpoint: '<your-logto-endpoint>',
appId: '<your-app-id>',
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
}),
// ...otros proveedores
],
};

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:

app/app.config.ts
import { type ApplicationConfig } from '@angular/core';
import { provideLogto } from '@logto/angular';

export const appConfig: ApplicationConfig = {
providers: [
provideLogto({
endpoint: '<your-logto-endpoint>',
appId: '<your-app-id>',
scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
}),
// ...otros proveedores
],
};

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:

app/app.config.ts
import { type ApplicationConfig } from '@angular/core';
import { provideLogto } from '@logto/angular';

export const appConfig: ApplicationConfig = {
providers: [
provideLogto({
endpoint: '<your-logto-endpoint>',
appId: '<your-app-id>',
scopes: ['read', 'write'], // Alcances solicitados
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Recursos de API solicitados
}),
// ...otros proveedores
],
};

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.

Vuelve a iniciar sesión después de cambiar los recursos o alcances para que el usuario pueda autorizar la configuración actualizada.

Obtén el 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():

app/api-resource.component.ts
import { Component, inject, signal } from '@angular/core';
import { LogtoService } from '@logto/angular';

@Component({
selector: 'app-api-resource',
standalone: true,
template: `
@if (logto.error(); as error) {
<p role="alert">{{ error.message }}</p>
}
@if (logto.isAuthenticated()) {
<button type="button" [disabled]="logto.isLoading()" (click)="loadAccessToken()">
Obtener token de acceso de API
</button>
<pre>{{ accessToken() }}</pre>
}
`,
})
export class ApiResourceComponent {
readonly logto = inject(LogtoService);
readonly accessToken = signal('');

async loadAccessToken() {
this.accessToken.set(await this.logto.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.

Utiliza el identificador exacto del recurso de tu configuración. Llama a getAccessToken(resource) cada vez que realices una solicitud a la API para que el SDK pueda devolver un token válido, en lugar de mantener un token indefinidamente en tu componente.

Obtén 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:

app/app.config.ts
import { type ApplicationConfig } from '@angular/core';
import { provideLogto, UserScope } from '@logto/angular';

export const appConfig: ApplicationConfig = {
providers: [
provideLogto({
endpoint: '<your-logto-endpoint>',
appId: '<your-app-id>',
scopes: [UserScope.Organizations],
}),
// ...other providers
],
};

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

app/organizations.component.ts
import { Component, effect, inject, signal } from '@angular/core';
import { LogtoService } from '@logto/angular';

@Component({
selector: 'app-organizations',
standalone: true,
template: `
@if (logto.error(); as error) {
<p role="alert">{{ error.message }}</p>
}
@if (logto.isAuthenticated()) {
<ul>
@for (organizationId of organizationIds(); track organizationId) {
<li>
<span>{{ organizationId }}</span>
<button
type="button"
[disabled]="logto.isLoading()"
(click)="loadOrganizationToken(organizationId)"
>
Obtener token de organización
</button>
</li>
}
</ul>
<pre>{{ organizationToken() }}</pre>
}
`,
})
export class OrganizationsComponent {
readonly logto = inject(LogtoService);
readonly organizationIds = signal<string[]>([]);
readonly organizationToken = signal('');

constructor() {
effect(() => {
if (!this.logto.isAuthenticated()) {
this.organizationIds.set([]);
this.organizationToken.set('');
return;
}

void this.logto
.getIdTokenClaims()
.then((claims) => {
this.organizationIds.set(claims.organizations ?? []);
})
.catch(() => {
// El SDK expone el error a través de logto.error() para la plantilla.
});
});
}

async loadOrganizationToken(organizationId: string) {
this.organizationToken.set(await this.logto.getOrganizationToken(organizationId));
}
}

Combina UserScope.Organizations con cualquier alcance existente y vuelve a iniciar sesión después de actualizar la configuración. getOrganizationToken(organizationId) devuelve un token para la organización de Logto seleccionada; utiliza getAccessToken(resource) para un token de recurso de API.

Adjunta el token de acceso a las cabeceras de la solicitud

Coloca el token en la cabecera HTTP Authorization usando el formato Bearer (Bearer YOUR_TOKEN). Por ejemplo, añade este método a un componente autenticado que inyecta LogtoService:

async fetchProducts() {
const accessToken = await this.logto.getAccessToken('https://shopping.your-app.com/api');
const response = await fetch('https://shopping.your-app.com/api/products', {
headers: {
Authorization: `Bearer ${accessToken}`,
},
});

if (!response.ok) {
throw new Error(`Request failed: ${response.status}`);
}

return response.json();
}
nota:

El ejemplo utiliza fetch. Si usas HttpClient de Angular, establece la misma cabecera Authorization en las opciones de la solicitud.

Lecturas adicionales

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