SACG - Sistema Administrador de Cronogramas

Aplicación Angular 19 con PrimeNG para la gestión de cronogramas de concesiones, utilizando autenticación directa con Keycloak.

Características Principales

• Autenticación DirectAuth con Keycloak (implementación moderna sin usar keycloak-angular)
• Componentes Standalone Angular 19
• Interfaz de usuario con PrimeNG
• Gestión de cronogramas y concesiones
• Exportación de datos a PDF y Excel

Instalación

Requisitos Previos

• Node.js (versión 20.x o superior)
• npm (incluido con Node.js)
• Keycloak Server (para autenticación)

Pasos de Instalación

1. Clonar el Repositorio

   git clone <URL-del-repositorio>
   cd sacg-cronogramas
   

2. Configurar Variables de Entorno

   Copie el archivo de plantilla de entorno y configúrelo para su entorno:

   cp .env.template .env
   

   Edite el archivo .env con la configuración de su entorno de Keycloak:

   # Keycloak Configuration
   KEYCLOAK_URL=http://localhost:8080
   KEYCLOAK_REALM=angular-app
   KEYCLOAK_CLIENT_ID=angular-app
   KEYCLOAK_CLIENT_SECRET=your-client-secret
   
   # API Configuration
   API_BASE_URL=/api
   
   # Environment
   NODE_ENV=development
   

3. Instalar Dependencias

   npm install
   

4. Iniciar el Servidor de Desarrollo

   npm start
   

   La aplicación estará disponible en http://localhost:4200/

Configuración de Keycloak

Configuración del Servidor

1. Instalar y Ejecutar Keycloak:

   • Descargue Keycloak desde keycloak.org
   • Inicie el servidor: bin/kc.[sh|bat] start-dev
   • Acceda a la consola de administración: http://localhost:8080/admin

2. Crear un Realm:

   • Cree un nuevo realm llamado angular-app
   • Este nombre debe coincidir con su variable KEYCLOAK_REALM en .env

3. Crear un Cliente:

   • Cree un nuevo cliente con ID angular-app (debe coincidir con KEYCLOAK_CLIENT_ID)
   • Configure:
     • Access Type: confidential o public (según su caso)
     • Valid Redirect URIs: http://localhost:4200/*
     • Web Origins: http://localhost:4200 (o agregar + para permitir cualquier origen)

4. Configurar Usuarios y Roles:

   • Cree usuarios para pruebas
   • Configure roles como admin, user, etc.
   • Asigne roles a los usuarios

Integración con la Aplicación

La aplicación utiliza una implementación moderna de autenticación directa con Keycloak, sin depender del paquete keycloak-angular que está deprecado. En su lugar:

• Utiliza el protocolo OpenID Connect para autenticación directa
• Gestiona tokens manualmente para mayor control
• Implementa renovación automática de tokens
• Provee detección de inactividad de usuario

Entornos de Ejecución

Los archivos de entorno están configurados en src/environments/:

• environment.ts: Configuración para desarrollo local
• environment.prod.ts: Configuración para producción

Las variables de entorno relacionadas con Keycloak se definen en estos archivos y se cargan desde los valores configurados en .env.

Flujo de Autenticación

1. Login:

   • Usuario ingresa credenciales en la pantalla de login
   • La aplicación realiza una solicitud directa al endpoint de token de Keycloak
   • Después de una autenticación exitosa, se almacena el token JWT

2. Manejo de Tokens:

   • El token se almacena en localStorage para persistencia entre sesiones
   • Se configura un temporizador para renovación automática del token
   • Se decodifica el token para extraer información del usuario

3. Protección de Rutas:

   • Las rutas protegidas utilizan el guardia authGuard
   • La verificación se basa en la validez del token almacenado

4. Interceptor HTTP:

   • Todas las solicitudes HTTP incluyen automáticamente el token de autenticación
   • En caso de error 401, se intenta renovar el token automáticamente

Comandos Disponibles

Comando	Descripción
npm start	Inicia servidor de desarrollo en http://localhost:4200
npm run build	Compila el proyecto para desarrollo
npm run build:prod	Compila para producción con optimizaciones
npm test	Ejecuta pruebas unitarias

Estructura del Proyecto

/sacg-cronogramas/
├── src/
│   ├── app/
│   │   ├── components/        # Componentes compartidos
│   │   ├── guards/            # Guardias de ruta (authGuard)
│   │   ├── interceptors/      # Interceptores HTTP (authInterceptor)
│   │   ├── models/            # Interfaces de datos
│   │   ├── pages/             # Componentes de página
│   │   ├── services/
│   │   │   ├── direct-auth.service.ts  # Implementación DirectAuth
│   │   │   └── ...            # Otros servicios
│   │   └── utils/             # Utilidades
│   ├── environments/          # Configuración de entornos
│   │   ├── environment.ts     # Desarrollo
│   │   └── environment.prod.ts # Producción
│   ├── pipes/                 # Pipes personalizados
│   ├── index.html             # HTML principal
│   ├── main.ts                # Punto de entrada
│   └── styles.scss            # Estilos globales
├── public/                    # Recursos estáticos
│   └── keycloak.json          # Configuración de Keycloak
├── .env.template              # Plantilla para variables de entorno
├── angular.json               # Configuración de Angular
├── package.json               # Dependencias y scripts
└── README.md                  # Esta documentación

Solución de Problemas

Problemas Comunes de Autenticación

1. No se puede iniciar sesión:

   • Verifique que las credenciales sean correctas
   • Asegúrese de que el servidor Keycloak esté ejecutándose
   • Compruebe que el realm y client ID en .env coincidan con su configuración de Keycloak

2. Token expirado o inválido:

   • La aplicación debería renovar automáticamente el token
   • Si persiste, intente cerrar sesión y volver a iniciar sesión

3. Redirecciones en bucle:

   • Limpie el localStorage del navegador
   • Verifique la configuración de URLs en el cliente Keycloak

Recursos Adicionales

• Documentación oficial de Keycloak
• Angular Security Best Practices
• Tutorial completo de Keycloak