proxy-oidcv2/INSTALLATION.md

# 🔐 Guide d'Installation - Secure Proxy OIDC

## Configuration Rapide (Développement)

### 1. Installation des dépendances

```bash
cd /Users/alexandre/projet/openidv2
npm install
```

### 2. Configuration de base

```bash
cp .env.example .env
```

Pour le développement simple (sans Keycloak), modifier `.env` :

```env
PORT=3000
NODE_ENV=development
PROXY_URL=http://localhost:3000

# Ces valeurs peuvent rester par défaut pour le dev
OIDC_ISSUER=http://localhost:8080/auth/realms/master
OIDC_CLIENT_ID=openidv2-client
OIDC_CLIENT_SECRET=dev-secret
OIDC_CALLBACK_URL=http://localhost:3000/callback

ADMIN_USERNAME=admin@example.com
ADMIN_PASSWORD=password123

DB_PATH=./db/services.db
SESSION_SECRET=dev-secret-very-secure

LOG_LEVEL=info
```

### 3. Initialiser la base de données

```bash
npm run init-db
```

### 4. Démarrer le serveur

**Mode développement (avec auto-reload)** :
```bash
npm run dev
```

**Mode production** :
```bash
npm start
```

Le serveur démarre sur http://localhost:3000

## Configuration Complète avec Keycloak

### Setup Keycloak local (Docker)

```bash
docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_HTTP_ENABLED=true \
  quay.io/keycloak/keycloak:latest start-dev
```

Accéder à : http://localhost:8080
- Login : admin / admin

### Créer un Realm Keycloak

1. Aller à la console d'administration
2. Hover sur "Master" → "Create realm"
3. Nommer le realm : `master` (déjà créé par défaut)

### Créer un Client OIDC

1. Dans le menu gauche : **Clients**
2. **Create**
3. **Client ID** : `openidv2-client`
4. **Client Protocol** : `openid-connect`
5. **Root URL** : `http://localhost:3000`
6. **Save**

#### Configurer le Client

Aller dans l'onglet **Settings** du client créé :

- **Valid Redirect URIs** : `http://localhost:3000/callback`
- **Valid Post Logout Redirect URIs** : `http://localhost:3000/`
- **Access Type** : `confidential`
- **Standard Flow Enabled** : `ON`

Aller dans l'onglet **Credentials** :

- Noter le **Client Secret**

### Créer un utilisateur

1. Menu gauche : **Users** → **Add User**
2. **Username** : `testuser`
3. **Email** : `testuser@example.com`
4. **Email Verified** : `ON`
5. **Save**

Onglet **Credentials** :

- **Set Password** : définir un mot de passe
- **Temporary** : OFF

### Mettre à jour .env

```env
OIDC_ISSUER=http://localhost:8080/auth/realms/master
OIDC_CLIENT_ID=openidv2-client
OIDC_CLIENT_SECRET=<secret-from-keycloak>
OIDC_CALLBACK_URL=http://localhost:3000/callback
ADMIN_USERNAME=testuser@example.com
```

### Redémarrer le serveur

```bash
npm run dev
```

## Exemples d'Utilisation

### Exemple 1 : Proxifier Grafana local

**Setup Grafana** :
```bash
docker run -p 3001:3000 grafana/grafana
```

**Ajouter via Panel Admin** :
1. Aller à `/admin`
2. Login avec Keycloak
3. "+ New Service"
4. Remplir :
   - Name: `Grafana`
   - Path: `/grafana`
   - Target URL: `http://localhost:3001`
   - Require Auth: ✓ Cochée

**Accès** :
- Avant : http://localhost:3001
- Après : https://secure.k2r.ovh/grafana (ou http://localhost:3000/grafana en dev)

### Exemple 2 : Proxifier un service public (pas d'auth)

```bash
# Service simple
docker run -p 5000:80 nginx

# Dans l'admin :
# Name: Public Docs
# Path: /docs
# Target URL: http://localhost:5000
# Require Auth: ❌ Décochée

# Accès sans login : http://localhost:3000/docs
```

### Exemple 3 : Proxifier une app React locale

```bash
# L'app React en dev
npm start  # sur http://localhost:3000

# Dans l'admin :
# Name: My React App
# Path: /app
# Target URL: http://localhost:3000
# Require Auth: ✓

# Accès : http://localhost:3000/app
```

## Test de l'API

Script shell disponible :

```bash
chmod +x test-api.sh
./test-api.sh
```

Ou manuellement avec curl :

```bash
# Test de login
curl http://localhost:3000/auth/login-page

# Test des services (après auth)
curl http://localhost:3000/api/services \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Accès au Panel Admin

1. **Sans Keycloak** (dev) : 
   - URL : http://localhost:3000/admin
   - Email : admin@example.com

2. **Avec Keycloak** :
   - URL : http://localhost:3000/auth/login
   - Authentifier avec Keycloak
   - Doit avoir l'email configuré en `ADMIN_USERNAME`

## Déploiement Production

### Configuration DNS

Créer un record DNS :
```
secure.k2r.ovh  A  YOUR_IP
```

### Certificat SSL

Avec Let's Encrypt :
```bash
sudo certbot certonly --standalone -d secure.k2r.ovh
```

### Configuration Nginx

Copier et adapter `nginx.example.conf` :

```bash
sudo cp nginx.example.conf /etc/nginx/sites-available/secure-proxy
sudo ln -s /etc/nginx/sites-available/secure-proxy /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
```

### Configurer .env production

```env
NODE_ENV=production
PORT=3000
PROXY_URL=https://secure.k2r.ovh

OIDC_ISSUER=https://keycloak.example.com/auth/realms/master
OIDC_CLIENT_ID=openidv2-client
OIDC_CLIENT_SECRET=changeme_secure
OIDC_CALLBACK_URL=https://secure.k2r.ovh/callback

ADMIN_USERNAME=admin@example.com
ADMIN_PASSWORD=changeme_secure

DB_PATH=/var/lib/openidv2/services.db
SESSION_SECRET=changeme_very_long_random_string

LOG_LEVEL=info
```

### Lancer avec systemd

Créer `/etc/systemd/system/openidv2.service` :

```ini
[Unit]
Description=Secure Proxy OIDC
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/openidv2
Environment="NODE_ENV=production"
ExecStart=/usr/bin/node src/server.js
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Lancer :
```bash
sudo systemctl daemon-reload
sudo systemctl start openidv2
sudo systemctl enable openidv2
```

Vérifier :
```bash
sudo systemctl status openidv2
sudo journalctl -u openidv2 -f
```

## Dépannage

### Port déjà utilisé

```bash
# Trouver le processus
lsof -i :3000

# Changer le port dans .env
PORT=3001
```

### Erreur OIDC

```
✗ OIDC initialization failed
```

- Vérifier que Keycloak est accessible
- Vérifier `OIDC_ISSUER` dans `.env`
- Le serveur continue sans OIDC en dev

### Base de données verrouillée

```bash
rm db/services.db
npm run init-db
```

### Logs détaillés

```env
LOG_LEVEL=debug
```

## Variables d'Environnement Complètes

```env
# Serveur
PORT=3000
NODE_ENV=development|production
PROXY_URL=https://secure.k2r.ovh

# OIDC/Keycloak
OIDC_ISSUER=https://keycloak.example.com/auth/realms/master
OIDC_CLIENT_ID=openidv2-client
OIDC_CLIENT_SECRET=your_secret
OIDC_CALLBACK_URL=https://secure.k2r.ovh/callback

# Admin
ADMIN_USERNAME=admin@example.com
ADMIN_PASSWORD=your_password

# Base de données
DB_PATH=./db/services.db

# Sessions
SESSION_SECRET=random_string_minimum_32_chars

# Sécurité
RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
RATE_LIMIT_MAX_REQUESTS=100

# Logging
LOG_LEVEL=debug|info|warn|error
```

## Commandes Utiles

```bash
# Installation complète
npm install && npm run init-db

# Démarrage dev
npm run dev

# Production
npm start

# Seed de données d'exemple
npm run seed-db

# Test API
./test-api.sh

# Voir les sessions
ls -la sessions/

# Voir la DB
sqlite3 db/services.db "SELECT * FROM services;"

# Logs (systemd)
journalctl -u openidv2 -f
```

---

**Questions ? Consultez README.md pour plus d'infos**