# Guide d'Authentification API CHAPS

## Middlewares disponibles

### 1. `verify.bearer` - VerifyFastBearerToken

**Usage** : Applications frontend avec authentification Keycloak (JWT Bearer Token)

**Header requis** :
```
Authorization: Bearer <JWT_TOKEN>
```

**Description** :
- Vérifie le token JWT Bearer contre les clés publiques Keycloak
- Extrait les informations utilisateur du token (email, name, uuid)
- Synchronise automatiquement l'utilisateur avec l'API ESTAIR
- Injecte les données utilisateur dans la requête

**Routes protégées** :
- `/api/v1/admin/*` - Routes CRUD
- `/api/v1/metadata/{modulename}` - Métadonnées
- `/api/v1/menus` - Menus
- `/api/v1/modules` - Modules
- `/api/v1/badges/*` - Badges

**Exemple d'utilisation** :
```bash
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
     http://localhost:8011/api/v1/admin/contacts
```

---

### 2. `verify.apikey` - VerifyFastApiKey

**Usage** :
- API ESTAIR (authentification par clé API)
- Dashboard CHAPS (authentification par session SSO)

**Header requis (pour API)** :
```
X-API-KEY: <votre_cle_api>
```

**Description** :
- Accepte deux modes d'authentification :
  1. **API Key** : Vérifie la clé API dans le header `X-API-KEY`
  2. **Session SSO** : Vérifie si l'utilisateur est authentifié via SSO (session web)
- Mode dual permettant l'utilisation depuis ESTAIR et depuis le dashboard CHAPS

**Routes protégées** :
- `/api/metadata/*` - Gestion des métadonnées
- `/api/backups/*` - Gestion des backups
- `/api/admin/*` (legacy) - Routes CRUD (compatibilité)
- `/api/v1/badges/*` (legacy) - Routes badges (compatibilité)

**Exemple d'utilisation (API Key)** :
```bash
curl -H "X-API-KEY: 1234567890abcdef..." \
     http://localhost:8011/api/metadata/contacts
```

**Exemple d'utilisation (Session SSO)** :
```bash
# Depuis le navigateur avec session active
fetch('http://localhost:8011/api/metadata/contacts', {
  credentials: 'include'
})
```

---

### 3. `SsoAuthenticate` - Middleware Web

**Usage** : Routes web du dashboard CHAPS

**Description** :
- Vérifie la session SSO de l'utilisateur
- Redirige vers `/login` si non authentifié
- Rafraîchit automatiquement la session
- Partage les données utilisateur avec les vues Blade

**Routes protégées** :
- `/admin/metadata-setup/*` - Interface de configuration
- `/admin/menus/*` - Gestion des menus
- `/admin/ctas/*` - Gestion des CTAs
- `/admin/metadatas-matrix/*` - Vue matricielle des métadonnées
- `/admin/blocs-matrix/*` - Vue matricielle des blocs

---

## Migration des routes

### Routes legacy (API Key + SSO)
```
/api/admin/{module}           → Utilise verify.apikey
/api/v1/badges/*              → Utilise verify.apikey (legacy)
```

### Routes v1 (Bearer Token)
```
/api/v1/admin/{module}        → Utilise verify.bearer
/api/v1/badges/*              → Utilise verify.bearer
```

### Période de transition
Les routes CRUD et badges sont disponibles dans les deux groupes pour assurer une transition progressive :
- **Anciennes routes** (`/api/admin/*`, `/api/v1/badges/*`) : API Key + SSO
- **Nouvelles routes** (`/api/v1/admin/*`, `/api/v1/badges/*`) : Bearer Token

---

## Configuration Keycloak

Pour utiliser `verify.bearer`, assurez-vous que :

1. Le fichier de clés publiques est présent :
   ```
   storage/app/private/keycloak-public-keys.json
   ```

2. La variable d'environnement est définie :
   ```env
   KEYCLOAK_PUBLICKEY_FILENAME=keycloak-public-keys.json
   ```

3. L'URL de l'API ESTAIR est configurée :
   ```env
   ESTAIR_API_URL=http://localhost:8010
   ```

---

## Génération d'une API Key

Pour ESTAIR ou tout autre service externe :

```bash
curl -X POST http://localhost:8011/api/apikey \
  -H "Content-Type: application/json" \
  -d '{"name": "ESTAIR Production", "expires_at": "2025-12-31"}'
```

---

## Dépannage

### Erreur : "Access denied. API key or authentication required"
- Vérifiez que le header `X-API-KEY` est présent
- Ou que vous êtes authentifié via SSO (session active)

### Erreur : "user_unauthorized"
- Le token Bearer est manquant ou invalide
- Vérifiez que le fichier de clés publiques Keycloak est à jour

### Erreur : "public_key_not_found"
- Le `kid` (Key ID) du token ne correspond à aucune clé publique
- Mettez à jour le fichier `keycloak-public-keys.json`