Skip to content

docs: v2 — verified-only improvements (post-audit) #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pierrelaburthe wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: v2 — verified-only improvements (post-audit) #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 68 additions & 45 deletions docs/authentication/jwt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,33 @@
---
id: jwt
title: JWT
description: Authentification via le jeton JWT
description: Authentification via le jeton JWT — génération, transmission, cycle de vie de la session.
---

Ce mode d'authentification permet de connecter automatiquement les utilisateurs à Logora une fois qu'il sont authentifiés à travers votre système de connexion. Cette méthode utilise un jeton JWT (JSON Web Token) signé (JWS) ou chiffré (JWE) pour transmettre les données de l'utilisateur à Logora.
Ce mode d'authentification permet de connecter automatiquement les utilisateurs à Logora une fois qu'ils sont authentifiés à travers votre système de connexion. Cette méthode utilise un jeton **JWT** (JSON Web Token) signé (JWS) ou chiffré (JWE) pour transmettre les données de l'utilisateur à Logora.

### Avant de commencer
## Avant de commencer

- Rendez-vous sur votre [Espace d'administration](https://admin.logora.fr) onglet *Configuration > Authentification* pour choisir le mode d'authentification `JWT`.
- Munissez-vous de votre clé secrète d'API. Cette clé secrète vous servira à créer le jeton JWT. Elle doit rester confidentielle.
- Rendez-vous sur votre [Espace d'administration](https://admin.logora.fr) onglet *Configuration > Authentification* pour choisir le mode d'authentification `JWT`.
- Munissez-vous de votre clé secrète d'API. Cette clé secrète vous servira à créer le jeton JWT. Elle doit rester confidentielle.

### Processus d'authentification
## Processus d'authentification

1. Lorsque l'utilisateur se connecte sur votre site web, vous devez créer le jeton JWT contenant les informations de l'utilisateur. Il sera transmis à Logora.
1. Lorsque l'utilisateur se connecte sur votre site web, vous devez créer le jeton JWT contenant les informations de l'utilisateur. Il sera transmis à Logora.
2. Lorsque l'utilisateur se rend sur une page où est inséré le code Logora, le jeton JWT est inséré dans les variables de configuration Javascript, via le paramètre `remote_auth`.
3. L'application Logora détecte le jeton JWT, le décode, le vérifie et inscrit ou connecte l'utilisateur.

### Mise en place
## Mise en place

> ATTENTION : le jeton JWT transmis à Logora doit toujours être mis à jour selon l'état de l'utilisateur, qu'il soit connecté ou non. Si les pages de votre site web sont derrière un cache, notamment les pages qui contiennent la synthèse du débat, il est possible que le jeton JWT ne soit pas mis à jour. Si la mise en cache gêne la création du jeton JWT, utilisez une autre méthode d'authentification.
:::warning Pages mises en cache
Le jeton JWT transmis à Logora doit toujours être mis à jour selon l'état de l'utilisateur, qu'il soit connecté ou non. Si les pages de votre site web sont derrière un cache, notamment les pages qui contiennent la synthèse du débat, il est possible que le jeton JWT ne soit pas mis à jour. Si la mise en cache gêne la création du jeton JWT, utilisez une autre méthode d'authentification.
:::

### 1. Génération du jeton JWT

Grâce à la [sérialisation JSON Web Token](https://jwt.io/), les éditeurs peuvent transmettre les données utilisateurs existantes pour fournir aux utilisateurs une session authentifiée transparente sur Logora. Le jeton JWT doit être généré sur vos serveurs puis transmis à Logora via les variables de configuration javascript. Le jeton peut être signé ou chiffré, en fonction du degré de confidentialité que vous souhaitez obtenir pour les informations utilisateur.

##### Création du corps du jeton
#### Création du corps du jeton

Le corps du jeton contient les informations de l'utilisateur sous format JSON :

Expand All @@ -41,33 +43,38 @@ Le corps du jeton contient les informations de l'utilisateur sous format JSON :
```

Il doit inclure les attributs suivants, sensibles à la casse :

- `uid` : identifiant unique associé à l'utilisateur dans votre base de données.
- `first_name` : prénom de l'utilisateur, ou nom d'utilisateur si `last_name` est vide.
- `last_name` (optionnel) : nom de famille de l'utilisateur.
- `email` : l'adresse email enregistrée pour ce compte.
- `image_url` (optionnel) : lien vers l'avatar de l'utilisateur.
- `iat` : date de génération du jeton
- `exp` (optionnel) : date d'expiration du jeton. Si présent, la session ne démarrera pas si le jeton est expiré.
- `iat` : date de génération du jeton.
- `exp` (optionnel) : date d'expiration du jeton. Si présent, **la session ne démarrera pas si le jeton est expiré**.

Le nom des champs est personnalisable sur l'espace d'administration si vous avez un format différent.

Vous pouvez maintenant créer le jeton, soit en format JWS, ou soit sous format JWE. Si vous n'êtes pas sûr de quelle solution choisir, choisissez la version signée qui est la plus utilisée et la plus simple à mettre en place.

##### JWT signé (JWS)
#### JWT signé (JWS)

> **Important** : Si votre clé secrète est encodée en Base64, activez l'option correspondante dans votre espace d'administration.
:::note Clé secrète encodée en Base64
Si votre clé secrète est encodée en Base64, activez l'option correspondante dans votre espace d'administration.
:::

Le jeton est composée de trois parties, l'en-tête, le corps (payload) que vous avez généré précédemment et la signature.

En-tête du jeton
```
{
"alg": "HS256",
"typ": "JWT"
En-tête du jeton :

```json
{
"alg": "HS256",
"typ": "JWT"
}
```

Signature
Signature :

```
HMACSHA256(
base64UrlEncode(header) + "." +
Expand All @@ -76,11 +83,12 @@ HMACSHA256(
)
```

Exemple en pseudo-code
```
header = {
"alg": "HS256",
"typ": "JWT"
Exemple en pseudo-code :

```javascript
header = {
"alg": "HS256",
"typ": "JWT"
}
payload = {
uid: "123abc",
Expand All @@ -97,47 +105,62 @@ signature = HMACSHA256(

// Variable transmise à Logora
jetonJWT = base64UrlEncode(header) + "." + base64UrlEncode(payload) + "." + signature
=> "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiIxMjNhYmMiLCJmaXJzdF9uYW1lIjoiSmVhbiIsImxhc3RfbmFtZSI6IkR1cG9udCIsImVtYWlsIjoiamVhbmR1cG9udEBleGVtcGxlLmNvbSIsImlhdCI6MTUxNjIzOTAyMn0.ITnJo8VwbP4PkVTANSt651C0olsrdRNCNmvTHkanuYk"
```
Avant de passer à la deuxième étape, vérifiez le bon fonctionnement du jeton sur le site web : https://jwt.io/

##### JWT chiffré (JWE)
Avant de passer à la deuxième étape, vérifiez le bon fonctionnement du jeton sur le site web : [https://jwt.io/](https://jwt.io/).

Pour utiliser ce type de jeton, choisissez l'option "JWE" dans les paramètres de l'espace d'administration.
Le chiffrement du jeton permet de ne pas divulguer les informations utilisateur. Nous ne supportons que les clés de type RSA (RSA-OAEP et RSA1_5).
#### JWT chiffré (JWE)

Pour générer le jeton, nous vous proposons de lire cet article qui explique le processus : https://dzone.com/articles/using-json-web-encryption-jwe
Pour utiliser ce type de jeton, choisissez l'option « JWE » dans les paramètres de l'espace d'administration. Le chiffrement du jeton permet de ne pas divulguer les informations utilisateur. Nous ne supportons que les clés de type RSA (RSA-OAEP et RSA1_5).

Voici un exemple de jeton généré avec le corps généré précédemment, et qui sera transmis à Logora :
```
eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhHQ00ifQ.FuNsYUYJzh294MQZ_71zOxBLiiOkU8UKF4b-wwhCKNKCm1452jnyxzljNTCkTGVhZui6CnBctUByqdvVugMzIlWxNA4hSXWvQUKxm-QJlJyqbdeL6URM2mxeqBxk3iEA7TIbLCd30pnFo8KkSbbHmkDVrVElJ403t0bNKPlvJkjU_Dc71tP3Zun-Nc_3PK9azldEZ7IEPYvd--leYPBBTThNZ--SHSWx_C8rF5a3PHaniVttguHX4EJ39V36xz_7FWFXh4ZNCCFp_kqa05_ixD0EEH11kpxdOv-wm_MgOyt9XODoIWqZUrcDywCkhNy_gIHP8LHbHFhyHR3o8qQvhQ.s_bngM9ad5tmrkQH.GJUshscvO9ZtspkyH-emLbbgyczh_uzFTbv_QEWM3iryARl0UrvYzaBjyBIr3o16bw4PfUCK-4TXTRzV4C56s63BNIwL7fY0AQXrBfRifg8AtaIg0NJyJXbnUzqB7Gx23KruL9g.zSNCxobkIFdAY82DRf1Qdw
```
Pour générer le jeton, nous vous proposons de lire cet article qui explique le processus : [https://dzone.com/articles/using-json-web-encryption-jwe](https://dzone.com/articles/using-json-web-encryption-jwe).

Avant de passer à la deuxième étape, vérifiez le bon fonctionnement du jeton sur le site web : https://dinochiesa.github.io/jwt/
Vérifiez le bon fonctionnement du jeton sur : [https://dinochiesa.github.io/jwt/](https://dinochiesa.github.io/jwt/).

### 2. Transmission du jeton à Logora

Une fois que le message a été généré, il doit être transmis via la variable de configuration Javascript, `remote_auth`, dans le code de l'espace de débat.
Une fois que le message a été généré, il doit être transmis via la variable de configuration Javascript, `remote_auth`, dans le code de l'espace de débat :

```javascript
var logora_config = {
remote_auth: jeton_JWT
remote_auth: jeton_JWT
}
```

Il faut également remplir l'interface sur l'espace d'administration :

![Admin JWT](/img/jwtadmin.png)
Il faut également remplir l'interface sur l'espace d'administration.

### 3. Déconnexion de l'utilisateur

Pour déconnecter l'utilisateur, retirez le paramètre `remote_auth` ou transmettez une chaîne de caractères vide. Si le paramètre est vide, Logora considère que l'utilisateur est déconnecté.

### 4. Redirection vers l'espace de débat après connexion de l'utilisateur
Pour une déconnexion **côté serveur en temps réel**, utilisez le [Backchannel Logout](/authentication/backchannel-logout).

### 4. Redirection vers l'espace de débat après connexion

Lorsqu'un utilisateur non connecté veut effectuer une action sur l'espace de débat, il est redirigé vers votre page de connexion ou d'inscription. Lors de l'insertion de l'espace de débat et de la synthèse, vous devez définir les URLs de connexion et d'inscription, respectivement via les variables `auth.login_url` et `auth.registration_url`.

Lors de la redirection, un paramètre de requête `logora_redirect` est transmis, contenant l'URL de la page avant redirection. Utilisez ce paramètre pour rediriger l'utilisateur après sa connexion ou son inscription. Le nom du paramètre transmis peut être modifié, il peut être par exemple défini à `redirect_to`.

Ces paramètres peuvent être changés dans l'espace d'administration, dans l'onglet *Configuration > Authentification*.

---

## Cycle de vie de la session

### Durée d'une session Logora

Une fois le JWT validé, Logora ouvre **sa propre session** indépendamment de la vôtre. Cette session expire **2 heures après** sa création par défaut.

Si vous souhaitez forcer une déconnexion avant cette échéance, utilisez le [Backchannel Logout](/authentication/backchannel-logout).

Lorsqu'un utilisateur non connecté veut effectuer une action sur l'espace de débat, il est redirigé vers votre page de connexion ou d'inscription. Lors de l'insertion de l'espace de débat et de la synthèse, vous devez définir les URLs de connexion et d'inscription, respectivement via les variables auth.login_url et auth.registration_url.
### Validation du claim `exp`

Lors de la redirection, un paramètre de requête logora_redirect est transmis, contenant l'URL de la page avant redirection. Utilisez ce paramètre pour rediriger l'utilisateur après sa connexion ou son inscription. Le nom du paramètre transmis peut être modifié, il peut être par exemple défini à redirect_to.
Si le claim `exp` est présent dans le JWT, Logora vérifie qu'il n'est pas expiré. Un jeton expiré ne démarrera pas de session.

Ces paramètres peuvent être changés dans l'espace d'administration, dans l'onglet *Configuration > Authentification*
:::tip Bonne pratique pour limiter la réutilisation
Si vous craignez qu'un token soit rejoué :

1. **Toujours inclure un claim `exp` court** dans le JWT
2. **Mettre à jour le `remote_auth` à chaque rendu de page** (pas de cache HTML qui fige le token)
3. **Appeler le backchannel logout côté serveur** lors de la déconnexion utilisateur sur votre site
:::
65 changes: 65 additions & 0 deletions docs/faq/account-deletion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
---
id: account-deletion
title: Suppression et anonymisation d'un utilisateur
description: Comment anonymiser ou supprimer un utilisateur via l'API Logora, et comment notifier Logora d'une suppression côté SSO.
sidebar_label: Suppression d'utilisateur
---

L'API Logora propose deux opérations pour gérer la suppression d'un utilisateur, selon votre besoin :

| Opération | Effet sur les contributions | Endpoint |
|---|---|---|
| **Anonymiser** | ✅ Conservées (auteur masqué) | `POST /api/v1/users/{user_uid}/anonymize` |
| **Supprimer** | ❌ Supprimées | `DELETE /api/v1/users/{user_uid}` |

Choisissez selon le contexte :

- **Demande RGPD d'effacement** → anonymisation suffit dans la plupart des cas (équilibre entre droit à l'oubli et préservation du contenu public).
- **Suppression définitive** (compte test, doublon, fraude avérée) → suppression complète.

## Anonymiser un utilisateur

```http
POST https://app.logora.fr/api/v1/users/{user_uid}/anonymize
Authorization: Bearer YOUR_TOKEN
```

Le `user_uid` est l'identifiant unique que **vous** transmettez à Logora via le SSO (champ `uid` du JWT).

Réponse `200` en cas de succès.

## Supprimer un utilisateur

```http
DELETE https://app.logora.fr/api/v1/users/{user_uid}
Authorization: Bearer YOUR_TOKEN
```

:::caution Action irréversible
La suppression efface l'utilisateur **et toutes ses contributions associées**. Cette opération n'est pas réversible.
:::

## Notifier Logora d'une suppression côté votre système (Backchannel Logout)

Si votre système d'authentification gère la suppression des comptes côté serveur (ex. RGPD via votre back-office), vous pouvez notifier Logora en temps réel via le [Backchannel Logout](/authentication/backchannel-logout).

L'endpoint accepte un JWT signé contenant les informations de la suppression.

```http
POST https://app.logora.fr/auth/logout/{shortname}
Content-Type: application/x-www-form-urlencoded

logout_token=YOUR_SIGNED_JWT
```

Voir la page dédiée pour le détail des claims attendus.

## Test via Swagger

Les deux endpoints `anonymize` et `delete` sont testables directement depuis le **[Swagger interactif](https://app.logora.fr/docs)**, section *Users*.

## Voir aussi

- [API publique Logora](/faq/api)
- [Backchannel Logout](/authentication/backchannel-logout)
- [Gestion des utilisateurs (FAQ)](/faq/data) — vue d'ensemble RGPD
Loading