# Grimaud Login IAM Library

Bibliothèque PHP permettant d'encapsuler l'authentification OIDC avec Keycloak et la gestion des autorisations (rôles, groupes, permissions).

## 1. Installation

Dans l'application cible (par exemple `UsersManager`), ajoutez ce package en tant que dépôt local dans le fichier `composer.json` :

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

Puis installez-le via la ligne de commande :
```bash
composer require grimaud/login-iam-library:@dev
```

## 2. Configuration (exemple avec Laravel)

Créez un fichier `config/keycloak.php` qui retourne les paramètres de connexion :

```php
<?php

return [
    'issuer'                 => env('KEYCLOAK_ISSUER', 'https://keycloak.mairie-grimaud.fr/realms/Users%20Authentification'),
    'client_id'              => env('KEYCLOAK_CLIENT_ID', 'usersmanager'),
    'client_secret'          => env('KEYCLOAK_CLIENT_SECRET', ''), // Optionnel si 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'), // Optionnel (déduit auto. depuis auth)
    'scope'                  => env('KEYCLOAK_SCOPE', 'openid profile email'),
    'verify'                 => env('KEYCLOAK_VERIFY_SSL', true), // Mettre à false en dév si pas de certificat

    // --- Vérification du statut compte AD (optionnel, voir section 6) ---
    'admin_check_account'    => env('KEYCLOAK_ADMIN_CHECK', false),
    'admin_base_url'         => env('KEYCLOAK_ADMIN_BASE_URL', 'https://keycloak.mairie-grimaud.fr'),
    'realm'                  => env('KEYCLOAK_REALM', 'Users Authentification'),
    'admin_client_id'        => env('KEYCLOAK_ADMIN_CLIENT_ID', ''),
    'admin_client_secret'    => env('KEYCLOAK_ADMIN_CLIENT_SECRET', ''),
];
```

## 3. Utilisation dans un Contrôleur (Flux OIDC)

### A. Rediriger l'utilisateur vers Keycloak (Login)

```php
use Grimaud\LoginIamLibrary\AuthService;
use Illuminate\Support\Str;

public function login()
{
    $authService = new AuthService(config('keycloak'));
    
    // PKCE et State pour la sécurité
    $state = Str::random(40);
    $codeVerifier = Str::random(128);
    
    // Sauvegarde en session pour vérifier au retour
    session(['oauth_state' => $state, 'oauth_code_verifier' => $codeVerifier]);
    
    $redirectUri = route('auth.callback');
    $url = $authService->getAuthorizationUrl($state, $codeVerifier, $redirectUri);
    
    return redirect($url);
}
```

### B. Traiter le retour de Keycloak (Callback)

```php
public function callback(\Illuminate\Http\Request $request)
{
    // Vérification du state (contre les attaques CSRF)
    if ($request->state !== session('oauth_state')) {
        abort(403, 'State invalide');
    }

    $authService = new AuthService(config('keycloak'));
    $codeVerifier = session('oauth_code_verifier');
    
    try {
        // 1. Échange du code contre les tokens
        $tokens = $authService->exchangeCodeForTokens(
            $request->code, 
            route('auth.callback'), 
            $codeVerifier
        );
        
        $accessToken = $tokens['access_token'];
        $idToken = $tokens['id_token'] ?? null;
        
        // 2. Validation du token et extraction des informations
        $checker = $authService->authenticateAndAuthorize($accessToken);
        $userInfo = $checker->getTokenInfo();
        
        // 3. Connecter l'utilisateur dans Laravel (optionnel)
        // ex: $user = User::firstOrCreate(['email' => $userInfo->getEmail()]);
        // Auth::login($user);
        
        // Stocker l'access_token et l'id_token en session (pour les APIs et la déconnexion)
        session([
            'access_token' => $accessToken,
            'id_token'     => $idToken
        ]);
        
        return redirect('/dashboard');
        
    } catch (\Exception $e) {
        return "Erreur d'authentification : " . $e->getMessage();
    }
}
```

## 4. Déconnexion (RP-Initiated Logout)

Pour déconnecter l'utilisateur proprement de votre application ET de Keycloak (Single Sign-Out) :

```php
public function logout()
{
    $authService = new AuthService(config('keycloak'));
    
    // Récupération de l'id_token stocké lors de la connexion
    $idToken = session('id_token');
    
    // On vide la session de l'application
    session()->flush();
    
    // On redirige vers Keycloak pour fermer la session globale
    // (Keycloak va ensuite rediriger l'utilisateur vers route('home'))
    $url = $authService->getLogoutUrl($idToken, route('home'));
    
    return redirect($url);
}
```

## 5. Vérifier les autorisations (Middlewares ou Contrôleurs)

Une fois que vous avez l' `access_token` (récupéré depuis la session ou via le header d'une API `Bearer Token`), vous pouvez vérifier les droits très facilement :

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

$authService = new AuthService(config('keycloak'));
$accessToken = session('access_token'); // Ou request()->bearerToken()

try {
    $checker = $authService->authenticateAndAuthorize($accessToken);
    
    // -- Informations utilisateur --
    $email = $checker->getTokenInfo()->getEmail();
    $name = $checker->getTokenInfo()->getName();
    
    // -- Vérifications des Groupes --
    if ($checker->isInGroup('/Direction')) {
        // Action autorisée
    }
    
    // -- Vérifications des Rôles --
    if ($checker->hasRole('admin')) { // Cherche dans le realm et le client_id configuré
        // Action autorisée
    }
    
    if ($checker->hasRealmRole('super-admin')) {
        // ...
    }

} catch (TokenException $e) {
    // Token expiré ou signature invalide
    abort(401, 'Session expirée, veuillez vous reconnecter.');
}
```

---

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

> **Contexte** : Keycloak synchronise les comptes depuis Active Directory via LDAP, mais le mapper `msad-user-account-control-mapper` ne remonte **pas** le statut `enabled/disabled` dans le JWT.  
> La librairie interroge l'**API Admin REST Keycloak** directement, après la validation JWT, pour lire le champ `enabled` réel du compte.

### Prérequis Keycloak

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

### Configuration `.env`

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

### Utilisation dans le callback

Lorsque `admin_check_account => true`, la vérification est **automatique** lors de l'appel à `authenticateAndAuthorize()` ou `validateToken()`.

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

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

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

    // Traitement normal...

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

### Méthodes `TokenInfo` liées au statut compte

| Méthode | Retour | Comportement |
|---|---|---|
| `isAccountEnabled()` | `bool` | `true` = actif, `false` = désactivé (ACCOUNTDISABLE AD). Lève `\LogicException` si `admin_check_account` n'est pas activé. |
| `isAccountStatusChecked()` | `bool` | `true` si la vérification a été effectuée — permet d'appeler `isAccountEnabled()` sans risque. |

### Checklist des cas à tester obligatoirement

Avant toute mise en production, l'application **doit** valider les scénarios suivants :

| # | Scénario | Comportement attendu |
|---|---|---|
| 1 | Connexion avec un compte **actif** dans AD | Authentification réussie — `isAccountEnabled()` retourne `true` |
| 2 | Connexion avec un compte **désactivé dans AD** (ACCOUNTDISABLE) | Le JWT est valide, mais `isAccountEnabled()` retourne `false` — l'appli doit refuser l'accès et détruire la session |
| 3 | Compte **réactivé** dans AD après désactivation | Au prochain login, `isAccountEnabled()` retourne `true` — vérifier l'absence de cache applicatif persistant l'ancien état |
| 4 | `admin_check_account` désactivé (`false`) | `isAccountEnabled()` lève `\LogicException` — l'appli ne doit pas l'appeler, ou utiliser `isAccountStatusChecked()` en garde |
| 5 | **Mauvais secret** ou rôle `view-users` manquant | `validateToken()` lève `TokenException` — l'appli doit capturer l'erreur et renvoyer une erreur serveur lisible |
| 6 | **API Admin Keycloak indisponible** | `validateToken()` lève `TokenException` — prévoir un fallback ou une page d'erreur dédiée |
| 7 | **Token JWT expiré** et compte désactivé | `TokenException` levée en premier (expiration détectée avant appel Admin) — vérifier l'ordre de traitement dans le `catch` |
| 8 | Appel de `isAccountEnabled()` sans `admin_check_account` | `\LogicException` levée — utiliser `isAccountStatusChecked()` comme garde ou garantir la config avant l'appel |
