191 lines
6.5 KiB
Markdown
191 lines
6.5 KiB
Markdown
# 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**
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cp .env.template .env
|
|
```
|
|
|
|
Edite el archivo `.env` con la configuración de su entorno de Keycloak:
|
|
|
|
```env
|
|
# 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**
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
4. **Iniciar el Servidor de Desarrollo**
|
|
|
|
```bash
|
|
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](https://www.keycloak.org/downloads)
|
|
- 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](https://www.keycloak.org/documentation)
|
|
- [Angular Security Best Practices](https://angular.io/guide/security)
|
|
- [Tutorial completo de Keycloak](tutorial-keycloak-completo.md) |