Guide
Guide
Keycloak, LemonLDAP::NG, Authentik, Okta, Google… : your users sign in to SpotBooker with their organisation credentials.
Does your organisation have an identity provider that speaks OpenID Connect (OIDC)? Keycloak, LemonLDAP::NG, Authentik, Okta and Google Workspace all do. Once linked to SpotBooker, everyone signs in with their usual credentials, with no extra password. OpenID Connect sign-in is included in the subscription; like SAML sign-in, it needs full access (a subscription or a running trial). Only your workspace administrators set it up, most often with the IT department.
Its address (the issuer) must be HTTPS and reachable from the Internet: SpotBooker refuses private network addresses and addresses that contain a ? or a #.
You must be able to declare an application there: a confidential client (with a secret), using the authorization code flow. SpotBooker always sends PKCE (S256) as well.
For instance institute.edu. Unlike SAML, OpenID Connect sign-in cannot be turned on without a domain: one provider (Google, Okta…) can serve many organisations, and with no domain all of its accounts could get in.
It lets you prove the domain is yours (see "Prove your domains" below). This proof is essential for your users to reach the sign-in from the login page: without it, the address they type does not find your organisation, automatic admission does not apply and an existing account cannot be linked by its address.
Your provider only signs in an application it knows. The "To declare in your provider" box shows two addresses, each with a Copy button: the redirect URI, shaped like https://<your-workspace>/oidc/<key>/callback, and the post-logout redirect URI, https://<your-workspace>/oidc/<key>/logged-out. The key is stable: these addresses do not change, even if you change your workspace's public address.
Create an application of the confidential client type, using the authorization code flow. Declare the redirect URI from step 1; declare the post-logout URI only if your provider offers single sign-out. Note the client ID and its secret. The Keycloak and LemonLDAP::NG recipes are below.
In SpotBooker, choose the provider type (it only pre-fills the help), enter the issuer exactly as the provider publishes it, then click "Test the provider". The test reads /.well-known/openid-configuration and the signing keys, and saves nothing. The secret itself is only checked at the first real sign-in.
Copy the client ID and its secret (encrypted when saved, never shown again). Authentication at the token endpoint is client_secret_basic by default; choose client_secret_post only if your provider requires it. The default scopes are openid email profile; openid is always added.
Claims are the pieces of information the provider puts in the person's token. By default: sub (unique identifier), email, given_name (first name), family_name (last name) and groups. A claim can be a nested path, for instance realm_access.roles. If the address or the names are missing from the token, SpotBooker reads the provider's userinfo endpoint, after checking it is the same sub.
Turning it on requires: a successful discovery of the provider, the client ID, the secret, and at least one accepted domain. If one is missing, SpotBooker says so and turns nothing on. Every change to the sign-in is written to the activity log.
In your realm, open Clients then Create client. Client type: OpenID Connect. On the next step, turn on Client authentication (confidential access) and keep Standard flow (authorization code) ticked. The secret is then in the Credentials tab.
In "Valid redirect URIs", paste the redirect URI copied in step 1. If you want single sign-out, paste the post-logout URI in "Valid post logout redirect URIs". The issuer looks like https://server/realms/name, with no trailing /.
To receive groups, open the client, Client scopes tab, then the client's dedicated scope (…-dedicated) and Add mapper > By configuration > Group Membership. Name it groups, put groups in "Token Claim Name", and turn off "Full group path" if you want plain names (lab rather than /lab). For realm roles, use the realm_access.roles claim instead.
An address sent with email_verified: false is not trusted to link an existing SpotBooker account. In Keycloak, mark addresses as verified (user: "Email verified"); otherwise people who already have an account will have to sign in with their password.
In the Manager, add an "OpenID Connect Relying Party" (RP) for SpotBooker, with a client ID and a secret. The issuer to enter in SpotBooker is the address of the LemonLDAP::NG portal, for instance https://auth.example.fr. For this relying party, the client ID and secret are under Options → Basic (Client ID, Client secret).
Add the redirect URI from step 1 to the relying party's allowed redirect addresses (and the post-logout URI for single sign-out). For authentication at the token endpoint, keep client_secret_basic, which is also SpotBooker's default.
In the relying party's exported attributes, map the email, given_name and family_name claims to your directory attributes (for instance mail, givenName, sn), and groups if you want groups to be driven. Add the matching scope in SpotBooker if LemonLDAP::NG requires it.
Enter the issuer exactly as your provider publishes it: SpotBooker corrects nothing silently. If the published issuer differs from the one you typed, even by a trailing /, the test says so and shows both values: copy the provider's. Example: Keycloak publishes https://<server>/realms/<realm>, with no trailing /.
The address to enter is the issuer's, not the discovery document's: without /.well-known/openid-configuration.
HTTPS is required, reachable from the Internet, with no ? or #. A private network address is refused: a provider behind your organisation's firewall must be made reachable from the Internet.
A domain you declare filters addresses as soon as it is saved. For it to also find your organisation from the login page, vouch for addresses and admit automatically, you must prove it is yours. Without that proof, any workspace could claim your domain. The proof covers the exact domain only: institut.fr does not cover labo.institut.fr, which must be declared and proven separately.
Under the domains field, each saved domain shows its record: type TXT, value spotbooker-verification=….
Your IT team adds it on the domain itself (for example institut.fr) or, if they prefer, on _spotbooker.institut.fr. It can stay in place: SpotBooker re-checks it every day.
Click “Verify now”. Otherwise SpotBooker looks for it on its own every 15 minutes for 14 days. A domain is verified by a single workspace: if it already is elsewhere, contact support. If the record disappears for 7 days in a row, the verification is withdrawn and your administrators are notified by email.
In "Group mapping", pair a group value from the provider with a SpotBooker group created beforehand. At every sign-in, the person is added to the groups matching theirs at the provider and removed from those they left. A group created by hand in SpotBooker is never changed by the sign-in.
The provider must send the groups claim (or the one you entered). With Keycloak, that is the "Group Membership" mapper above; for roles, enter realm_access.roles. Google does not send groups: limit access by domain instead.
When the person signs out of SpotBooker, they are also signed out at the provider (RP-Initiated Logout), then return to the login page with this confirmation message: "You have been signed out, including from your organisation.". Remember to declare the post-logout URI at the provider.
If the provider publishes no sign-out endpoint, only the SpotBooker session closes: the person stays signed in at the provider. The sign-in status box tells you whether single sign-out is available.
The identity token is always checked with the keys the provider publishes (RS256, RS384, RS512, PS256, ES256, ES384). Unsigned tokens (none) and HMAC signatures (HS256 and others) are refused.
An address sent with email_verified: false is not trusted to link an existing account: the person is asked to sign in with their password.
| What you see | What to do |
|---|---|
| « Signing in through your organisation is not available. Please contact its administrator. » | The sign-in is not turned on, is incomplete, or the provider could not be read. In Settings, check that the sign-in is turned on and that the provider status reads "Discovered on" followed by a date (not "Not discovered yet"), then run the test. |
| « Signing in through your organisation failed. Please try again. » | Most often: the redirect URI is not declared identically at the provider, or the secret is wrong. Also check the authentication method (client_secret_basic or client_secret_post) and the issuer. The "Last error" in the status box gives the reason; a login page left open too long also fails: start again. The provider may also have sent neither the email address nor the identifier (sub) in the claims you configured, even after the userinfo call: check the names under "Claim mapping". |
| « Your account is not allowed to access this space. Please contact your organisation's administrator. » | The person's address is outside the accepted domains, it is already used by an account in another SpotBooker space, or an administrator refused this person's access request. In the first case, add the domain; in the others, a refused person does not get in by signing in again. |
| « An account already exists with this address. For security reasons it cannot be linked automatically: please sign in with your password. » | A SpotBooker account already exists with this address and the provider does not say it is verified (email_verified). Mark the address as verified at the provider, or the person signs in with their password. |
| « Your access request has been sent to your organisation's administrator. You will receive an email once it has been reviewed. » | Expected when automatic admission is off, or the domain is not proven through DNS: an administrator must accept the request in user management. |
| « Your access request is waiting for an administrator to review it. » | The person has already asked for access: an administrator has not decided yet. Accept or refuse the request. |
| « Your account has been disabled by your organisation. Please contact its administrator. » | The account was disabled because the person left the directory. It reopens by itself when the directory marks them active again; it cannot be re-enabled by hand in SpotBooker. See Sync users with SCIM. |
| « Required to enable OpenID Connect sign-in (discovered provider, client ID, secret and at least one domain). » | A condition is missing: discovered provider, client ID, secret, or at least one accepted domain. Run the test, complete the fields, then turn it on again. |
| « The provider address is refused: it is not HTTPS, or it contains a query (?), a fragment (#) or characters that are not allowed. » | The issuer is not HTTPS, or contains a ? or a #. Enter the issuer address alone, over HTTPS. |
| « This address points to a private network: SpotBooker will not connect to it. » | The address points to a machine on a private network. Make the provider reachable from the Internet, then use its public address. |
| « Cannot reach the provider. Check the address and that the server is reachable from the Internet. » | Wrong address, or a server unreachable from the Internet (firewall, invalid HTTPS certificate). Check the address and open it in a browser outside your organisation. |
| « The provider answered with an error. Check the issuer: the address must not include /.well-known/openid-configuration. » | The address you entered is not an OpenID Connect provider's. Remove /.well-known/openid-configuration and check the path (with Keycloak: /realms/<realm>). |
| « The issuer you typed (https://sso.example.fr/) does not match the one the provider publishes (https://sso.example.fr). Copy it exactly, character for character (including a trailing "/"). » | The issuer you typed differs from the one the provider publishes. Copy the value found, character for character, including a trailing /. SpotBooker does not correct it for you. |
| « The provider's document is incomplete: a required address is missing (authorization, token or keys). » | The provider's document does not hold all the useful addresses. Check the provider's or realm's configuration. |
| « The sign-in was saved, but discovering the provider failed: … » | The settings are saved, but the sign-in cannot be used until discovery succeeds. Fix the cause shown, then run the test. |
| « The provider's response is not a readable OpenID Connect document. » | The address does not lead to an OpenID Connect provider (web page, portal, redirect). Check the issuer. |
| « The provider's response is abnormally large and was refused. » | An abnormally large response is not read. Check that the address really is an OpenID Connect provider's. |
| « The test failed. Check the issuer you typed. » | The message gives no detail: check the issuer you typed, then run the test again. |