PD-241 — Déconnexion utilisateur (logout)¶

1. Objectif¶

Décrire précisément le contrat canonique de l'endpoint backend permettant à un utilisateur authentifié d'invalider sa session côté serveur via POST /auth/logout.

2. Périmètre / Hors périmètre¶

Inclus¶

• Endpoint POST /auth/logout.
• Authentification JWT obligatoire.
• Invalidation de la session Keycloak (révocation du token).
• Invalidation du refresh token si présent.
• Format d'erreur contractuel : {error: "ERR-241-*", message: "..."}.
• Retour d'une erreur explicite en cas d'échec d'invalidation Keycloak.
• Compatibilité contractuelle avec PD-106 (F-106-06, INV-106-13, CA-106-13/14, ERR-106-LOGOUT-FAILED). PD-241 retourne ERR-241-LOGOUT-FAILED, que PD-106 doit traiter comme équivalent à ERR-106-LOGOUT-FAILED.

Exclu¶

• Effacement des données locales côté client (responsabilité PD-106).
• Gestion MFA (PD-238).
• Gestion de profil (PD-32).
• Suppression de compte (PD-240).

3. Définitions¶

• Déconnexion : invalidation de la session serveur associée au JWT/refresh token.
• Session Keycloak : session OIDC côté Keycloak associée au JWT/refresh token.
• Refresh token : jeton de rafraîchissement associé à la session, s'il existe.
• Transmission du refresh token : le refresh token est transmis dans le body JSON de POST /auth/logout sous la clé optionnelle refresh_token.
• Erreur explicite : réponse d'erreur contenant un code ERR-241-* et un message exploitable.
• Hors périmètre : exigence non vérifiable via PD-241 seul et devant être prouvée par un artefact externe.

4. Invariants (non négociables)¶

5. Flux nominaux¶

F-241-01 — Déconnexion nominale¶

1. Le client appelle POST /auth/logout avec un JWT valide (et refresh_token si présent).
2. Le système invalide la session Keycloak associée.
3. Le système invalide le refresh token si présent.
4. Le système retourne un succès explicite.

5b. Diagrammes¶

Séquence — Déconnexion nominale (F-241-01)¶

sequenceDiagram
    participant C as Client (PD-106)
    participant B as Backend POST /auth/logout
    participant K as Keycloak Admin API

    C->>B: POST /auth/logout<br/>Authorization: Bearer {JWT}<br/>Body: { refresh_token? }
    Note right of B: INV-241-01 — JWT valide exigé

    B->>K: DELETE /admin/realms/{realm}/sessions/{sessionId}
    K-->>B: 204 No Content
    Note right of B: INV-241-02 — Session Keycloak invalidée

    opt refresh_token présent
        B->>K: POST /realms/{realm}/protocol/openid-connect/revoke<br/>token={refresh_token}
        K-->>B: 200 OK
        Note right of B: INV-241-03 — Refresh token invalidé
    end

    B-->>C: 200 OK

Séquence — Échec Keycloak (ERR-241-LOGOUT-FAILED)¶

sequenceDiagram
    participant C as Client (PD-106)
    participant B as Backend POST /auth/logout
    participant K as Keycloak Admin API

    C->>B: POST /auth/logout<br/>Authorization: Bearer {JWT}
    B->>K: DELETE /admin/realms/{realm}/sessions/{sessionId}
    K-->>B: 500 / timeout

    Note right of B: INV-241-05 — Erreur explicite obligatoire
    B-->>C: 502 Bad Gateway<br/>{ error: "ERR-241-LOGOUT-FAILED", message: "..." }
    Note right of B: INV-241-04 — Format {error, message} respecté

6. Cas d'erreur¶

7. Critères d'acceptation (testables)¶

8. Scénarios de test (Given / When / Then)¶

Scenario 1 — Déconnexion nominale¶

GIVEN utilisateur authentifié avec JWT valide (et refresh token si présent). WHEN POST /auth/logout. THEN la session Keycloak est invalidée et la réponse indique un succès explicite.

Scenario 2 — Rejet sans JWT¶

GIVEN aucun JWT valide. WHEN POST /auth/logout. THEN refus explicite (ERR-241-UNAUTHENTICATED).

Scenario 3 — Échec invalidation Keycloak¶

GIVEN utilisateur authentifié. WHEN Keycloak échoue lors de l'invalidation. THEN erreur explicite ERR-241-LOGOUT-FAILED.

Scenario 4 — Invalidation refresh token¶

GIVEN utilisateur authentifié avec refresh token. WHEN POST /auth/logout. THEN le refresh token est invalide à toute tentative de réutilisation.

Scenario 5 — Hors périmètre PD-106¶

GIVEN périmètre PD-241. WHEN la preuve d'effacement local est demandée. THEN hors périmètre (artefact client PD-106).

9. Hypothèses explicites¶

Références¶

• Epic : PD-182 AUTH
• JIRA : PD-241
• Repos concernés : ProbatioVault-backend
• Documents associés : PD-241-besoin.md, PD-106-specification.md