LibreBooking OAuth2 Integration

This document explains how to implement Monosign with LibreBooking, the open-source resource scheduling and booking application. It covers Single Sign-On with OAuth 2.0, which is built into LibreBooking as the Oauth2 authentication option. LibreBooking uses the Authorization Code flow and reads the user from the user information endpoint, so the OIDC/OpenID access key of Monosign is used as an OAuth 2.0 provider. Before you continue, it is better to read the LibreBooking Oauth2 configuration documentation.

This configuration is done with LibreBooking running on Docker Compose (image librebooking/librebooking:7.1.0 and mariadb:11). If your LibreBooking version or deployment type is different, please check the LibreBooking documentation.

LibreBooking supports OAuth 2.0 for this scenario. It does not validate an ID token (no issuer or nonce check) and it does not use the discovery document. SAML is available only through the separate SAML plugin, which needs an external SimpleSAMLphp installation. There is no single sign-on screen in the LibreBooking administration; the provider is defined with the oauth2.* settings of config/config.php or with the equivalent LB_AUTHENTICATION_OAUTH2_* environment variables.

The local user name and password login stays available next to the Sign in with Monosign button, unless you hide it (see step 4).

Monofor has no responsibility to do LibreBooking configurations. If you need support please contact the LibreBooking community or your LibreBooking support provider.

📑 Instructions

This documentation contains 5 main steps for integration.

Creating an application on Monosign
Configuring the OIDC/OpenID settings on Monosign
Assign a user to the LibreBooking application
Configuration Single Sign-On for LibreBooking
Sign In Test

1- Creating an Application on Monosign

Create your application on Monosign first. Open the Applications page from the left menu and click Add New.

Applications page in Monosign (1: Applications menu, 2: Add New)

LibreBooking is not in the application catalog, so click Create from scratch.

Creating a new application from scratch (1: Create from scratch)

Fill in the application details on the Application tab and click Next.

New Application - Application tab (1: Name, 2: Logo (optional), 3: Next)

Property	Value	Description
Name	`LibreBooking`	Name of the application shown to users on the Monosign portal and on the Monosign sign-in page.
Type	`Web`	LibreBooking is accessed through a web browser. Options: Web, Mobile, Desktop, API.
Url	Optional	Leave empty or enter the LibreBooking address (for example `https://<librebooking-address>/Web/`) so users can open the application from their Monosign portal (see the note in step 5).
Logo	Optional	Browse and upload a logo; it is also shown on the Monosign sign-in page.
Users can see this application on their list	`Enabled`	Displays the application on the user portal.

On the Access tab define who can reach the application and click Create Application.

New Application - Access tab (1: Profile Access Type, 2: Create Application)

Property	Value	Description
User Access Type	`System Default`	Defines which users can access this application. Options: Only Assigned Users, All Users, System Default.
User Group Access Type	`System Default`	Defines the application’s user group access.
Source Using Type	`System Default`	Defines which user sources the application can use.
Profile Access Type	`All`	Defines which user profile attributes are available to the application (Options: Restricted, All). LibreBooking needs the e-mail address, the user name and the name of the user.

By default LibreBooking creates an account for every Monosign user who signs in for the first time (see step 4). Make sure the effective User Access Type is Only Assigned Users and give access only to the users you assign in step 3.

After the application is created, click Keys and add a new Access Key for OIDC/OpenID access.

Keys tab of the LibreBooking application (1: Keys, 2: Add New Access Key)

Select OIDC/OpenID as the key type and click Create. Monosign generates the Client Id and Client Secret automatically.

Creating the OIDC/OpenID Access Key (1: Type OIDC/OpenID, 2: Create)

Property	Value	Options
Type	`OIDC/OpenID`	Rest API, OAuth 2.0, JWT, OIDC/OpenID, SAML, RADIUS, Access Gateway, LDAP, AuthN/Z Server
Client Id / Client Secret	Generated automatically	Use the eye icon next to the secret to reveal it. Both values are required in step 4.
Session	`System Default`	System Default, On-demand, Permanent
State	`Enabled`	Enabled, Disabled
Never Expires	`Yes`	Turn off to define a specific expiration date for the key.

Configuration details for the LibreBooking application are provided as follows:

Monosign value	Example	Used in LibreBooking as
Client Id	`<client-id>`	`oauth2.client.id`
Client Secret	`<client-secret>`	`oauth2.client.secret`
Auth Url	`https://<monosign-host>/openid/authorize`	`oauth2.url.authorize`
Access Token Url	`https://<monosign-host>/openid/token`	`oauth2.url.token`
User Info Url	`https://<monosign-host>/openid/userinfo`	`oauth2.url.userinfo`. LibreBooking reads the user from this address with the access token.

2- Configuring the OIDC/OpenID Settings on Monosign

Click the Configure button of the OpenID Connect (OIDC) key to open the OIDC/OpenID settings and add the callback address of LibreBooking to Allowed Redirect URIs.

OIDC/OpenID Settings (1: Allowed Redirect URIs)

Property	Value	Description
Allowed Redirect URIs	`https://<librebooking-address>/Web/oauth2-auth.php`	The address where Monosign sends the user back after sign-in. The path `/Web/oauth2-auth.php` is fixed by LibreBooking. LibreBooking builds the address from its `script.url` setting, so use the public (HTTPS) address that users type in the browser.
Signing Key / Key Id / Password, Issuer, Audience, Scope, Resource	Empty	Optional custom JWT settings. They are not needed. LibreBooking sends the scopes itself (`openid email profile`).
Token lifetimes, CORS	Empty	Default values are used.

LibreBooking reads the user name, the first name and the last name from the UserInfo response. Open the Claim Mapping tab of the settings, add the following rows and click Update.

Claim Name	Value	Used in LibreBooking as
`preferred_username`	`{{UserName}}`	User name. When the claim is missing, LibreBooking uses the e-mail address as the user name.
`given_name`	`{{Profile.FirstName}}`	First name.
`family_name`	`{{Profile.LastName}}`	Last name.

The email claim is required and Monosign returns it by default, so it does not need to be mapped. LibreBooking can also read phone_number, organization and title; add them in the same way if you want these fields to be filled in.

3- Assign a User to the LibreBooking Application

Please follow the below instructions on how to assign a user to the LibreBooking application. Open the application, click the Assignments tab and click Assign a User.

Assignments tab of the LibreBooking application (1: Assignments, 2: Assign a User)

Search and select the users who can sign in to LibreBooking, check the Expiration Date and save. You can select more than one user.

Assign a User dialog (select the users, set the Expiration Date)

Property	Value	Description
User(s)	Selected users	Users who can sign in to LibreBooking with Monosign.
Expiration Date	Default one year	The assignment expires on this date.

4- Configuration Single Sign-On for LibreBooking

As we mentioned at the start, please check out the LibreBooking documentation first. In the Docker deployment LibreBooking is configured with environment variables that start with LB_. Add the following variables to the environment of the LibreBooking container (for example the .env file that is used with env_file) and replace the placeholder values.

Bash

LB_SCRIPT_URL=https://<librebooking-host-name>/Web
LB_AUTHENTICATION_OAUTH2_LOGIN_ENABLED=true
LB_AUTHENTICATION_OAUTH2_NAME=Monosign
LB_AUTHENTICATION_OAUTH2_STRIP_TRAILING_SLASH=false
LB_AUTHENTICATION_OAUTH2_URL_AUTHORIZE=https://<monosign-host>/openid/authorize
LB_AUTHENTICATION_OAUTH2_URL_TOKEN=https://<monosign-host>/openid/token
LB_AUTHENTICATION_OAUTH2_URL_USERINFO=https://<monosign-host>/openid/userinfo
LB_AUTHENTICATION_OAUTH2_CLIENT_ID=<client-id>
LB_AUTHENTICATION_OAUTH2_CLIENT_SECRET=<client-secret>
LB_AUTHENTICATION_OAUTH2_CLIENT_URI=/Web/oauth2-auth.php

Without Docker the same settings are written to the authentication section of config/config.php:

PHP

return [
    'settings' => [
        'authentication' => [
            'oauth2.login.enabled' => true,
            'oauth2.name' => 'Monosign',
            'oauth2.strip.trailing.slash' => false,
            'oauth2.url.authorize' => 'https://<monosign-host>/openid/authorize',
            'oauth2.url.token' => 'https://<monosign-host>/openid/token',
            'oauth2.url.userinfo' => 'https://<monosign-host>/openid/userinfo',
            'oauth2.client.id' => '<client-id>',
            'oauth2.client.secret' => '<client-secret>',
            'oauth2.client.uri' => '/Web/oauth2-auth.php',
        ],
    ],
];

Setting	Value	Description
LB_SCRIPT_URL (`script.url`)	`https://<librebooking-host-name>/Web`	Public address of LibreBooking. The redirect address that is sent to Monosign is built from it, so it must match the Allowed Redirect URI of step 2.
oauth2.login.enabled	`true`	Shows the single sign-on button on the sign-in page.
oauth2.name	`Monosign`	Text of the button (“Sign in with Monosign”).
oauth2.strip.trailing.slash	`false`	By default LibreBooking removes the trailing slash of the authorize address. It affects only this address, so it does not matter for Monosign.
oauth2.url.authorize / token / userinfo	Monosign addresses	Auth Url, Access Token Url and User Info Url of the Monosign access key. LibreBooking does not use the discovery document, so the three addresses must be written.
oauth2.client.id / secret	Client Id / Client Secret	Copied from the Monosign OIDC/OpenID Access Key Details created in the first step. LibreBooking sends them in the body of the token request, which Monosign accepts.
oauth2.client.uri	`/Web/oauth2-auth.php`	Callback path. It is added to the script address for the redirect address.

How LibreBooking handles the user: the user is found with the user name and the e-mail address. If the user exists, LibreBooking signs the user in. If the user does not exist and self registration is allowed (allow.self.registration, default on), LibreBooking creates the account with the e-mail address, the user name and the names from Monosign and signs the user in. When self registration is off, a new user gets the message that self registration is disabled, so create the user in LibreBooking first with the same e-mail address.

The application administrator is the user whose e-mail address is the value of LB_ADMIN_EMAIL (admin.email). Set it to the e-mail address of the Monosign user who should manage LibreBooking.

The local login form stays on the sign-in page. To show only the Monosign button, add the setting LB_AUTHENTICATION_HIDE_LOGIN_PROMPT=true (hide.login.prompt). Keep the local login until you have tested the single sign-on, because the local administrator is the way back if the configuration is wrong.

The environment file contains the client secret, the database password and the installation password. Restrict its permissions (for example chmod 600) and do not store it in a shared repository. Change the default password of the LibreBooking admin user (password) right after the installation.

Recreate the LibreBooking container so that the new variables are loaded:

Bash

cd <librebooking-compose-directory>
docker compose up -d --force-recreate app

The sign-in page must now show the user name and password form and the Sign in with Monosign button.

Now try to log in to LibreBooking using Monosign SSO.

Open a new browser window (or a private window) and type the LibreBooking address. The sign-in page shows the local form and the Sign in with Monosign button.

LibreBooking sign-in page with the “Sign in with Monosign” button

Click Sign in with Monosign. LibreBooking redirects the browser to the Monosign sign-in page of the LibreBooking application. You can log in passwordless with your QR code (Monofor Identity), with a Passkey or with your user name and password (Sign in with Password). If you are already signed in to Monosign, the page is skipped.
After the sign-in Monosign redirects the browser back to LibreBooking (/Web/oauth2-auth.php). LibreBooking finds or creates the account and opens the dashboard. In My Account → Profile the user name, the e-mail address and the names come from Monosign.

User logged in to LibreBooking through Monosign SSO (Edit My Profile)

The sign-in of LibreBooking starts when the user clicks the Monosign button on its sign-in page. If you enter the LibreBooking address as the Url of the application (step 1), the user who opens LibreBooking from the Monosign portal lands on the sign-in page and clicks Sign in with Monosign once.

Troubleshooting

Symptom	Cause	Solution
The “Sign in with Monosign” button is not shown	`oauth2.login.enabled` is not `true`, or the container was not recreated.	Set the variables (step 4) and run `docker compose up -d --force-recreate app`.
Monosign shows a redirect URI error	The redirect address that LibreBooking sends does not exactly match the Allowed Redirect URIs, for example because `script.url` is wrong.	Add `https://<librebooking-address>/Web/oauth2-auth.php` in Monosign (step 2) and set `LB_SCRIPT_URL` to the same public HTTPS address.
LibreBooking shows “Error retrieving Oauth2 token” after returning from Monosign	The token request failed: wrong Client Id or Secret, wrong token address, or the container cannot reach Monosign.	Check the Client Id, the Secret and the token and UserInfo addresses, and the DNS and firewall rules of the LibreBooking host. The message contains the answer of Monosign.
LibreBooking shows “Email is not set in your Oauth2 profile”	The UserInfo response has no `email` claim.	Set the Profile Access Type of the application to All (step 1) and make sure the Monosign user has an e-mail address.
The user name is the e-mail address and the first and last name are empty	The claims `preferred_username`, `given_name` and `family_name` are not mapped.	Add the claim mapping rows of step 2 and click Update.
A new user sees the message that self registration is disabled	`allow.self.registration` is off, so LibreBooking does not create accounts for new users.	Turn the setting on, or create the user in LibreBooking first with the same e-mail address.
The sign-in is refused with an invalid e-mail domain message	A required e-mail domain is configured in LibreBooking and the e-mail address of the user is in another domain.	Use a user from the allowed domain or change the domain setting of LibreBooking.
A user cannot sign in	The user is not assigned to the application.	Assign the user in step 3.
ID token validation or SAML sign-in is required	The Oauth2 option of LibreBooking does not validate an ID token.	Use the OAuth 2.0 integration in this document, or the SAML plugin of LibreBooking with SimpleSAMLphp.

After completing the configuration on LibreBooking and Monosign, it is better to test in a new private browser window if the SSO doesn’t work, because old session cookies of the LibreBooking address may cause errors.