Aidants Connect

Aidants Connect est une application web qui propose à des aidants les fonctionnalités suivantes :

• créer un mandat de connexion via FranceConnect avec un ou plusieurs usagers sur un périmètre et une durée définis ;
• connecter via FranceConnect un usager dans les conditions des mandats créés ;
• accéder à des ressources sur l'accompagnement des usagers ;
• accéder à un suivi de ses mandats.

Aidants Connect est construit sur les éléments suivants :

• Python 3.11
• Django 4.2
• PostgreSQL

Installer et lancer l'application

Lancement rapide si vous avez déjà installé la base de données et les dépendances de test :

git clone git@github.com:betagouv/Aidants_Connect.git
cd Aidants_Connect
cp .env.example .env
virtualenv venv
source venv/bin/activate
pip install --user pipenv
pipenv install --dev
python manage.py collectstatic
pre-commit install

Ensuite, vous devriez pouvoir faire tourner les tests :

python manage.py test

Et lancer le serveur :

python manage.py runserver 3000

Installer la base de données

Utilisez votre gestionnaire de paquets préféré pour installer la base. L'exemple qui suit emploie le gestionnaire Homebrew via la commande brew.

Dans un terminal, installez PostgreSQL :

brew install postgresql

Démarrez le service postgresql :

brew services start postgresql

Ceci démarre le serveur de la base de données et active sa réexécution au login.

Dans le cas où ce serait votre première utilisation de PostgreSQL, créez une base d'essai à votre nom :

createdb `whoami`

Puis, démarrez l'invite de commande PostgreSQL :

psql

Vous pouvez dès à présent visualiser :

• la liste des bases de données existantes avec cette commande PostgreSQL \list
• la liste des rôles existants avec \du

Ajoutez une base aidants_connect appartenant au nouvel utilisateur aidants_connect_team en poursuivant dans l'invite de commmande PostgreSQL :

CREATE USER aidants_connect_team;
CREATE DATABASE aidants_connect OWNER aidants_connect_team;
ALTER USER aidants_connect_team CREATEDB;

🎉 La base de donnée aidants_connect est installée. Vous pouvez la voir et quitter l'invite de commande avec :

\list
\q

Installer l'application

Dans votre répertoire de travail, créez et activez un environnement virtuel :

virtualenv venv
source venv/bin/activate

Installez pipenv :

brew install pipenv  # Sur Mac
# Ou
pip install pipenv

Installez les dépendances :

pipenv install --dev

Si vous avez un Mac M1, ou si la commande précédente déclenche le message d'erreur ld: library not found for -lssl, référez-vous à la section Troubleshooting.

Configurer les variables d'environnement

Dupliquez le fichier .env.example à la racine du projet en tant que .env :

cp .env.example .env

En test en local, vous ne devriez pas avoir à modifier ce .env.

Créez un répertoire staticfiles à la racine du projet :

mkdir staticfiles

Appliquez les migrations de la base de données :

python manage.py migrate

Peupler la base de données

Il existe plusieurs moyens de peupler la base de données.

Utiliser les fixtures

Des données de test qui créent un environnement complet :

  python manage.py loaddata admin.json
  python manage.py loaddata usager_autorisation.json
  python manage.py loaddata faq.json

Ce process crée automatiquement un superuser admin@email.com. Plus d'information sur comment se connecter avec ce compte sont disponible dans la section Se connecter à l'application

Créer manuellement un superuser

Créez un profil administrateur avec une organisation par défaut :

python manage.py createsuperuser --username <insert_admin_email> --organisation-name <insert_organisation_name>

Une organisation avec l'email que vous avez spécifié sera automatiquement créée pour ce profil. Si vous avez déjà créé une organisation vous pouvez passer son numéro dans la base de donnée à la création du profil admin :

python manage.py createsuperuser --username <insert_admin_email> --organisation <insert_organisation_pk>

Pour pouvoir vous connecter à votre instance locale, il faut apparier à votre superuser un dispositif TOTP (TOTP device).

Pour cela, commencez par lui adjoindre un jeton OTP statique :

python manage.py addstatictoken <insert_admin_email> -t <insert_6_numbers>

Notez ce code, il vous permettra de vous connecter la première fois à l'interface d'administration.

Lancer les tests

Si vous ne les avez pas, installez les éléments suivants :

• Navigateur Firefox en téléchargement
• Gecko driver

Installation de Gecko Driver :

• Mac OS : brew install geckodriver
• Linux : vous pouvez télécharger ici la dernière version du driver et déposer le fichier geckodriver dans VOTRE_VENV/bin (ou dans /usr/local/bin si vous voulez donner un accès global au driver).

Puis lancez les commandes suivantes pour vérifier le style du code source et exécuter les tests de l'application :

flake8
black --check .
python manage.py test

Les tests fonctionnels (Selenium) sont lancés sur http://localhost:3000. Il faut s'assurer que rien d'autre n'occupe ce port pendant leur exécution.

Par défaut, les tests Selenium sont lancés en mode headless, c'est-à-dire sans ouverture de fenêtre de navigateur. Pour modifier ce comportement, inversez la valeur de la variable d'environnement HEADLESS_FUNCTIONAL_TESTS dans votre fichier .env.

Astuce : la plupart des cas de tests portent une directive @tag pour leur associer des tags décrivant des fonctionnalités ou des caractéristiques des tests. Par exemple, functional pour les tests fonctionnels, create_mandat pour ce qui implique une création de mandat, etc. Cela vous permet de lancer seulement certains tests, grâce à l'option --tag. Par exemple, pour lancer les tests portant le tag parrot :

python manage.py test --tag parrot

Lancer l'application

Pour lancer l'application sur le port 3000 :

python manage.py runserver 3000

L'application sera disponible à l'URL http://localhost:3000/.

Se connecter à l'application

Votre superuser est créé et a un login, un mot de passe et un static token c'est-à-dire un code à 6 chiffres utilisable une seule fois. Il faut maintenant obtenir le QR code qui vous permettra de vous connecter de manière pérenne.

Trouver la page d'admin

La page d'admin se trouve sur /[Variable d'environnement ADMIN_URL]. En local, /adm.

Attention, /admin n'est pas un vrai site d'admin… c'est un pot de miel.

Se connecter à l'admin

• ⏩ Si vous avez utilisé les fixtures pour peupler votre base de données,
  • identifiant : admin@email.com;
  • mot de passe : admin;
  • Static OTP : 111111
• Sinon, utilisez le login, mot de passe et static token créés dans la section Installation sur un serveur : Créer un superuser

Pérenniser son authentification à double facteur (2FA)

Une fois connecté à l'admin, cliquez sur TOTP devices

• ⏩ Si vous avez utilisé les fixtures :
  • Cliquez sur le lien qr code à droite de l'entrée pour Admin
  • Scannez le QRcode dans une application TOTP telle que Authy ou Google Authenticator

Si vous avez créé votre propre superuser :

1. Cliquez sur le bouton Ajouter TOTP device +
2. Choisissez votre superuser grâce à l'icône "loupe" située à côté du champ User
3. Saisissez un nom pour votre dispositif TOTP (par exemple : Mon téléphone) dans le champ Name
4. Cliquez ensuite sur Enregistrer et continuer les modifications tout en bas du formulaire
5. Une fois l'enregistrement effectué, l'écran devrait se rafraîchir et vous proposer un lien vers un QR Code
6. Vous pouvez à présent scanner celui-ci dans une application TOTP telle que Authy ou Google Authenticator pour utiliser l'authentification à double facteur dans votre environnement local.

Contribuer à l'application

Il faut d'abord avoir correctement installé l'application.

Installez les git hooks :

pre-commit install

Travailler sur le côté client (CSS et JavaScript)

CSP et JavaScript inline

La CSP (content security policy) de Aidants Connect fonctionne en liste blanche : elle nécessite de lister tous les scripts inline (dans des balises <script>).

Si vous devez modifier ou ajouter un bout de JavaScript inline, vous pouvez utiliser la propriété csp_nonce de l'objet HttpRequest générée par django-csp :

<script nonce="{{request.csp_nonce}}">
    var hello="world";
</script>

CSS et SCSS

Pour compiler les fichiers SCSS en CSS, vous devez avoir installé sass sur votre poste, la commande sass doit être disponible dans votre $PATH.

Ensuite, utilisez une des deux commandes suivantes :

python manage.py scss # compilation one-shot
# ou bien :
python manage.py scss --watch # compilation automatique à chaque modification de SCSS

Installation sur un serveur

Variables d'environnement

Sur un serveur, vous voudrez ajouter vos informations dans le fichier .env ou dans les variables d'environnement de votre hébergeur :

• Les champs obligatoires sont indiqués par le préfixe <insert_.
• Les informations de production FC_AS_FS et FC_AS_FI sont à récupérer via des habilitations FranceConnect.
• Vous allez devoir calculer la valeur HASH_FC_AS_FI_SECRET à partir de la valeur de FC_AS_FI_SECRET : pour cela voir dans les annexes la procédure.
• Les valeurs de sécurité sont issues de la section "sécurité" de la documentation Django et de la conférence Django and Web Security Headers.

Création d'un superuser sans accès à la console Django

Il existe deux solutions.

Solution avant installation du code

• déployer la branche de la PR 473 avant de déployer main (utilisé pour notre environnement sandbox).
  • avant de déployer le code, insérer les variables d'environnement INIT_* mentionnées dans la PR ;
  • installer l'application à partir de la branche de la PR 473 ;
  • déployer ensuite l'application à partir de la branche main.

Solution après installation du code

• insérer directement les données dans la base de données après l'installation de l'application.

Annexes

Documentation de FranceConnect

• Fournisseur d'Identité (FI): ici
• Fournisseur de Service (FS): ici

Ré-initialiser la base de données

Avec les données de test (fixtures) : Utiliser le Makefile

Pour simplifier le lancement de certaines commandes, un Makefile est disponible. Exemples de commandes :

make destroy-rebuild-dev-db

Sur Windows, la commande make n'est pas disponible ; Il faut passer chaque commande du Makefile (fichier présent à la racine du projet) les unes après les autres.

Avec des données existantes

Si vous avez des données existantes, vous pouvez d'abord les sauvegarder :

python manage.py dumpdata --exclude auth.permission --exclude contenttypes > db.json

Puis il vous faudra recréer la base de donnée PostgreSQL :

• Dans le shell :

  psql

• Puis, dans l'invite de commande psql :

  DROP DATABASE aidants_connect;
  CREATE DATABASE aidants_connect OWNER aidants_connect_team;
  ALTER USER aidants_connect_team CREATEDB;
  \q

Ensuite, de retour dans le shell, pour lancer les migrations :

python manage.py migrate

Enfin, chargez les données :

• Soit des données sauvegardées précédement :

  python manage.py loaddata db.json

• Soit repartir de zéro en recréant un superuser (plus de détails dans la section Installer l'application) :

  python manage.py createsuperuser

Purger les connexions expirées

Les objets Django de type Connection repésentent une forme de cache pendant l'établissement de la connexion FranceConnect. À ce titre, ils contiennent des données personnelles et doivent donc être purgés régulièrement pour respecter nos engagements en la matière. Pour ce faire, il suffit d'exécuter ou de planifier la commande suivante :

python manage.py delete_expired_connections

Calcul de HASH_FC_AS_FI_SECRET à partir de la valeur de FC_AS_FI_SECRET

Il faut utiliser generate_sha256_hash.

from aidants_connect_web.utilities import generate_sha256_hash
generate_sha256_hash("VALUE_FC_AS_FI_SECRET".encode("utf-8"))

Troubleshooting

Erreur ld: library not found for -lssl

Si la commande précédente déclenche le message d'erreur suivant ld: library not found for -lssl, essayez :

export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/opt/openssl/lib/

Si vous avez un Mac M1

• Si, lors de l'installation de psycopg2-binary, vous avez le message d'erreur suivant :

 ld: warning: directory not found for option '-L/usr/bin/openssl/lib/'
    ld: library not found for -lssl
    clang: error: linker command failed with exit code 1 (use -v to see invocation)
    error: command 'clang' failed with exit status 1

• Si vous avez installé openssl via brew, vous pouvez essayer la commande suivante :

env LDFLAGS='-L/opt/homebrew/opt/openssl@1.1/lib -L/opt/homebrew/opt/readline/lib' pip install -r requirements.txt

https://stackoverflow.com/a/42264168

• Si, lors de l'installation de pillow vous avez le message d'erreur suivant :

The headers or library files could not be found for zlib,
    a required dependency when compiling Pillow from source.

Vous pouvez essayer :

brew install libjpeg

python-pillow/Pillow#5042 (comment)

Les tests fonctionnels échouent de manière inexpliquée

Dans de rares cas (comportement observé à ce jour sur une seule machine de dev), les tests d'intégration échouent car la première connexion à une URL via l'API Selenium plante de manière inexpliquée.

Un contournement empirique a été mis en place ; si vous rencontrez ce problème vous pouvez l'activer en passant à True la variable d'environnement BYPASS_FIRST_LIVESERVER_CONNECTION dans votre fichier .env.