Guide
Guide
Shibboleth, ADFS, Keycloak, Okta…: your users get into SpotBooker with their organisation credentials.
Your organisation does not use Microsoft Entra ID? It almost always has a SAML 2.0 identity provider: Shibboleth at institutions in the RENATER federation, ADFS, Keycloak, Okta… Once it is linked to SpotBooker, everyone signs in with their usual credentials, with no extra password. SAML sign-in is included in the subscription and available during the free trial. Only your workspace administrators can set it up, usually together with IT.
Your identity provider only signs people in to services it knows. The “To declare in your identity provider” box shows your workspace identifier (entity ID, which is also the address of the metadata file) and the return URL. Send the metadata file: it contains everything, certificate included. These addresses never change, even if you change your workspace's public address.
Easiest: paste its XML metadata, for your own identity provider only, not the whole federation file. SpotBooker reads its identifier, sign-in URL and signing certificate from it. Otherwise, fill in these three fields by hand; the sign-in URL must start with https://. During a certificate renewal, paste both certificates one after the other: each one's expiry date is shown.
SpotBooker needs the email address and an identifier that stays the same from one sign-in to the next; first name, last name and groups are optional. The usual names are recognised out of the box: eduPersonPrincipalName for the identifier (otherwise a persistent NameID), mail, givenName, sn and isMemberOf, plus their ADFS equivalents. Only fill in the attribute mapping if your identity provider uses other names. On the organisation's side, these attributes must be released to SpotBooker.
Separate them with commas, for instance institute.edu, cnrs.fr. They do three things: only these addresses can sign in; your users find your organisation by typing their address on the sign-in page; and a SpotBooker account that already exists at one of these addresses is linked to the directory instead of being refused. With no domain, any address your identity provider authenticates is accepted, but the last two effects are lost. Discovery from the login page, linking of existing accounts and automatic admission only apply once the domain is proven (see “Prove your domains” below).
With automatic admission, anyone in the directory gets in on their first sign-in, with no admin rights. Turn it off if your directory also holds students or guests who should not book: each first sign-in then files an access request that you approve or decline. These settings belong to SAML: Microsoft sign-in keeps its own.
Map a group value sent by the directory (for instance an isMemberOf entry) to a SpotBooker group created beforehand. At every sign-in, the user joins the matching groups and leaves the ones they are no longer in. Groups you manage by hand in SpotBooker are never touched.
Turn sign-in on, then save. It cannot be turned on until the identifier, sign-in URL and certificate are filled in. Try it first with a directory account, in a private browsing window.
On the sign-in page, they choose “Sign in with your organisation”, type their address (or just the domain) and land on your organisation's sign-in page. You can also give them the direct sign-in link shown in the settings, for instance on your intranet.
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.
Optional: the “Sign-out URL (SLO, Redirect binding)” field expects an https:// address, and fills itself in if the pasted metadata contains one. For its part, SpotBooker publishes its “Sign-out URL (Single Logout Service)” in its metadata: if your organisation declared them earlier, ask it to reload them. Without a sign-out URL, signing out only closes the SpotBooker session.
The SpotBooker session is closed first, then a signed request goes to your identity provider. If it does not confirm, the person stays signed out of SpotBooker and sees “You are signed out of SpotBooker, but your organisation did not confirm that your session there has ended. Close your browser to end it.”
When your identity provider sends a signed sign-out request, SpotBooker closes all of the person's sessions, on all their devices, and shows them “You have been signed out by your organisation”. As for sign-in, a request that is unsigned, signed with SHA-1, too old or already received is refused.
| Refused | Why |
|---|---|
| An unsigned response | Your identity provider's signature is what proves the response comes from it. It can cover the response or the assertion: Shibboleth signs the response by default, nothing to change. |
| A SHA-1 signature | This algorithm is no longer safe enough, for signatures or digests. Set your identity provider to SHA-256. |
| A sign-in started from your organisation's portal | SpotBooker only accepts a response to a request it has just issued, usable once and for 10 minutes: an intercepted response cannot be replayed. Sign-in must therefore start from SpotBooker. For a portal tile, use the direct sign-in link. |
| A transient identifier only | A transient NameID changes at every sign-in: SpotBooker would not recognise the person next time. Send eduPersonPrincipalName or a persistent NameID. |
| An address outside your domains | If you declared domains, other addresses do not get in, even when your identity provider authenticates them. |
| What you see | What to do |
|---|---|
| “No organisation sign-in matches this address” | The domain typed is not in your accepted email domains, or SAML sign-in is not turned on. Add the domain and check it is turned on. |
| “Signing in through your organisation is not available” | Sign-in is turned off or incomplete, or the free trial ended without a subscription. Your settings are kept: they apply again as soon as you subscribe. |
| “Signing in through your organisation failed” | Your identity provider answered, but the response was refused. Common causes: certificate renewed at the organisation but not in SpotBooker (check its expiry date), SHA-1 signature, email address not sent, sign-in left pending for more than 10 minutes. For security the detail is not shown: write to us with the time of the attempt and we will find it. |
| Your identity provider shows an error before coming back | It does not know SpotBooker yet, or not under this identifier. Have the metadata from step 1 declared in your identity provider. |
| “Your account is not allowed to access this space” | The address is outside your domains, it is already used in another SpotBooker workspace, or this person's access request was declined. A declined person does not get in by signing in again. |
| “An account already exists with this address…” | A SpotBooker account already exists at this address, and it is only linked to the directory if its domain is in your accepted domains. Add the domain, or the person signs in with their password. |
| “Your access request has been sent…” or “Your account has been disabled…” | The first message is expected without automatic admission: approve the request. The second means the person left the directory: see Sync users with SCIM. |