Pointage par reconnaissance faciale pour les organisations multi-sites

Les employés pointent leur entrée et leur sortie en regardant la caméra d'un téléphone connecté au Wi-Fi du site. Chaque site fait tourner un petit serveur relais qui continue de fonctionner quand le siège est injoignable, et un serveur principal central rassemble tout.

Les trois composants

Ordre de déploiement

1. Déployez le serveur principal, placez-le derrière HTTPS et connectez-vous à la console d'administration.
2. Ajoutez les départements et les utilisateurs (avec une photo chacun).
3. Pour chaque site, Relays → Add a relay sur le serveur principal, puis copiez son jeton.
4. Installez le relais sur un PC du site avec ce jeton.
5. Ouvrez le QR code du relais sur un téléphone et faites un pointage de test.

Prérequis en bref

Architecture de déploiement

Les téléphones ne parlent qu'au relais de leur site, sur le réseau local. Les relais parlent au serveur principal par Internet, via une seule API authentifiée. Le serveur principal n'appelle jamais un relais.

Schéma de déploiement

Trait bleu plein : le seul lien entre les sites et le siège. Pointillés : appels sortants vers des services que vous n'hébergez pas.

Qui tourne où

Déroulement d'un pointage

1. L'administrateur ajoute un utilisateur

   Sur le serveur principal : ID, nom complet, département et photo. Le serveur vérifie que la photo contient exactement un visage exploitable et la garde comme référence.

2. Les relais se synchronisent toutes les 30 s

   Chaque relais appelle GET /ping, /settings, /users et télécharge les photos nouvelles ou modifiées, puis calcule lui-même leurs données faciales.

3. Le téléphone prend la photo

   L'employé ouvre https://<ip-du-relais>:8443. Quand un visage est visible, la photo est envoyée à POST /api/identify. Le relais reconnaît la personne et renvoie son nom avec un jeton à usage unique valable 90 s pour ce téléphone.

4. Le téléphone confirme ENTRÉE ou SORTIE

   IN/OUT est proposé puis envoyé après 4 s, sauf si la personne choisit l'autre option. POST /api/checkins n'est accepté qu'avec le jeton ; la photo enregistrée est celle que le relais a reconnue.

5. Le relais enregistre et transmet

   Le pointage est horodaté avec l'heure Internet fiable, affiché OK/KO dans la fenêtre du relais, écrit dans SQLite et envoyé à POST /api/v1/checkins immédiatement, ou plus tard si le serveur principal est injoignable.

6. Le serveur principal vérifie

   Il recalcule OK/KO à partir du fuseau horaire et des paramètres du site et compare la photo de pointage à celle de l'utilisateur. Les non-correspondances, visages absents, rejeux et arrivées tardives sont signalés sur le tableau de bord.

Réseau et ports

Fonctionnement hors ligne

Le relais garde en cache les utilisateurs et les paramètres, décide OK/KO localement et met les pointages en file d'attente. La seule chose dont il ne peut pas se passer est l'heure fiable.

Modèle de confiance et de sécurité

• Authentification des relais. Chaque appel d'API porte un jeton bearer, provient d'une IP/CIDR autorisée, indique l'ID machine du relais dans X-Relay-Id et est signé avec la clé privée du relais (X-Relay-Time, X-Relay-Signature). Un jeton est lié au premier relais qui l'utilise : son ID machine et sa clé publique (X-Relay-Key) sont enregistrés à la première requête, et chaque requête et pointage suivants doivent être signés avec la clé privée correspondante. Un jeton volé ou un relais cloné sans cette clé est refusé.
• Heure. L'heure des pointages provient des en-têtes HTTPS Date, puis avance avec une horloge monotone : modifier l'heure ou le fuseau de Windows n'a aucun effet. Le fuseau du site est fixé dans relay.ini.
• Revérification côté serveur. Le serveur principal recalcule lui-même OK/KO, refuse les horodatages dans le futur et signale les pointages livrés plus de 10 minutes en retard alors que le relais était connecté.
• Secrets sur le relais. Le jeton est déplacé de relay.ini vers data/secrets.bin (Windows DPAPI pour le compte qui exécute le relais) et le dossier data/ est réservé à ce compte, à SYSTEM et aux Administrateurs.

Déployer le serveur principal

Le script d'installation crée un utilisateur système, un environnement Python, la base de données si vous le souhaitez, un service systemd et une tâche cron, et génère les secrets. C'est la méthode prise en charge pour déployer le serveur principal.

Avant de commencer

• Un serveur Linux avec systemd, des droits sudo et Python 3.10+. Le script installe python3-venv, PostgreSQL et cron avec apt, dnf ou yum s'ils manquent.
• Un nom DNS pour le serveur (par exemple intime.example.com) et un moyen d'obtenir un certificat TLS.
• La synchronisation de l'heure (NTP / systemd-timesyncd) activée. Les requêtes de relais dont l'heure signée s'écarte de plus de 5 minutes de l'horloge du serveur sont refusées avec clock_skew.

Installer avec le script

1. Lancer l'installateur

   Sur le serveur, avec un utilisateur disposant des droits sudo :

   $ curl -sSL https://raw.githubusercontent.com/dijey099/in-Time/refs/heads/master/main_server/install_main_server.sh \
     | sh

   Le script demande si vous avez déjà un serveur PostgreSQL. Répondez n pour qu'il installe PostgreSQL et crée le rôle et la base in-time (socket local, authentification peer, sans mot de passe). Sur une machine sans terminal, répondez à l'avance avec IN_TIME_POSTGRES=install ou IN_TIME_POSTGRES=existing.

2. Conserver le mot de passe administrateur

   Lors d'une première installation, le script affiche l'identifiant généré pour la console (utilisateur admin, mot de passe aléatoire). Il est aussi enregistré dans /var/lib/in-time/main-server/.env.

3. Modifier la configuration

   $ sudo nano /var/lib/in-time/main-server/.env

   Vérifiez au minimum DEPARTMENTS et DATABASE_URL (déjà renseignée si le script a créé la base). Derrière un proxy, renseignez aussi TRUSTED_PROXIES, CF_PROXY et SESSION_COOKIE_SECURE=true ; voir HTTPS et proxy inverse. Toutes les variables sont dans la référence de configuration.

4. Démarrer le service

   $ sudo systemctl start in-time-main
   $ sudo systemctl status in-time-main
   $ sudo journalctl -u in-time-main -f

   Le service est déjà activé au démarrage de la machine. Il écoute sur 127.0.0.1:8000. Au premier démarrage, il télécharge face-api.js et les modèles faciaux OpenCV.

Options de l'installateur

Ce que le script met en place

L'adresse d'écoute et le nombre de workers de gunicorn viennent de SERVER (par défaut 127.0.0.1:8000) et WORKERS (par défaut 2) dans .env.

Exemple d'installation sans interaction

# version figée, archive vérifiée, PostgreSQL installé localement, aucune question
$ curl -sSL https://raw.githubusercontent.com/dijey099/in-Time/refs/heads/master/main_server/install_main_server.sh \
  | IN_TIME_BRANCH=<tag de version> IN_TIME_SHA256=<sha256 de l'archive> \
    IN_TIME_POSTGRES=install sh

HTTPS et proxy inverse

Les relais doivent joindre le serveur principal en HTTPS, et l'option caméra de la page utilisateur ne fonctionne qu'en HTTPS. Placez nginx (ou Apache, Traefik, Cloudflare) devant gunicorn et indiquez à l'application derrière combien de proxys elle se trouve, pour que le contrôle d'IP des relais voie la vraie adresse publique.

# /etc/nginx/sites-available/in-time  (adaptez le nom et les chemins du certificat)
server {
    listen 443 ssl http2;
    server_name intime.example.com;

    ssl_certificate     /etc/letsencrypt/live/intime.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/intime.example.com/privkey.pem;

    client_max_body_size 32m;   # correspond à MAX_CONTENT_LENGTH de l'application (photos)

    location / {
        proxy_pass         http://127.0.0.1:8000;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_read_timeout 120s;
    }
}
server {
    listen 80;
    server_name intime.example.com;
    return 301 https://$host$request_uri;
}

Puis dans .env : TRUSTED_PROXIES=1 et SESSION_COOKIE_SECURE=true, et redémarrez le service. Avec Cloudflare, choisissez la ligne qui correspond à votre installation :

Les en-têtes transmis ne sont lus que depuis TRUSTED_PEERS (par défaut : cette machine). Si le proxy ou un tunnel cloudflared tourne sur une autre machine ou dans Docker, ajoutez son adresse. L'IP vue pour chaque relais apparaît sur la page Relays, sous Last seen.

Première configuration

1. Se connecter

   Ouvrez https://intime.example.com et connectez-vous en tant qu'admin avec le mot de passe du fichier .env. Le tableau de bord vous avertit tant que les modèles du contrôle facial sont en cours de téléchargement.

2. Vérifier les paramètres

   Définissez l'heure d'arrivée maximale et l'heure de départ minimale globales sur la page Settings. Chaque site peut les modifier.

3. Ajouter les utilisateurs

   Page Users : ID, nom complet, département et photo (envoi d'un fichier ou prise par la caméra). Le contrôle facial doit réussir pour que l'utilisateur puisse être reconnu.

4. Enregistrer un relais par site

   Relays → Add a relay : saisissez la ou les IP publiques depuis lesquelles le site se connecte (CIDR accepté ; * signifie toutes et ne sert qu'aux tests) et copiez le jeton. Il n'est affiché qu'une fois. Depuis le terminal :

   $ sudo -u in-time .venv/bin/flask --app main create-relay "SITE A" --ips 203.0.113.10

   Transmettez le jeton à la personne qui installe le relais sur ce site. Il est lié au premier serveur relais qui l'utilise.

Mise à jour

Relancez le script d'installation. Il arrête le service, remplace l'application et conserve .env, .venv, photos/, snapshots/, models/, app/static/vendor/ et cf_ips.txt, réinstalle les dépendances et redémarre le service s'il tournait. Comparez ensuite votre .env avec .env.example pour repérer les nouveaux paramètres.

Déployer un serveur relais

Un relais par site. C'est un exécutable unique accompagné d'un fichier relay.ini : double-cliquez dessus et la fenêtre du relais s'ouvre avec un QR code pour les téléphones.

Avant de commencer

• Un PC sur le site, sur le même réseau que les téléphones, avec une IP fixe ou une réservation DHCP. Le certificat du relais est régénéré quand son IP locale change, et les téléphones verraient alors un nouvel avertissement.
• Un accès Internet depuis ce PC : HTTPS vers le serveur principal, les sources d'heure et, au premier démarrage, le registre npm et le dépôt de modèles OpenCV.
• Fourni par l'administrateur du serveur principal : le jeton du relais de ce site (Relays → Add a relay), avec l'IP publique du site dans Allowed IPs.
• Le fuseau horaire IANA du site, par exemple Indian/Antananarivo ou Europe/Paris.
• L'exécutable du relais pour le système cible : start_relay.exe (Windows) ou start_relay (Linux), téléchargé depuis les versions GitHub du projet ou compilé depuis les sources avec build.bat / build.sh. Vous pouvez aussi le lancer depuis les sources avec Python 3.10+.

Installer sur un site

1. Choisir le compte et le dossier

   Choisissez le compte Windows qui exécutera toujours le relais et créez-lui un dossier, par exemple C:\in-Time\relay. Copiez-y start_relay.exe.

   Gardez le même compteLe jeton et les clés du relais sont chiffrés avec Windows DPAPI pour le compte qui exécute le relais, et le cache chiffré en dépend. Lancer le relais sous un autre compte oblige à ressaisir les secrets et fait perdre les pointages pas encore envoyés.

2. Écrire relay.ini

   Créez relay.ini dans le même dossier (à partir du relay.ini.example livré avec l'exécutable) et renseignez au moins ces valeurs :

   relay.ini

   [main_server]
   url = https://intime.example.com
   token = <jeton de Relays → Add a relay>
   verify_ssl = true
   sync_interval = 30
   
   
   [relay]
   host = 0.0.0.0
   port = 8443
   duplicate_window = 60
   allow_public_clients = false
   data_dir = data
   
   [face]
   min_similarity = 0.363
   
   [time]
   timezone = Indian/Antananarivo
   check_interval = 60

   Chaque clé est décrite dans la référence de configuration. Utilisez verify_ssl = <chemin vers .pem> si le serveur principal utilise une autorité de certification privée.

3. Ouvrir le pare-feu une fois

   WINDOWS · ADMIN

   netsh advfirewall firewall add rule name="in-Time relay" dir=in action=allow protocol=TCP localport=8443

   LINUX · UFW

   $ sudo ufw allow 8443/tcp

4. Démarrer le relais

   Double-cliquez sur start_relay.exe. La console se masque et seule la fenêtre du relais s'affiche. Au démarrage, le relais :

   • déplace le jeton de relay.ini vers data\secrets.bin et réserve data\ au compte, à SYSTEM et aux Administrateurs ;
   • vérifie l'heure fiable et crée sa clé de signature (premier démarrage), dont le serveur principal enregistre la clé publique à sa première requête ;
   • crée son ID stable dans data\server.id et un certificat auto-signé dans data\certs\ ;
   • télécharge face-api.js dans data\vendor\ et les modèles faciaux dans data\models\ (premier démarrage uniquement).

   Les erreurs de démarrage (relay.ini absent, port déjà utilisé) s'affichent dans une boîte de dialogue et dans data\relay.log. Lancez start_relay.exe --no-gui depuis un terminal pour suivre le journal en direct.

5. Vérifier les lignes d'état

   Dans la fenêtre du relais, Internet doit indiquer OK avec le fuseau du site et Main server Reachable. Sur le serveur principal, la page Relays montre le relais en ligne avec son IP publique sous Last seen. La première synchronisation récupère utilisateurs et photos en moins de 30 secondes.

Connecter les téléphones

1. Connectez le téléphone au Wi-Fi du site.
2. Scannez le QR code affiché dans la fenêtre du relais, ou ouvrez https://<ip-du-relais>:8443.
3. Acceptez une fois l'avertissement de certificat. Les navigateurs n'autorisent la caméra qu'en HTTPS, c'est pourquoi le relais utilise un certificat auto-signé.
4. Regardez la caméra : le nom s'affiche, IN/OUT est proposé et envoyé après 4 secondes.

L'identification est limitée à 15 requêtes par 10 secondes et par téléphone. Les téléphones sur des adresses publiques sont refusés sauf si allow_public_clients = true.

Démarrage automatique

in-Time ne fournit pas de configuration de démarrage automatique. Voici des façons suggérées de relancer le relais après un redémarrage.

# /etc/systemd/system/in-time-relay.service
[Unit]
Description=in-Time relay
After=network-online.target
Wants=network-online.target

[Service]
User=intime-relay
WorkingDirectory=/opt/in-time-relay
ExecStart=/opt/in-time-relay/start_relay --no-gui
Restart=on-failure

[Install]
WantedBy=multi-user.target

Site sans Internet pendant l'installation

Au premier démarrage, le relais télécharge face-api.js et les modèles faciaux (environ 39 Mo). Si le PC ne peut pas joindre le registre npm ou le dépôt de modèles OpenCV, copiez data/vendor/ et data/models/ d'un autre relais dans son dossier data/ avant de le démarrer. Les pointages, eux, nécessitent toujours Internet pour l'heure fiable.

Déplacer ou remplacer un relais

Référence de configuration

Le serveur principal lit /var/lib/in-time/main-server/.env ; chaque relais lit le relay.ini placé à côté de son exécutable.

Serveur principal · .env

Relais locaux

Un relais situé sur le même réseau que le serveur principal peut être marqué Local relay sur la page Relays. Son IP est alors l'adresse qui a ouvert la connexion ; TRUSTED_PROXIES et CF_PROXY sont ignorés pour lui. Il doit se connecter directement à gunicorn (par exemple SERVER=<IP du LAN>:8000) avec cette IP dans Allowed IPs. N'utilisez jamais 0.0.0.0 sur un serveur joignable depuis Internet.

Plages Cloudflare

cf_ips.txt est mis à jour par update_cf_ips.py, qui ne le réécrit que si la liste de Cloudflare a changé (--check se contente de signaler). Le script d'installation le planifie toutes les 2 heures dans /etc/cron.d/in-time-cf-ips. Pour le mettre à jour à la main :

$ cd /var/lib/in-time/main-server
$ sudo -u in-time .venv/bin/python update_cf_ips.py

Relais · relay.ini

Exploitation et dépannage

Où trouver les journaux, les commandes du serveur principal et la signification des codes d'erreur courants.

Journaux et fichiers

Commandes du serveur principal

Exécutez-les depuis /var/lib/in-time/main-server avec l'utilisateur du service : sudo -u in-time .venv/bin/flask --app main <commande>.

Verrouillage de la connexion admin

Après LOGIN_MAX_FAILURES échecs de connexion consécutifs (depuis n'importe quelle adresse), la console est verrouillée et admin_login.lock est écrit à côté de .env, avec la liste des tentatives. Il n'est jamais supprimé automatiquement : supprimez le fichier ou lancez unlock-admin. Une connexion réussie remet le compteur à zéro.

Erreurs de relais vues par le serveur principal

Symptômes courants

Indicateurs du contrôle facial

Les pointages signalés sont tout de même enregistrés. Examinez la photo et décidez.