APP_USER_ROLES – Guía de uso

Este documento explica cómo recuperar los roles del usuario para el módulo activo desde el storageMap usando la clave APP_USER_ROLES, disponible en cualquier Microfrontend Remoto.

---

tip

Los roles de usuario (APP_USER_ROLES) representan los roles asignados al usuario en Keycloak para la aplicación del módulo que está navegando actualmente. Se actualizan automáticamente en cada cambio de ruta por el shell principal.

¿Cómo se puebla APP_USER_ROLES?

El shell principal (ContentLayoutComponent) es responsable de guardar esta información. Al detectar una navegación, obtiene la aplicación activa desde APP_SOURCE y consulta el backend con fetchRolesUserByRealmAppUsername. El resultado se normaliza y se persiste bajo la clave APP_USER_ROLES.

// Flujo interno del shell (solo referencia — no copiar en remotes)
// content-layout.component.ts → handleSaveRolesUserSession()
this.storageVm.setStorageMap('APP_USER_ROLES', normalizedRoles);
// normalizedRoles: Array<{ roleName: string }>

La estructura almacenada es un arreglo de objetos con la forma:

Array<{ roleName: string }>
// Ejemplo:
// [{ roleName: 'ADMIN' }, { roleName: 'CONSULTA' }]

---

📁 Importaciones necesarias

En tu componente o servicio importa AlpuraStorageViewModel desde la librería @alpura/commons.

// En tu componente.ts o servicio.ts
import { AlpuraStorageViewModel } from "@alpura/commons";

---

🧩 Ejemplo de uso | Recuperar todos los roles del usuario

export class MyComponent implements OnInit {
  /**
   * Servicio de gestión de almacenamiento.
   * Inyecta `AlpuraStorageViewModel` para controlar los tipos de almacenamiento
   * de datos mediante localstorage, session storage, storage(map) y cookie.
   *
   * @readonly
   * @type {AlpuraStorageViewModel}
   */
  private readonly storageVm = inject(AlpuraStorageViewModel);

  /**
   * Ciclo de vida de Angular.
   * Se invoca getStorageMap() con la clave 'APP_USER_ROLES' para obtener
   * el arreglo de roles del usuario en el módulo activo.
   */
  ngOnInit(): void {
    const userRoles = this.storageVm.getStorageMap('APP_USER_ROLES') as
      | Array<{ roleName: string }>
      | null;

    console.log('[ROLES]:', userRoles);
    // Ejemplo de resultado: [{ roleName: 'ADMIN' }, { roleName: 'CONSULTA' }]
  }
}

---

🧩 Ejemplo de uso | Verificar si el usuario tiene un rol específico

export class MyComponent implements OnInit {
  /**
   * @readonly
   * @type {AlpuraStorageViewModel}
   */
  private readonly storageVm = inject(AlpuraStorageViewModel);

  /**
   * Ciclo de vida de Angular.
   * Se usa hasRole() para verificar si el usuario posee un rol determinado.
   */
  ngOnInit(): void {
    const canEdit = this.hasRole('ADMIN');
  }

  /**
   * Verifica si el usuario tiene un rol específico dentro de `APP_USER_ROLES`.
   *
   * Origen de datos:
   * - Lee el arreglo `APP_USER_ROLES` desde el `storageMap` (vía `AlpuraStorageViewModel`).
   *
   * Reglas:
   * - Si `APP_USER_ROLES` no existe en el storageMap, retorna `false`.
   * - La comparación es insensible a mayúsculas/minúsculas.
   *
   * @param {string} role Nombre del rol a verificar (ej. `'ADMIN'`, `'CONSULTA'`).
   * @returns {boolean} `true` si el usuario posee el rol, `false` en caso contrario.
   *
   * @example
   * const canEdit = this.hasRole('ADMIN');
   * // canEdit => true | false
   */
  public hasRole(role: string): boolean {
    const userRoles = this.storageVm.getStorageMap('APP_USER_ROLES') as
      | Array<{ roleName: string }>
      | null;

    if (!userRoles?.length) return false;

    return userRoles.some(
      (r) => r.roleName?.toUpperCase() === role.toUpperCase()
    );
  }
}

---

⚠️ Consideraciones importantes

Punto	Detalle
Momento de disponibilidad	APP_USER_ROLES se llena después de que el shell resuelve la ruta activa. Si lo lees en el constructor, puede estar vacío. Usa ngOnInit o espera la señal isUserRolesSet del shell si está disponible.
Scope del dato	Los roles cambian en cada navegación: siempre corresponden al módulo que el usuario está visitando actualmente, no son roles globales.
Roles globales	Si necesitas los roles de toda la aplicación (todos los realms), usa la clave APP_GLOBAL_ROLES en su lugar.
Tipo de dato	El valor es Array<{ roleName: string }>. Siempre castea con seguridad antes de usar.

---

🚀 Resultado esperado

Esta implementación permite a los Microfrontends Remotos leer los roles del usuario para el módulo activo y aplicar reglas de negocio como mostrar/ocultar botones, habilitar acciones o restringir vistas, sin realizar llamadas adicionales al backend.

---

📬 Soporte

Para dudas o mejoras, puedes contactar al equipo de arquitectura.