# Note d'intégration : LoginLibrary

Cette note explique comment intégrer la bibliothèque `LoginLibrary` dans un nouveau projet (ex: application Laravel).

## 1. Ajout de la dépendance

Dans le fichier `composer.json` de votre projet cible, ajoutez le chemin local vers la bibliothèque dans la section `repositories` :

```json
"repositories": [
    {
        "type": "path",
        "url": "c:/wamp64/www/LoginLibrary"
    }
],
```

Ensuite, installez le package avec Composer en ligne de commande :

```bash
composer require grimaud/login-iam-library:@dev
```

## 2. Configuration Keycloak

Créez un fichier de configuration `config/keycloak.php` dans votre projet pour définir les paramètres de connexion au serveur Keycloak :

```php
<?php

return [
    'issuer'                 => env('KEYCLOAK_ISSUER', 'https://keycloak.mairie-grimaud.fr/realms/VotreRealm'),
    'client_id'              => env('KEYCLOAK_CLIENT_ID', 'votre_client_id'),
    'client_secret'          => env('KEYCLOAK_CLIENT_SECRET', ''), // Facultatif si c'est un client public
    'authorization_endpoint' => env('KEYCLOAK_AUTH_ENDPOINT', 'https://keycloak.mairie-grimaud.fr/.../auth'),
    'end_session_endpoint'   => env('KEYCLOAK_LOGOUT_ENDPOINT', 'https://keycloak.mairie-grimaud.fr/.../logout'),
    'scope'                  => env('KEYCLOAK_SCOPE', 'openid profile email'),
    'verify'                 => env('KEYCLOAK_VERIFY_SSL', true), // false en dev local sans HTTPS
];
```

Pensez à bien déclarer ces variables dans votre fichier `.env`.

## 3. Mise en place de l'authentification (Contrôleur)

Vous devrez implémenter un contrôleur (par ex: `AuthController`) avec les trois étapes clés du flux OIDC :

### A. Connexion (Login)
1. Instanciez `Grimaud\LoginIamLibrary\AuthService`.
2. Générez des paramètres aléatoires PKCE (`state` et `code_verifier`).
3. Sauvegardez-les en session Laravel (`session(['oauth_state' => $state, 'oauth_code_verifier' => $codeVerifier])`).
4. Redirigez l'utilisateur vers l'URL fournie par `$authService->getAuthorizationUrl()`.

### B. Traitement du retour (Callback)
1. Vérifiez que le `state` reçu dans la requête correspond à celui en session (protection CSRF).
2. Échangez le code d'autorisation contre des jetons via `$authService->exchangeCodeForTokens()`.
3. Sauvegardez au minimum l'`access_token` et l'`id_token` en session.
4. Identifiez l'utilisateur avec `$authService->authenticateAndAuthorize($accessToken)->getTokenInfo()` si vous souhaitez le lier à un modèle `User` local.

### C. Déconnexion (Logout)
1. Récupérez l'`id_token` stocké en session.
2. Videz la session Laravel (`session()->flush()`).
3. Redirigez l'utilisateur vers l'URL de déconnexion globale générée par `$authService->getLogoutUrl()`.

## 4. Gestion des autorisations dans votre code

Pour protéger vos routes ou conditionner l'affichage selon les droits de l'utilisateur, utilisez l'`access_token` stocké en session :

```php
use Grimaud\LoginIamLibrary\AuthService;
use Grimaud\LoginIamLibrary\Exceptions\TokenException;

try {
    $authService = new AuthService(config('keycloak'));
    $checker = $authService->authenticateAndAuthorize(session('access_token'));

    // 1. Informations de l'utilisateur
    $email = $checker->getTokenInfo()->getEmail();

    // 2. Vérifier l'appartenance à un groupe Keycloak
    if ($checker->isInGroup('/Direction')) {
        // L'utilisateur est dans le groupe Direction
    }

    // 3. Vérifier la présence d'un rôle (client ou realm)
    if ($checker->hasRole('admin')) {
        // L'utilisateur possède le rôle admin
    }

} catch (TokenException $e) {
    // Le token est invalide, expiré, ou la session a été interrompue.
    // -> Rediriger vers la page de login ou renvoyer une erreur 401
}
```

---

## 5. Vérification du statut du compte (Active Directory / ACCOUNTDISABLE)

> **Contexte** : Keycloak synchronise les comptes depuis Active Directory, mais le mapper `msad-user-account-control-mapper` ne remonte pas l'information `enabled/disabled` dans le JWT.  
> La librairie propose un mécanisme dédié qui interroge l'**API Admin REST Keycloak** pour lire le champ `enabled` du compte directement depuis Keycloak.

### A. Configuration supplémentaire

Ajoutez les clés suivantes dans `config/keycloak.php` (ou votre tableau de config) :

```php
// Activation de la vérification du statut compte
'admin_check_account'  => env('KEYCLOAK_ADMIN_CHECK', true),

// URL racine Keycloak (sans /realms/..., sans slash final)
'admin_base_url'       => env('KEYCLOAK_ADMIN_BASE_URL', 'https://keycloak.mairie-grimaud.fr'),

// Nom du realm
'realm'                => env('KEYCLOAK_REALM', 'VotreRealm'),

// Client Keycloak disposant du Service Account avec le rôle "view-users"
'admin_client_id'      => env('KEYCLOAK_ADMIN_CLIENT_ID', 'votre-admin-client'),
'admin_client_secret'  => env('KEYCLOAK_ADMIN_CLIENT_SECRET', 'xxxxxxxxxxxxxxxx'),
```

> **Prérequis Keycloak** : dans la console d'administration, le client `admin_client_id` doit avoir :
> - **Service Accounts Enabled** : activé
> - **Rôle Service Account** : `view-users` (dans `realm-management`)

### B. Variables `.env` associées

```dotenv
KEYCLOAK_ADMIN_CHECK=true
KEYCLOAK_ADMIN_BASE_URL=https://keycloak.mairie-grimaud.fr
KEYCLOAK_REALM=VotreRealm
KEYCLOAK_ADMIN_CLIENT_ID=votre-admin-client
KEYCLOAK_ADMIN_CLIENT_SECRET=xxxxxxxxxxxxxxxx
```

### C. Utilisation dans le callback de connexion

Lorsque `admin_check_account => true`, `validateToken()` (appelé en interne par `authenticateAndAuthorize()`) interroge automatiquement l'API Admin **après** la validation JWT.

```php
$authService = new AuthService(config('keycloak'));

try {
    $checker   = $authService->authenticateAndAuthorize(session('access_token'));
    $tokenInfo = $checker->getTokenInfo();

    // Vérifier que le compte est bien actif côté AD
    if (!$tokenInfo->isAccountEnabled()) {
        // Compte désactivé dans Active Directory (bit ACCOUNTDISABLE positionné)
        session()->flush();
        return redirect('/login')->withErrors(['auth' => 'Votre compte est désactivé.']);
    }

    // Suite du traitement normal...

} catch (TokenException $e) {
    abort(401, 'Session expirée ou token invalide.');
}
```

> **Méthodes disponibles sur `TokenInfo`** :
> | Méthode | Retour | Description |
> |---|---|---|
> | `isAccountEnabled()` | `bool` | `true` = actif, `false` = désactivé. Lève `\LogicException` si la vérification n'a pas été activée. |
> | `isAccountStatusChecked()` | `bool` | Permet de tester si `isAccountEnabled()` est appelable sans risque. |

### D. Checklist des cas à tester obligatoirement

Avant de mettre en production, l'application intégrante **doit** avoir testé les scénarios suivants :

| # | Scénario | Comportement attendu |
|---|---|---|
| 1 | Connexion d'un compte **actif** (non désactivé dans AD) | Authentification réussie, `isAccountEnabled()` retourne `true` |
| 2 | Connexion d'un compte **désactivé dans AD** (ACCOUNTDISABLE) | L'utilisateur a pu obtenir un token Keycloak, mais `isAccountEnabled()` retourne `false` → l'appli doit refuser l'accès et détruire la session |
| 3 | Compte **réactivé dans AD** après une désactivation | Au prochain login, `isAccountEnabled()` retourne `true` — vérifier qu'il n'y a pas de cache applicatif persistant l'ancien état |
| 4 | `admin_check_account` non activé | `isAccountEnabled()` lève une `\LogicException` — vérifier que l'appli ne l'appelle pas dans ce cas, ou utilise `isAccountStatusChecked()` en garde |
| 5 | Service account mal configuré (mauvais secret ou rôle manquant) | `validateToken()` lève une `TokenException` — vérifier que l'appli gère ce cas et renvoie une erreur 500 lisible |
| 6 | Keycloak Admin API indisponible | `validateToken()` lève une `TokenException` — prévoir un fallback ou une page d'erreur dédiée |
| 7 | Token expiré **et** compte désactivé | `TokenException` levée en premier (expiration avant appel Admin) — s'assurer que l'ordre de traitement est correct |
| 8 | Appel de `isAccountEnabled()` **sans** `admin_check_account` | `\LogicException` levée — l'appli doit vérifier `isAccountStatusChecked()` ou garantir la config avant l'appel |
