Auth et logique de session

16 min

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.

Session utilisateur

À 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 (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 :

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 client 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 :

{ "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 initProjectFromContext est passée en paramètre à la méthode startServer importée depuis la dépendance @fasstech/oip-starter-utils. La méthode startServer est appelée dans le fichier server/index.mjs de votre OAV et initialise le server.

La callback initProjectFromContext reçoit en paramètre l'objet context qui 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 sessionId qui correspond à l'identifiant de la session utilisateur actuelle.

Exemple :

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

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 :

GET /session?token=my-generated-token

Le server essaie alors de récupérer le context client lié au token par un appel HTTP au service de sessions (le même service qui a généré le token) :

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

Si l'appel réussi un objet qui représente le context client du projet est reçu en réponse :

{ "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

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 :

GET /session?projectId=xxxxx

*Si l'entité *Project relative existe, elle doit être impérativement liée à la session utilisateur en cours. 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 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 fasst-oav-project-id 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 client. Vous pouvez éditer le mock du context selon vos besoins, fichier server/mocks/context.mjs. Une fois l'entité Project ré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.

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.

Dans ce chapitre, le terme « client » fait référence à l'application React de votre OAV.

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.

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

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 sont 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 pour 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 via 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 :

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

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 pour la gestion du cookie de session.

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

{
  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