Guía de implementación de SSO-ANGULAR-CONECTOR

Generalidades

La presente librería contiene métodos, procesos y llamadas necesarias para completar el proceso de Autenticación/Autorización con el SSO/Autenticación federada.

Requisitos

• Angular v16 o superior
• Typescript v5.4.2 o superior (recomendado)
• jwt-decode

Instalación

Durante el proceso de instalación se recomienda descartar los archivos, clases y tipos correspondientes al modelo de autenticación de la aplicación conforme se van reemplazando con los de auth, pues ya no serán utilizados.

General

1. Instale el paquete en su repositorio local utilizando

   npm i @paulo_a_b/sso-conector jwt-decode

2. Configure los parámetros básicos del API en app.config.ts. Se recomienda colocar estos datos de configuración en el environment.ts.

   // environment.ts
   export const environment = {
        //...
        sso: {
            ssoApiUrl: 'http://localhost:5001/api/',
            ssoWebUrl: 'http://localhost:4300/',
            codigoSistema: 'eq.tarificacion',
            redirectUrl: 'http://localhost:4200/',
            tokenValidationRoute: '/auth/token',
            apiManagerToken: '', // <- Opcional, agrega header 'apiKey' a peticiones del ssoApi, útil en contextos de api gestionados con api-manager
            useSessaKeyHeader: false,
            useIframeBridge: false // Opcional: Verdadero solo para aplicaciones con soporte para tal integración 
        },
   };
   
   // app.config.ts
   import { ApplicationConfig } from '@angular/core';
   import { provideConectorConfig } from '@paulo_a_b/sso-conector';
   import { environment } from '../environments/environment';
   
   export const appConfig: ApplicationConfig = {
       providers: [
           //... Otras declaraciones,
           ...provideConectorConfig({
               ...environment.sso,
           }),
       ]
   };

   En caso de no contar con app.config.ts, se deberá integrar en el app.module.ts como se muestra a continuación

   import { provideConectorConfig } from '@paulo_a_b/sso-conector';
   import { environment } from '../environments/environment';
   
   @NgModule({
    //...Otras props
      providers: [
          //... Otras declaraciones,
        ...provideConectorConfig({
          ...environment.sso,
        }),
      ]
   })

   Esto permitirá a la aplicación pre-cargar el árbol de permisos desde el SSO, verificar el estado de la sesión e interceptar los errores de http.

3. En su componente session-expired o su compoennte equivalente de cierre de sesión, se debe reemplazar el logout por defecto al b2c por el logout provisto por el SSO.

   // Ejemplo: session-expired.component.ts
   import { AuthenticationService } from 'sso-conector';
   @Component({
       //...
   })
   export class SessionExpiredComponent {
   
   constructor(
       //...
       public authenticationService: AuthenticationService, // inyectamos el servicio
   ) {}
   
   logout() {
       localStorage.clear();
       this.ref.close();
       this.authenticationService.logout(); // logout
   }

4. Una vez configurados los servicios de permisos, se deben configurar los guards en nuestro app.routes.ts

    // app.routes.ts
    export const routes: Routes = [
    {
        path: '',
        component: AppLayoutComponent,
        canActivate: [
            authenticationGuard, // Verifica que el usuario tenga una sesión activa
        ],
        canActivateChild: [
            authorizationGuard, // Verifica que el usuario tenga permiso para acceder a las rutas
        ],
        children: [
            //... Rutas hijas protegidas
        ],
        //... Otras rutas no protegidas
    }

   Nota En caso de utilizar el authorizationGuard en rutas raíz, es importante que se declare en canActivateChild, caso contrario no comprobará la navegación entre rutas hijas de la ruta raíz, además de remover las invocaciones al guard de la app en los archivos .routes de cada módulo.

5. Agregar ruta de cierre de sesión. En el archivo app.routes.ts al final agregaremos una ruta NO PROTEGIDA que servirá para el cierre de sesión unificado. Esta ruta deberá registrarse en el SSO al crear el nuevo Sistema.

   // app.routes.ts
   import { LogoutComponent } from 'sso-conector';
   
   export const routes: Routes = [
       //... Otras rutas
       {
         path: 'logout',
         component: LogoutComponent,
       },
   ];

   Este componente se encargará del vaciado de credenciales cuando otra app del entorno cierre sesión.

6. Se estandariza la gestión del menús del sidebar. Para obtener el vector de MenúItems[] que representan un árbol de menús, reemplazamos la lógica de carga en app.menu.component.ts proveniente del layout.

   // app.menu.component.ts
   import { AuthorizationService, mapMenuSistemaGroupToMenuItem } from 'sso_angular_conector';
   export class AppMenuComponent implements OnInit, OnDestroy {
       model: MenuItem[] = [];
   
       constructor(
         private readonly authorizationService: AuthorizationService,
       ) {}
   
       ngOnInit() {
           this.authorizationService.menus.subscribe(
               (menuData) => {
                   this.model = mapMenuSistemaGroupToMenuItem(menuData);
               }
           );
       }
       //...
   }

Gestión de permisos - árbol de permisos

Para verificar permisos, se ofrecen varias alternativas, siendo esta la más compleja de implementar pero escalable a largo plazo. En caso de requerir un procedimiento más rápido, se puede utilizar el método descrito en la sección siguiente.

1. Defina el árbol de menús y operaciones disponibles en su aplicación. Con la finalidad de mejorar el tipado y gestión de anidamientos de menús y operaciones, se ha definido una estructura estándar para la declaración de permisos en aplicaciones frontend.

   Se busca que la estructura del proyecto contenga los siguientes archivos

   src/
   +--app/
       +--modules/
           +--myModule/
               +--myModule.permissions.ts // Archivo de permisos solamente de este módulo
               +--mySubModule/
                   +--mySubModule.permissions.ts // Archivo de permisos solamente de este sub-módulo
       +--security/
           +--permissions.ts // Archivo de permisos globales del proyecto
   
   

   De este modo, a continuación se describe un ejemplo del contenido de cada archivo.

   // permissions.ts
   import { definePermissionsModule } from "sso_angular_conector";
   export const AppPermissions = definePermissionsModule({
       myModule: MyModulePermissions,
   } as const);
   
   // myModule.permissions.ts
   import { ModuloPermissions } from 'sso_angular_conector';
   export const MyModulePermissions = {
       codigoModulo: 'app1.myModule',
       permisos: { //... }, // Opcional: se usa en caso de que el nivel tenga operaciones
       modulos: {
           mySubModule: MySubModulePermissions,
       },
   } as const satisfies ModuloPermissions;
   
   
   // mySubModule.permissions.ts
   import { ModuloPermissions } from 'sso_angular_conector';
   export const MyModulePermissions = {
       codigoModulo: 'app1.myModule.mySubModule',
       permisos: {
           crear: 'test.crear',
           modificar: 'test.modificar',
           eliminar: 'test.eliminar',
           ver: 'test.ver',
       },
   } as const satisfies ModuloPermissions;

   Siguiendo este patrón, podemos anidar hasta 4 niveles de permisos y nos facilita el acceso posterior a los códigos de cada módulo, sub-módulo y operación, sin perder de vista la jerarquía.

2. Se debe implementar la gestión de consulta de los permisos desde el AuthorizationService. Utilizamos AuthorizationService para obtener un OperationChecker, con el cual consultaremos todos las operaciones de un menú específico.

   import { AuthorizationService } from 'sso-conector';
   export class MyModuleComponent {
      module = AppPermissions.myModule;
      hasPermission: OperationsChecker;
   
      constructor(
          private readonly authorizationService: AuthorizationService,
      ) {
          this.hasPermission = this.authorizationService.getOperationsChecker(
              this.module.codigoModulo // se puede utilizar directamente un string, pero se recomienda el uso del árbol de permisos.
          );
      }
      //...
   }

   y al utilizarlo podemos simplemente llamar a la función hasPermission(...)

   <th
      *ngIf="
        hasPermission(module.permisos.modificar) ||
        hasPermission(module.permisos.eliminar)
      "
   >
     Acciones
   </th>

Gestión de permisos - Simple

Esta sección explica como verificar permisos de forma más sencilla y directa, sin embargo se deja de mantener la jerarquía de permisos y se mantienen códigos de permisos muy acoplados.

1. Se debe implementar la gestión de consulta de los permisos desde el AuthorizationService. Utilizamos AuthorizationService para obtener un OperationChecker, con el cual consultaremos todos las operaciones de un menú específico.

   import { AuthorizationService } from 'sso-conector';
   export class MyModuleComponent {
      menuName:string ='';
   
      constructor(
          private readonly authorizationService: AuthorizationService,
      ) {
          //...
      }
   
      ngOnInit(){
          this.menuName = this.router.url.replace(/^\/+|\/+$/g, '');
      }
   
      hasPermission(operation: string): boolean {
          return this.authorizationService.hasPermission(operation, this.menuName);
      }
      //...
   }

   El resto de la implementación se mantiene igual, sin embargo es importante verificar que la ruta y el código del menú coincidan, y que el menú en cuestión contenga los permisos verificados en la vista.