---
title: Auth et logique de session
slug: oip-next/v3/auth-session
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-13T11:48:01.000Z
---

Ce chapitre a pour objectif de vous expliquer, d'une part comment fonctionne la logique de session et l'initialisation d'un nouveau projet sur votre OAV lors du décrochage et d'autre part l'authentification du client (de l'application *React*) au server.

::Image[]{src="https://api.archbee.com/api/optimize/Q9knVHkDeLR_ZZUvMbkiz-LPVS5TAlTmA15Pa_vEy-G-20250314-140833.jpg" size="52" width="993" height="669" position="center" darkWidth="993" darkHeight="669" showCaption="false"}

# Session utilisateur&#x20;

À chaque nouvelle connexion du client, le serveur crée une nouvelle session et génère un cookie. Les sessions et leurs informations sont sauvegardées dans la collection `sessions` de la base de données MongoDB.

Les variables d'environnement suivantes sont liées au cookie de session :

- `SESSION_COOKIE_MAX_AGE` le temps en minutes avant expiration du cookie et de la session utilisateur, 60 minutes par défaut.
- `SESSION_SECRET` la chaîne de caractères utilisée pour signer l'id de la session liée au cookie.

Souvenez vous qu'une session utilisateur peut être liée à plusieurs projets client.

# Générer un token de session

Pour générer un token de session, assurez-vous que le service *fasst-sessions&#x20;*(ou un service équivalent) est lancé et accessible depuis la *stack* de votre projet.

**Un token de session généré ne peut être « consommé »  qu'une seule fois par votre OAV.**

Exemple avec *fasst-sessions* en local :

```shell
curl --request POST \
  --url http://localhost:3005/api/sessions/tokens \
  --header 'Content-Type: application/json' \
  --data '{
  "applicant": "magic",
  "metadata": {
    "externalId": "project-AAA"
  }
}'
```

Lors de l'appel à votre service de sessions, assurez-vous de renseigner la bonne URL et les bons paramètres en fonction de votre environnement.

Le champ `metadata` du *body* de la requête correspond au *context&#x20;*&#x63;lient du projet. Vous pouvez renseigner par exemple l'identifiant client du projet, champ `metadata.externalId` ou toutes autres informations utiles qui vous seront nécessaires lors de la création et l'initialisation de l'entité *Project*.

Vous obtiendrez alors en réponse un objet JSON contenant votre token de session :

```json
{ "token": "my-generated-token" }
```

# Callback d'initialisation du projet

Côté serveur, le fichier `server/controllers/project/project.mjs` expose la *callback* d'initialisation du projet `initProjectFromContext` qui vous permet de créer et d'initialiser l'entité *Project* selon les besoins et les spécificités de votre OAV et du contexte client.

***La callback&#x20;***`initProjectFromContext`***&#x20;est passée en paramètre à la méthode&#x20;***`startServer`***&#x20;importée depuis la dépendance&#x20;***`@fasstech/oip-starter-utils`***. La méthode&#x20;***`startServer`***&#x20;est appelée dans le fichier&#x20;***`server/index.mjs`***&#x20;de votre OAV et initialise le server.***

La *callback* `initProjectFromContext` reçoit en paramètre l'objet *context&#x20;*&#x71;ui correspond au contexte client du projet lié au token généré.

***Depuis la version v3.4.1 de la dépendance @fasstech/oip-starter-utils, la callback d'initialisation du projet reçoit en second paramètre&#x20;***`sessionId`***&#x20;qui correspond à l'identifiant de la session utilisateur actuelle.***

Exemple :

:::CodeblockTabs
project.mjs

```javascript
import { Entities } from '@fasstech/oip-core';

export const initProjectFromContext = async (context, sessionId) => {
  // retrieve info from context client
  const { externalId } = context;
  
  // try to get an existing Project entity
  let project = await Entities('Project').get({ externalId });
  
  // if the project exists, we must return it
  if (project) {
    return project;
  }

  // else we create a new one and init it
  project = await Entities('Project').create({ externalId });
  project = await Entities('Project').save(project);
  
  // and return it
  return project;
};
```
:::

# Décrocher sur l'OAV

Deux types de décrochage sur l'OAV sont possibles. Décrocher avec un token ou avec l'identifiant interne d'un projet.

Ainsi, lors du décrochage sur l'OAV via son URL, un de ces deux paramètres (*query string parameters*) est attendu :

- `token` dont la valeur attendue correspond à un token fraîchement généré par votre service de sessions
- `projectId` dont la valeur attendue correspond à l'identifiant d'un projet (`id` de l'entité *Project*) précédemment initialisé lors de la même session utilisateur

## Décrocher avec un token

:::BlockQuote
*http\://localhost:8000/?token=my-generated-token*
:::

Si le paramètre d'URL `token` est trouvé lors du décrochage, le code client fait un appel HTTP au server pour initlialiser l'entité *Project* à partir du token et ainsi lier le projet à la session utilisateur en cours :

:::CodeblockTabs
HTTP client => server

```none
GET /session?token=my-generated-token
```
:::

Le server essaie alors de récupérer le *context&#x20;*&#x63;lient lié au token par un appel HTTP au service de sessions (le même service qui a généré le token) :

:::CodeblockTabs
HTTP server => service-sessions

```none
GET ${SESSIONS_SERVICE_URL}/api/sessions/tokens?token=${token}&sessionId=null
```
:::

Si l'appel réussi un objet qui représente le *context&#x20;*&#x63;lient du projet est reçu en réponse :

```json
{ "externalId": "project-AAA" }
```

Une fois le *context* du projet récupéré, la callback d'initialisation du projet est appellée avec *context* passé en paramètre et l'entité *Project* est initialisée ou récupérée et liée à la session utilisateur en cours.

Enfin, en réponse à l'appel initial `GET /session` du client, le server renvoie `projectId` qui correspond à l'identifiant de l'entité *Project* résolue.

***Si une erreur survient lors du processus, une erreur 401 est renvoyée au client.***

## Décrocher avec l'identifiant d'un projet

:::BlockQuote
*http\://localhost:8000/?projectId=xxxxx*
:::

Si le paramètre d'URL `projectId` est trouvé lors du décrochage, le code client fait un appel HTTP au server pour essayer de récupérer l'entité *Project* existante :

:::CodeblockTabs
HTTP client => server

```none
GET /session?projectId=xxxxx
```
:::

**\*Si l'entité \*Project *relative existe, elle doit être impérativement liée à la session utilisateur en cours.****&#x20;En cas d'erreur, une erreur 401 est renvoyée au client.*

Si l'appel réussi, le server renvoie `projectId` qui correspond à l'identifiant de l'entité *Project* résolue et vous reprendrez alors le parcours sur la dernière vue active du projet concerné.

## Identifiant du projet résolu

Une fois que le server a résolu l'entité *Project* lors du décrochage, l'identifiant relatif  `projectId` est renvoyé au client en réponse à l'appel `GET /session`

`projectId` sera alors renseigné lors de chaque appel graphQL du client au server dans les headers de la requête. Nom du header : `fasst-oav-project-id`

C'est grâce à cet header que le server résout lors des appels graphQL l'objet *process* contenu dans le *context graphQL* qui vous servira à récupérer `projectId` dans les resolvers et dans les composants de vos vues (se référer à [ce chapitre](https://doc.fasst.tech/oip-project-starter/process) pour plus de détails)

***Pour des raisons de sécurité, lors de chaque appel graphQL, le server vérifie que le projet identifié par le header&#x20;***`fasst-oav-project-id`***&#x20;fait bien partie de la liste des projets liés à la session utilisateur actuelle.***

# Reprise d'un projet existant

Si vous souhaitez reprendre le parcours d'un projet initié par une autre session utilisateur ou lors d'une session expirée, alors il vous faut re-générer un token auprès du service de sessions.

Vous devez vous assurer de renseigner dans le *body* de la requête (champ `metadata`), quelque chose qui fait référence au *context* client initial et qui vous aidera à identifier l'entité *Project* existante correspondante dans la callback d'initialisation du projet. Par exemple en renseignant l'`externalId` du projet concerné.

Une fois le token obtenu, vous pouvez décrocher sur l'OAV avec le token renseigné en paramètre dans l'URL.

Exemple : `http://localhost:8000/?token=my-generated-token`

Vous reprendrez alors le parcours sur la dernière vue active du projet concerné.

# Désactiver la vérification du token

***⚠️ La vérification du token de session ne doit jamais être désactivée en mode production ⚠️***

Lors de vos phases de développement en local, pour vous éviter à devoir générer des tokens auprès du service de sessions de manière redondante, vous pouvez désactiver la vérification du token lors du chargement de l'application web en passant à `true` la valeur de la variable d'env `SESSION_CHECKING_DISABLED`

Lorsque la vérification du token est désactivée, le server utilise le mock du *context* client (définit dans le fichier `server/mocks/context.mjs`) lors du décrochage. Par conséquent vous n'avez pas besoin de renseigner le paramètre `token` dans l'URL. Par ailleurs, si le paramètre `token` est présent dans l'URL, il sera ignoré.

Logique d'initialisation du projet lorsque la vérification du token est désactivée :

- si le paramètre `projectId` est trouvé dans l'URL, le server essaiera de récupérer le projet relatif :
  - si le projet est trouvé, il sera lié à la session utilisateur en cours s'il n'est pas encore lié à cette dernière et `projectId` est renvoyé au client
  - sinon une erreur 401 est renvoyée au client
- sinon, le server appelle la callback d'initialisation du projet en passant en paramètre le mock du *context&#x20;*&#x63;lient. Vous pouvez éditer le mock du *context* selon vos besoins, fichier `server/mocks/context.mjs`*.&#x20;*&#x55;ne fois l'entité *Project&#x20;*&#x72;ésolue par la callback d'initialisation du projet, elle sera liée à la session utilisateur en cours si elle n'est pas encore liée à cette dernière et `projectId` est renvoyé au client

# Authentification du client

Ce chapitre à pour but d'expliquer la logique d'authentifaction du client au server.

<font color="#ae2139">***L'endpoint*** `/graphql` ***du server est sécurisé par défaut. Le server vérifie le*** ***Bearer token*** ***définit dans les headers de chaque requête entrante.***</font>

<font color="#ae2139">***Dans ce chapitre, le terme*** ***« client »*** ***fait référence à l'application*** ***React*** ***de votre OAV.***</font>

<font color="#ae2139">***La logique d'authentification du client se fait en parallèle et de manière indépendante à la logique de session expliquée précédemment. Ce sont deux logiques distinctes, qui sécurisent votre OAV.***</font>

Les variables d'environnement relatives à l'authentification du client :

:::CodeblockTabs
Env

```none
API_USER_ID=fasst-oav-oip
API_KEY=00000000-0000-0000-0000-000000000000
API_KEYS=fasst-oav-oip:00000000-0000-0000-0000-000000000000
JWT_SECRET=33333333-3333-3333-3333333333
```
:::

Explications :

Lors du chargement de l'application *React* dans le navigateur web, le client échange les valeurs des variables d'env `API_USER_ID` et `API_KEY` contre des tokens via l'endpoint `/u/token` du server.

Le server vérifie les *credentials* du client reçus grâce à la variable d'env `API_KEYS` (dont sa valeur doit être une concaténation des valeurs de `API_USER_ID` et de `API_KEY`). Si les *credentials&#x20;*&#x73;ont valides alors le server génère et renvoie au client un *access token* et un *refresh token*. Ces tokens sont signés par le server en utilisant la valeur de la variable d'env `JWT_SECRET`

Lors de ses appels *graphQL*, le client utilisera alors l'*access token* reçu par le server en tant que *Bearer token&#x20;*&#x70;our s'authentifier auprès du server.

Dans le cas d'une erreur 401 retournée par le server lors d'un appel *graphQL*, le client essaie de rafraîchir l'*access token&#x20;*&#x76;ia l'endpoint `/u/token` du server en passant le *refresh token* gardé en mémoire et relance l'opération *graphQL* qui a échouée. Par défaut, l'expiration de l'*access token* est définie sur 24 heures.

# Garanties de sécurité

Résumé des garanties de sécurité en production :

- il n'est pas possible de décrocher sur l'OAV sans token de session
- si l'utilisateur souhaite reprendre un projet existant, il doit générer un token de session faisant référence au projet souhaité et re-décrocher sur l'OAV
- si l'utilisateur entre manuellement `projectId` dans l'URL, `projectId` doit faire référence à un projet précédamment initialisé lors de la même session utilisateur
- plusieurs projets peuvent être liés à une même session utilisateur
- un projet peut être lié à plusieurs sessions utilisateur
- l'application *React* (le client) s'authentifie auprès du server (OAuth 2.0)
- l'endpoint `/graphql` du server est protégé, le server vérifie :&#x20;
  - le *Bearer token* pour authentifier et autoriser le client
  - que le projet identifié par le header `fasst-oav-project-id` est bien lié à la session utilisateur

# Configurer les attributs du cookie de session

***La configuration des attributs du cookie de session est disponible à partir de la version 3.4.0 de la dépendance OIP Starter Utils.***

Le server utilise la dépendance npm [express-session](https://github.com/expressjs/session) pour la gestion du cookie de session.

La configuration par défaut du cookie est la suivante :

:::CodeblockTabs
COOKIE CFG

```javascript
{
  sameSite: 'lax',
  maxAge: process.env.SESSION_COOKIE_MAX_AGE,
  secure: true // en mode production
}
```
:::

Si vous souhaitez modifier la configuration par défaut, vous pouvez passer un objet `cookieOptions` en paramètre de la méthode `startServer` appelée par défaut dans le fichier `server/index.mjs`

Exemple :

:::CodeblockTabs
index.mjs

```javascript
import { start as startServer } from '@fasstech/oip-starter-utils/server';

const config = {
  // ...
  cookieOptions: {
    secure: process.env.NODE_ENV === 'production',
    httpOnly: process.env.NODE_ENV === 'production',
    sameSite: process.env.NODE_ENV === 'production' ? 'none' : false
  }
};

const { app } = await startServer(config);
```
:::

Points à savoir :

- l'option `secure` sera toujours activée en mode production pour des raisons de sécurité
- l'option `maxAge` sera toujours définie sur la valeur de la variable d'environnement `SESSION_COOKIE_MAX_AGE` si elle existe o&#x75;*&#x20;60 minutes* par défaut

Pour la liste complète et le détail des options de configuration acceptèes, veuillez vous référer à la documentation des options liées au *cookie* de la dépendance npm [express-session](https://github.com/expressjs/session)
