Connexion et espaces de travail

Connexion intégrée

Campbooks assure lui-même la connexion et l'émission des jetons. Il n'y a aucun service d'identité distinct à exécuter. Les gens se connectent avec Google, Microsoft, Zoho ou une clé d'accès (passkey), et le serveur émet tous les jetons.

Aucune configuration n'est nécessaire. Laissez CAMPBOOKS_AUTH__ISSUER non défini, comme le fait le compose.yaml fourni. L'émetteur est CAMPBOOKS_PUBLIC_URL, donc donnez-lui l'adresse que les gens utilisent.

• CAMPBOOKS_PUBLIC_URL doit être en https://. Le http:// simple ne fonctionne qu'avec CAMPBOOKS_ENV=development, pour un essai sur votre machine.
• Le serveur signe les jetons avec des clés qu'il génère au premier démarrage et renouvelle tous les 30 jours. Elles sont stockées dans Postgres, chiffrées avec la clé secrète de l'instance.
• Les clés d'accès ne demandent aucune configuration. Les navigateurs les proposent en https://, ou sur http://localhost en développement.

La clé secrète de l'instance

Au premier démarrage, le service ponctuel server-init génère la clé secrète de l'instance dans le volume server-secrets. Le serveur la lit comme un fichier, jamais depuis .env.

La clé protège ce que Campbooks conserve pour vous : les clés de signature de la connexion, les jetons des sessions web et les identifiants des comptes connectés. Si vous la perdez, elle est irrécupérable, et ce qu'elle protège aussi. Le serveur refuse de démarrer quand la clé n'ouvre pas les clés de signature stockées.

Gardez-en une copie en lieu sûr, à part de vos sauvegardes. Une sauvegarde qui contient la base de données et la clé donne tout le contenu de la base à qui la trouve. Voir Mises à jour et sauvegardes.

Comment l'application web vous connecte

Le serveur connecte lui-même les navigateurs. Ouvrez l'application, et si vous n'êtes pas connecté il vous envoie vers l'écran de connexion, puis vous ramène. Le navigateur ne reçoit qu'un cookie de session HttpOnly, SameSite=Strict. Les jetons restent sur le serveur, chiffrés, dans Postgres.

• Les sessions se terminent après 48 heures d'inactivité, ou 30 jours au plus, ou à la déconnexion.
• En https://, le cookie est Secure et préfixé __Host-. En http:// simple, il ne l'est pas, et le serveur écrit un avertissement dans les journaux. Le http simple convient uniquement sur localhost.

Les réglages de session forment le bloc CAMPBOOKS_BFF__*, listé dans Configuration.

Se connecter avec Google, Microsoft ou Zoho

Chaque fournisseur est facultatif. Il apparaît sur l'écran de connexion dès que vous lui donnez un identifiant client et un secret client. Sans aucun, les gens peuvent utiliser une clé d'accès.

Pour chaque fournisseur voulu :

1. Enregistrez une application OAuth dans la console du fournisseur, avec cet URI de redirection (<provider> vaut google, microsoft ou zoho) :

   ${CAMPBOOKS_PUBLIC_URL}/auth/callback/<provider>

2. Mettez l'identifiant client dans .env sous la forme CAMPBOOKS_GOOGLE__CLIENT_ID, CAMPBOOKS_MICROSOFT__CLIENT_ID ou CAMPBOOKS_ZOHO__CLIENT_ID.

3. Mettez le secret client dans un fichier de deploy/secrets/ : google-client-secret, microsoft-client-secret ou zoho-client-secret. Ne mettez jamais de secrets dans .env. Compose monte le dossier en lecture seule dans le serveur, à /run/secrets/campbooks, et le serveur s'exécute avec l'uid 10001 :

   sudo chown 10001:10001 secrets/google-client-secret
   sudo chmod 0400 secrets/google-client-secret

   Docker Desktop sur macOS ou Windows n'a pas besoin du chown.

4. Indiquez le fichier au serveur dans .env, par exemple :

   CAMPBOOKS_GOOGLE__CLIENT_ID=your-client-id
   CAMPBOOKS_GOOGLE__CLIENT_SECRET_FILE=/run/secrets/campbooks/google-client-secret

5. Appliquez :

   docker compose up -d

Notes par fournisseur :

• Google : type d'application Application Web. C'est le même client OAuth que celui qui connecte Gmail, donc ajoutez le scope profile à son écran de consentement. Publiez l'application, car une application en Testing émet des refresh tokens qui expirent au bout de 7 jours. Tant que Google n'a pas validé l'application, les gens voient l'écran « application non validée » à l'inscription.
• Microsoft : comptes personnels, professionnels et scolaires. Dans le centre d'administration Microsoft Entra, enregistrez une application et ajoutez un URI de redirection Web. CAMPBOOKS_MICROSOFT__TENANT (par défaut common) limite qui peut se connecter : organizations, consumers ou l'identifiant d'un tenant. Microsoft ne vérifie pas l'e-mail qu'il indique, donc sur une instance invite_only il ne compte comme vérifié que si vous ajoutez la revendication facultative xms_edov au jeton d'identité.
• Zoho : dans la console API de Zoho, ajoutez une Server-based application et activez Multi-DC, pour qu'un seul client serve tous les centres de données. Sans Multi-DC, définissez CAMPBOOKS_ZOHO__ACCOUNTS_SERVER sur le centre de données de votre application, par exemple https://accounts.zoho.eu.

Les mêmes clients Google et Zoho relient aussi des boîtes mail. Voir Relier des boîtes mail.

Pour renouveler un secret, remplacez le fichier et lancez docker compose up -d.

Si votre application OAuth a déjà enregistré un autre chemin de retour, définissez CAMPBOOKS_<PROVIDER>__REDIRECT_PATH et faites réécrire ce chemin vers /auth/callback/<provider> par votre reverse proxy. Laissez-le non défini pour une nouvelle application.

Comptes et liaison

• Un compte est lié au compte du fournisseur par son identifiant, jamais par l'adresse e-mail. Se connecter avec un compte de fournisseur que Campbooks ne connaît pas propose de créer un nouveau compte.
• Une fois connectée, chaque personne peut ajouter d'autres façons d'entrer sous Réglages, puis Façons de se connecter. La dernière façon d'entrer ne peut pas être retirée.

Derrière un reverse proxy

La connexion est limitée en débit par adresse client. Derrière un proxy, toutes les requêtes semblent venir du proxy, et tous les clients partagent la même limite. Définissez CAMPBOOKS_TRUSTED_PROXIES dans .env avec l'adresse ou le réseau du proxy, sous forme d'adresses ou de blocs CIDR séparés par des virgules :

CAMPBOOKS_TRUSTED_PROXIES=172.18.0.0/16

Espaces de travail et politique d'inscription

La première personne qui se connecte crée le premier espace de travail et invite les autres depuis Réglages, puis Membres. Qui d'autre peut créer un espace de travail dépend de CAMPBOOKS_SIGNUP__POLICY :

Valeur	Ce qui se passe
open (par défaut)	Toute personne ayant un compte peut créer un espace de travail.
invite_only	Pas d'inscription publique. Seules les personnes invitées obtiennent un compte.
approval	Demander un espace de travail enregistre une demande. Personne n'entre tant qu'elle n'est pas approuvée.
code	Créer un espace de travail exige un code d'inscription de CAMPBOOKS_SIGNUP__CODES.

La même politique décide si Google, Microsoft et Zoho créent des comptes pour de nouvelles personnes. Le premier utilisateur de l'instance peut toujours créer un espace de travail : sur une instance neuve, connectez-vous vous-même avant de partager l'adresse.

Les invitations ne sont pas encore envoyées par e-mail. La personne qui invite reçoit le lien une seule fois, juste après l'invitation, et le transmet. Le lien est construit à partir de CAMPBOOKS_PUBLIC_URL, donc donnez-lui l'adresse que les gens utilisent.

Utiliser un fournisseur d'identité externe

C'est une option avancée, et rien n'est provisionné pour elle. Définir CAMPBOOKS_AUTH__ISSUER sur un émetteur OpenID Connect externe fait que l'API fait confiance aux jetons de cet émetteur. Définissez aussi CAMPBOOKS_AUTH__JWKS_URL et CAMPBOOKS_AUTH__AUDIENCE. L'application web se connecte alors par lui avec CAMPBOOKS_BFF__CLIENT_SECRET (ou CAMPBOOKS_BFF__CLIENT_SECRET_FILE).

Tant que vous le faites, la connexion propre à Campbooks, les façons de se connecter, les applications et la connexion de boîtes mail sont désactivées. Vérifiez ces réglages dans la documentation de votre fournisseur.