Guide
Guide
Keycloak, LemonLDAP::NG, Authentik, Okta, Google… : vos utilisateurs entrent dans SpotBooker avec les identifiants de leur établissement.
Votre établissement a un fournisseur d'identité qui parle OpenID Connect (OIDC) ? C'est le cas de Keycloak, LemonLDAP::NG, Authentik, Okta ou Google Workspace. Une fois relié à SpotBooker, chacun se connecte avec ses identifiants habituels, sans mot de passe de plus. La connexion OpenID Connect est incluse dans l'abonnement ; comme la connexion SAML, elle demande un accès complet (abonnement ou essai en cours). Seuls les administrateurs de votre espace la configurent, le plus souvent avec le service informatique.
Son adresse (l'émetteur) doit être en HTTPS et joignable depuis Internet : SpotBooker refuse les adresses de réseau privé et celles qui contiennent un ? ou un #.
Il faut pouvoir y déclarer une application : un client confidentiel (avec un secret), en flux « code d'autorisation ». SpotBooker envoie toujours PKCE (S256) en plus.
Par exemple institut.fr. À la différence de SAML, la connexion OpenID Connect ne s'active pas sans domaine : un même fournisseur (Google, Okta…) peut servir de nombreux établissements, et sans domaine tous ses comptes pourraient entrer.
Il permet de prouver que le domaine vous appartient (voir « Prouver vos domaines » plus bas). Cette preuve est indispensable pour que vos utilisateurs atteignent la connexion depuis la page de connexion : sans elle, l'adresse saisie ne retrouve pas votre établissement, l'admission automatique n'agit pas et un compte déjà existant ne peut pas être relié par son adresse.
Votre fournisseur ne connecte qu'une application qu'il connaît. L'encart « À déclarer dans votre fournisseur » affiche deux adresses, chacune avec un bouton Copier : l'URL de redirection, de la forme https://<votre-espace>/oidc/<clé>/callback, et l'URL de redirection après déconnexion, https://<votre-espace>/oidc/<clé>/logged-out. La clé est stable : ces adresses ne changent pas, même si vous modifiez l'adresse publique de votre espace.
Créez une application de type client confidentiel, en flux « code d'autorisation » (authorization code). Déclarez l'URL de redirection de l'étape 1 ; déclarez l'URL après déconnexion seulement si votre fournisseur propose une déconnexion centralisée. Notez l'identifiant du client et son secret. Les recettes Keycloak et LemonLDAP::NG sont plus bas.
Dans SpotBooker, choisissez le type de fournisseur (il ne fait que pré-remplir l'aide), saisissez l'émetteur tel que le fournisseur le publie, puis cliquez sur « Tester le fournisseur ». Le test lit /.well-known/openid-configuration et les clés de signature, sans rien enregistrer. Le secret, lui, n'est vérifié qu'à la première vraie connexion.
Recopiez l'identifiant du client et son secret (chiffré à l'enregistrement, il n'est plus jamais affiché). L'authentification au point de jeton est client_secret_basic par défaut ; choisissez client_secret_post seulement si votre fournisseur l'exige. Les scopes par défaut sont openid email profile ; openid est toujours ajouté.
Les claims sont les informations que le fournisseur place dans le jeton de la personne. Par défaut : sub (identifiant unique), email, given_name (prénom), family_name (nom) et groups. Une claim peut être un chemin imbriqué, par exemple realm_access.roles. Si l'adresse ou les noms manquent dans le jeton, SpotBooker lit le point userinfo du fournisseur, après avoir vérifié qu'il s'agit bien du même sub.
L'activation exige : une découverte réussie du fournisseur, l'identifiant du client, le secret, et au moins un domaine accepté. Il manque l'un d'eux : SpotBooker le dit et n'active rien. Chaque modification de la connexion est inscrite au journal d'activité.
Dans votre realm, ouvrez Clients puis Create client. Type de client : OpenID Connect. À l'étape suivante, activez Client authentication (accès confidentiel) et gardez Standard flow (code d'autorisation) coché. Le secret se trouve ensuite dans l'onglet Credentials.
Dans « Valid redirect URIs », collez l'URL de redirection copiée à l'étape 1. Si vous voulez la déconnexion centralisée, collez l'URL après déconnexion dans « Valid post logout redirect URIs ». L'émetteur est de la forme https://serveur/realms/nom, sans / final.
Pour recevoir les groupes, ouvrez le client, onglet Client scopes, puis le scope dédié du client (…-dedicated) et Add mapper > By configuration > Group Membership. Nommez-le groups, mettez groups dans « Token Claim Name », et désactivez « Full group path » si vous voulez des noms simples (labo et non /labo). Pour les rôles du realm, utilisez plutôt la claim realm_access.roles.
Une adresse envoyée avec email_verified: false n'est pas crue pour relier un compte SpotBooker déjà existant. Dans Keycloak, marquez les adresses comme vérifiées (utilisateur : « Email verified »), sinon les personnes qui ont déjà un compte devront se connecter par leur mot de passe.
Dans le Manager, ajoutez un « OpenID Connect Relying Party » (RP) pour SpotBooker, avec un identifiant de client et un secret. L'émetteur à saisir dans SpotBooker est l'adresse du portail LemonLDAP::NG, par exemple https://auth.example.fr. Pour cette relation, l'identifiant et le secret se trouvent dans Options → Basic (Client ID, Client secret).
Ajoutez l'URL de redirection de l'étape 1 aux adresses de redirection autorisées de la relation (et l'URL après déconnexion pour la déconnexion centralisée). Pour l'authentification au point de jeton, gardez client_secret_basic, qui est aussi la valeur par défaut de SpotBooker.
Dans les attributs exportés de la relation, associez les claims email, given_name et family_name à vos attributs d'annuaire (par exemple mail, givenName, sn), et groups si vous voulez piloter les groupes. Ajoutez le scope correspondant dans SpotBooker si LemonLDAP::NG l'exige.
Saisissez l'émetteur exactement comme votre fournisseur le publie : SpotBooker ne corrige rien en silence. Si l'émetteur publié diffère de celui que vous avez saisi, même d'un / final, le test le dit et affiche les deux valeurs : recopiez celle du fournisseur. Exemple : Keycloak publie https://<serveur>/realms/<realm>, sans / final.
L'adresse à saisir est celle de l'émetteur, pas celle du document de découverte : sans /.well-known/openid-configuration.
HTTPS obligatoire, joignable depuis Internet, sans ? ni #. Une adresse de réseau privé est refusée : un fournisseur placé derrière le pare-feu de l'établissement doit être rendu joignable depuis Internet.
Un domaine que vous déclarez filtre les adresses dès l'enregistrement. Pour qu'il retrouve aussi votre établissement depuis la page de connexion, atteste les adresses et admette automatiquement, il faut prouver qu'il vous appartient. Sans cette preuve, n'importe quel espace pourrait revendiquer votre domaine. La preuve vaut pour le domaine exact : institut.fr ne couvre pas labo.institut.fr, qui se déclare et se prouve à part.
Sous le champ des domaines, chaque domaine enregistré affiche son enregistrement : type TXT, valeur spotbooker-verification=….
Votre service informatique l'ajoute sur le domaine lui-même (par exemple institut.fr) ou, s'il préfère, sur _spotbooker.institut.fr. Il peut rester en place : SpotBooker le revérifie chaque jour.
Cliquez sur « Vérifier maintenant ». Sinon, SpotBooker le cherche seul toutes les 15 minutes pendant 14 jours. Un domaine est vérifié par un seul espace : s'il l'est déjà ailleurs, contactez le support. Si l'enregistrement disparaît 7 jours de suite, la vérification est retirée et vos administrateurs sont prévenus par e-mail.
Dans « Correspondance des groupes », associez une valeur de groupe du fournisseur à un groupe SpotBooker créé au préalable. À chaque connexion, la personne est ajoutée aux groupes correspondant aux siens chez le fournisseur et retirée de ceux qu'elle a quittés. Un groupe créé à la main dans SpotBooker n'est jamais modifié par la connexion.
Le fournisseur doit envoyer la claim groups (ou celle que vous avez indiquée). Avec Keycloak, c'est le mapper « Group Membership » ci-dessus ; pour des rôles, indiquez realm_access.roles. Google n'envoie pas de groupes : limitez alors l'accès par domaine.
Quand la personne se déconnecte de SpotBooker, elle est aussi déconnectée chez le fournisseur (RP-Initiated Logout), puis revient à la page de connexion avec ce message de confirmation : « Vous avez été déconnecté, y compris auprès de votre établissement. ». Pensez à déclarer l'URL après déconnexion chez le fournisseur.
Si le fournisseur ne publie pas de point de déconnexion, seule la session SpotBooker se ferme : la personne reste connectée chez le fournisseur. L'encart d'état de la connexion indique si la déconnexion centralisée est disponible.
Le jeton d'identité est toujours vérifié avec les clés publiées par le fournisseur (RS256, RS384, RS512, PS256, ES256, ES384). Les jetons non signés (none) et les signatures HMAC (HS256 et autres) sont refusés.
Une adresse envoyée avec email_verified: false n'est pas crue pour relier un compte existant : la personne est invitée à se connecter avec son mot de passe.
| Ce que vous voyez | Que faire |
|---|---|
| « La connexion par votre établissement n'est pas disponible. Rapprochez-vous de son administrateur. » | La connexion n'est pas activée, elle est incomplète, ou le fournisseur n'a pas pu être lu. Vérifiez dans Réglages que la connexion est activée et que l'état du fournisseur indique « Découvert le » suivi d'une date (et non « Pas encore découvert »), puis lancez le test. |
| « La connexion par votre établissement a échoué. Veuillez réessayer. » | Cause la plus fréquente : l'URL de redirection n'est pas déclarée à l'identique chez le fournisseur, ou le secret est faux. Vérifiez aussi la méthode d'authentification (client_secret_basic ou client_secret_post) et l'émetteur. La « Dernière erreur » de l'encart d'état donne la raison ; une page de connexion restée ouverte trop longtemps échoue aussi : recommencez. Le fournisseur n'a peut-être envoyé ni l'adresse e-mail ni l'identifiant (sub) dans les claims que vous avez configurés, même après la lecture du point userinfo : vérifiez les noms dans « Lecture des claims ». |
| « Votre compte n'est pas autorisé à accéder à cet espace. Rapprochez-vous de l'administrateur de votre établissement. » | L'adresse de la personne n'est pas dans les domaines acceptés, elle est déjà utilisée par un compte d'un autre espace SpotBooker, ou un administrateur a refusé la demande d'accès de cette personne. Dans le premier cas, ajoutez le domaine ; dans les autres, une personne refusée n'entre pas en se reconnectant. |
| « Un compte existe déjà avec cette adresse. Pour des raisons de sécurité, la liaison automatique n'est pas possible : connectez-vous avec votre mot de passe. » | Un compte SpotBooker existe déjà avec cette adresse et le fournisseur ne la déclare pas vérifiée (email_verified). Marquez l'adresse comme vérifiée chez le fournisseur, ou la personne se connecte avec son mot de passe. |
| « Votre demande d'accès a été transmise à l'administrateur de votre établissement. Vous recevrez un email dès qu'elle sera traitée. » | Normal quand l'admission automatique est désactivée, ou que le domaine n'est pas prouvé par le DNS : un administrateur doit accepter la demande dans la gestion des utilisateurs. |
| « Votre demande d'accès est en attente de validation par un administrateur. » | La personne a déjà demandé l'accès : un administrateur n'a pas encore tranché. Acceptez ou refusez la demande. |
| « Votre compte a été désactivé par votre établissement. Rapprochez-vous de son administrateur. » | Le compte a été désactivé parce que la personne a quitté l'annuaire. Il se rouvre tout seul quand l'annuaire la marque de nouveau active ; il ne se réactive pas à la main dans SpotBooker. Voir Synchroniser les utilisateurs avec SCIM. |
| « Obligatoire pour activer la connexion OpenID Connect (fournisseur découvert, identifiant, secret et au moins un domaine). » | Il manque une condition : fournisseur découvert, identifiant du client, secret, ou au moins un domaine accepté. Lancez le test, complétez les champs, puis activez à nouveau. |
| « L'adresse du fournisseur est refusée : elle n'est pas en HTTPS, ou contient une requête (?), un fragment (#) ou des caractères non autorisés. » | L'émetteur n'est pas en HTTPS, ou contient un ? ou un #. Saisissez l'adresse de l'émetteur seule, en HTTPS. |
| « Cette adresse pointe vers un réseau privé : SpotBooker ne s'y connecte pas. » | L'adresse désigne une machine d'un réseau privé. Rendez le fournisseur joignable depuis Internet, puis utilisez son adresse publique. |
| « Impossible de joindre le fournisseur. Vérifiez l'adresse et que le serveur est accessible depuis Internet. » | Adresse mal saisie, ou serveur inaccessible depuis Internet (pare-feu, certificat HTTPS invalide). Vérifiez l'adresse et ouvrez-la dans un navigateur extérieur à l'établissement. |
| « Le fournisseur a répondu par une erreur. Vérifiez l'émetteur : l'adresse ne doit pas inclure /.well-known/openid-configuration. » | L'adresse saisie n'est pas celle d'un fournisseur OpenID Connect. Retirez /.well-known/openid-configuration et vérifiez le chemin (avec Keycloak : /realms/<realm>). |
| « L'émetteur saisi (https://sso.example.fr/) ne correspond pas à celui que publie le fournisseur (https://sso.example.fr). Recopiez-le à l'identique, au caractère près (y compris un « / » final). » | L'émetteur saisi diffère de celui que publie le fournisseur. Recopiez la valeur trouvée, au caractère près, y compris un / final. SpotBooker ne la corrige pas à votre place. |
| « Le document du fournisseur est incomplet : il manque une adresse indispensable (autorisation, jeton ou clés). » | Le document du fournisseur ne contient pas toutes les adresses utiles. Vérifiez la configuration du fournisseur ou du realm. |
| « La connexion a été enregistrée, mais la découverte du fournisseur a échoué : … » | Les réglages sont enregistrés, mais la connexion ne peut pas être utilisée avant que la découverte réussisse. Corrigez la cause indiquée, puis lancez le test. |
| « La réponse du fournisseur n'est pas un document OpenID Connect lisible. » | L'adresse ne mène pas à un fournisseur OpenID Connect (page web, portail, redirection). Vérifiez l'émetteur. |
| « La réponse du fournisseur est anormalement volumineuse : elle a été refusée. » | Une réponse anormalement volumineuse n'est pas lue. Vérifiez que l'adresse est bien celle d'un fournisseur OpenID Connect. |
| « Le test a échoué. Vérifiez l'émetteur saisi. » | Le message ne donne pas de précision : vérifiez l'émetteur saisi, puis relancez le test. |