SAML
Requirements (on-premise)
If you plan to migrate from GLPI SAML to SAMLSSO. Make sure GLPI SAML is removed completely from the environment and GLPI is updated to version 11 before installing samlSSO. (!) You need an admin access to the Entra/Google console to setup the application
Download the plugin (on-premise)
From the marketplace (Setup > Plugins), download the SAMLSSO plugin
See manual installation instructions if you cant or dont want to use the marketplace feature (isolated environments).
Configure identity providers
If installed correctly the plugin offers various routes to the configuration page.
Either click the wrench icon in the marketplace or navigate to
Setup>samlSSOEither click
Addor use the Backup / Restore feature to restore a previous configuration.
Consider your login strategy
SAMLSSO is designed to supports multiple identity providers.This allows you to add multiple identity providers for different customers. To deal with multiple identity providers simultaneously the plugin also offers different redirect scenario’s.
The following scenario’s are available:
Buttonized login The plugin will show a button for each IDP configured. This allows a user to visually select the required IDP. Buttonized login requires you to leave the
IdP>General>Userdomainoption either blank or default (youruserdomain.tld).
This option does potentially expose client and configuration information to the visiting clients.
Domain based redirection. With domain based redirection the plugin will actively hide the default GLPI password, login source, remember me form elements and actively blocks them from being used. The correct IDP is selected by matching the domain name in the username (email) with the correct IDP. Domain based redirection requires you to set the
IdP>General>Userdomainoption to the correct domainname.
This option does allow you to configure multiple top level domains using a comma separated list i.e. domain1.tld, domain2.tld, etc.
The blockade can be bypassed by adding the URL parameter: bypass=1. With this parameter the default GLPI loginscreen will be shown. In a future release we will add a configurable secret to be used for this bypass.
The config page will show warnings for the configuration fields that are omitted if domain based redirection is enabled. This is intended as a visual cue to verify domain based redirects are enabled.
Fully automated login If the
IdP>Security>Enforcedoption is enabled the plugin will automatically select the IDP and always forward the user to the given IDP. This option will only work if only one IDP is configured. Environments with multiple IDPS cannot be enforced because there is no viable way to predict the correct IDP for any given usersession.If enforcement fails the plugin will fall back to one of the previously described login strategies.
The automated flow be bypassed by adding the URL parameter: bypass=1. With this parameter the default GLPI loginscreen will be shown. In a future release we will add a configurable secret to be used for this bypass.
Understanding the basic SAML-flow
SAML (Security Assertion Markup Language) relies on a precise "handshake" between the Service Provider (GLPI) and the Identity Provider (IdP). If any certificate, Entity ID, or Assertion Consumer Service (ACS) URL is misaligned, the authentication flow will fail. Because of this strictness, the SAML protocol (if configured correctly) is very resilient and secure, and highly desired in environments where rigid security is required.
To configure this handshake successfully, you will need to understand how the exchange of specific configuration parameters takes place between the two primary actors.
The Service Provider (SP)
This is the application you are trying to access—in our case, GLPI. During login, the samlSSO plugin will generate a SAMLRequest and send it to the Identity Provider (IdP), using the configuration stored in GLPI to construct this message.
In order to validate the authenticity of the request, the IdP will verify its contents. For example, it will validate the SP URLs provided in the message against its own registry, and verify any signature present in the request using the Service Provider's public certificate. Any mismatch will result in an error reported by the Identity Provider.
The Identity Provider (IdP)
Once a valid SAMLRequest is received, the Identity Provider will attempt to authenticate the user using its own directory and authentication procedures. For instance, if Multi-Factor Authentication (MFA) is required, this is enforced by the Identity Provider during its authentication process, not by the Service Provider.
If the user successfully logs in (or already has an active session with the IdP), the IdP will generate a SAMLResponse using its own configuration. This response determines what user information (Claims) to include (e.g., phone, department, email), whether fields need to be encrypted, and how the response is signed using the IdP's private keys. Once complete, the Identity Provider sends the response back to the Assertion Consumer Service (ACS)—an endpoint provided by the samlSSO plugin.
The Service Provider (SP) - Verification
Once the SAMLResponse is received by the samlSSO plugin, the plugin validates the assertion. It verifies the cryptographic signatures and the payload content using the configuration and the public X.509 certificate provided by the Identity Provider.
As the administrator, you must precisely configure what to expect—such as which fields will be signed, what will be encrypted, and ensure that the URLs in the payload match your environment.
Plugin State Machine
The samlSSO plugin implements a strict state machine. This means the plugin tracks each authentication request rigorously. The unique ID of each request is registered and matched with the signed InResponseTo headers in the incoming SAMLResponse. This is a critical security mechanism that protects your environment from replay attacks and unauthorized session fuzzing attempts.
Most configuration errors are made in the certificate exchange. The following table is an attempt to explain what certificates are needed for what security option in the SAML configuration page.
Security Operation
Actor
Key/Certificate Used by actor
Verified / Decrypted By
Key/Certificate Used for Verification
Sign Outbound Requests (AuthnRequest / LogoutRequest)
Service Provider (GLPI)
🟪 SP Private Key
Identity Provider (IdP)
🔵SP Public Certificate
Encrypt Outbound Messages
Service Provider (GLPI)
🟪 IdP Public Certificate
Identity Provider (IdP)
🔵IdP Private Key
Sign Inbound Assertions / Responses (SAMLResponse)
Identity Provider (IdP)
🔵IdP Private Key
Service Provider (GLPI)
🟪 IdP Public Certificate
Encrypt Inbound Assertions (SAMLResponse Encryption)
Identity Provider (IdP)
🔵SP Public Certificate
Service Provider (GLPI)
🟪 SP Private Key
🔵Configured in the IDP. 🟪Configured in the samlSSO plugin.
Given the nature of SAML described above the following configuration examples might not reflect your precise environment and might not work out-of-the-box some fine-tuning might be required.
For Entra,Google see specific configuration instructions.
Entra ID (Active Directory)
In GLPI, open the
IdP>Transittab. Basically the transit tab should be seen as an ‘compatibility’ tab. The options in this tab allow you to ‘tweak’ the interactions for different identity providers capabilities. In case of entra for instance compression must be enabled and XML validation should be performed.
If in doubt, use the (?) to get additional information on each of the options available.
The proxy function is explained in more detail due to its complexity. There are various conditions regarding the webserver, proxy or container that must be met in order to make SAML work flawlessly due to the URL validations that are performed by both the SP and IdP.
Next open the
IdP>Service Providertab. As explained in the ‘understanding SAML section’ various information needs to be exchanged between the service provider (GLPI) and the identity provider (Entra). The information that needs to be shared with the identity provider is shown in theService Providertab.
Endpoints & Metadata
First make sure that the URLS shown are correct and ‘observable’ for the identity provider (Entra), meaning that these MUST be valid URLs from Entra’s perspective. If the URL isnt correct for instance, it shows an internal IP address, then correct it in GLPIs General configuration (Setup > General > General Setup > Url of the application).
SamlSSO derives the URL from the GLPI configuration, for this reason it cannot be updated via the plugin page.
Certificates & Keys
Secondly replace the default certificate (SP Certificate, SP Private key) with a newly generated x509 self signed certificate.The following microsoft article explains how to.
NEVER USE THE PROVIDED CERTIFICATE. It is used for regression testing and should not be used for production purposes, ever!
Thirdly use ‘Email Adress’ as the NAMEID Format.
After these configurations make sure to reference the ENTITY ID, ACSURL and SLOURL configurations in the next steps. You are strongly advised to use the ‘copy’ feature to copy paste the various values from the SP tab.
Entra admin center
Open the Microsoft Entra admin center page
Create a new ‘enterprise application.’
Next search for the ‘Entra saml toolkit’ and select it.
Name the configuration and click create.
Click Single Sign On in the created Enterprise Application
Select the method option: SAML.
End-points
The first Entra section configures the required end-points. Provide the values from the SP page in the appropriate configuration locations.
The certificate configured in the SP tab should also be uploaded to the ‘Token Encryption’ security option in the Enterprise Application if you want to encrypt the payloads. Its advisable to skip this step till after the basic authentication is configured and operational.
Claim Mapping
The next entra section describes the claims that Entra will add to the samlResponse if authentication was successfull. Make sure you add all the properties that you want to share with GLPI. Depending on your configuration the plugin will create a new user using these properties or will sync and align these properties on each successive login.
Make sure you configure the correct claim keys in the plugin’s Claim Mapping tab. If this is the first time Entra was configured, use the Entra_id preset to pre-populate the claims with the correct claim keys.
As soon as a successful login was performed you will be able to see what claims where ‘observed’ by GLPI and what claims where missing. Additionally added claims that where observed by the plugin will be available for mapping in the ‘Response Claim Key’ field.
If in doubt you can also use the ‘View observed samlResponse XML’ to see the raw xml structure received.
The Username <> NameID field is locked its value is determined by the NameId format.
JIT and Rules
The plugin will try to match the nameId field to an existing user in the GLPI database. The plugin only allows existing users that are ‘enabled and not deleted’ to login to the application. You can enable the Security > JIT User Creation option to automatically create users that don't have an account yet. With JIT disabled, the user must be pre-provisioned using the GLPI interface.
JIT uses the mapping mechanism to provision/target Claim keys directly to a user field or map it to a ‘rules’ property (Administration > Rules > samlsso - JIT import rules) . If a claim is mapped to a rule property you are allowed to perform advanced mappings using the GLPI rules engine during JIT. Only the claims actually mapped to a rule field will be provided to the rules engine.
If the Security > Sync on login is enabled, then the mapping and rules are applied after each successful login. This will update the user properties using the defined mappings and rules based on the changes found in the claims mappings.
(!) Be aware that the rules might be considered an append mechanism that should be used with extreme caution. Especially when you use rules to assign profiles and permissions. Previously added permissions are not deleted by default and might cause data leaks.
Certificate exchange
The next Entra section describes the certificate exchange. GLPI needs the public Entra certificate in order to validate the samlResponse and to decrypt encrypted sections of the SamlResponse.
Download the ‘Certificate Base 64’ certificate
Open the certificate with your favorite editor.
Copy the certificate string and paste it in the
Identity provider>Identity provider certificatesfield. After saving the certificate validate it using the (i). It should read, valid certificate found: Microsoft Azure…
The entra verification certificate (optional) option allows you to configure additional ‘samlRequests’ signing. This requires you to upload the public portion of the self signed certificate from the Service provider tab. This also requires you to configure the outbound security options found in the Security tab.
During initial configuration we advise to NOT configure these options yet and make sure you get authentication flow working first and then harden it as required.
Above is the most default security configuration for Entra if none of the optional security features is configured..
Entra authentication endpoints
The last step shows the correct identity providers endpoints. The URLs provided here should be added to the identity provider tab. These are the locations wher the plugin needs to redirect the userbrower including the samlRequest payloads.
Copy the provided values from Entra and configure them in the correct Identity provider fields. Configure the ‘Required Authn context’ to ‘None’ and configure the AuthN comparison to ‘exact.’
Assign users
Dont forget to add contextual configuration in Entra itself. At this point the ‘saml interface’ should be operational. Still Entra needs to know who is allowed to actually use it. Use the ‘Users and Groups’ option in Entra to finetune the configuration and test it.
Debugging
The plugin performs extensive error logging throughout the loginflow and the various phases. If required use the ?bypass=1 URL parameter to allow administrator login into GLPI using a local account. Then browse to the Setup>samlSSO>IDP used. Open the ‘Logging’ tab.
Find the session that reported the error. Either by searching on IP or the timestamps. Then hover over the ‘trace’ option to view the loginflow for that session. We gone through some lengths to make the errors as descriptive as possible. Where possible the plugin will suggest what configuration option caused the error.
Programmatic errors are logged in the file errorlogs.Administrators can review them by browsing to: Administration > Logs > samlsso-errors, samlssoevents.
(!) Error messages are localized by design. This is not a bug. The messages that are not translated and remain english usually originate from underlying libraries like the phpsaml library.
Proxies
Implementing SAML authentication in proxied environments introduces unique challenges. Below is the essential information required to configure your reverse proxy or load balancer correctly.
URL Mappings and Metadata Mismatch
The samlSSO plugin generates preconfigured metadata endpoints—specifically the Entity ID, Assertion Consumer Service (ACS) URL, and Single Logout (SLO) URL—using GLPI's global settings. These parameters are sent in every SAMLRequest and must match the registered endpoints on your Identity Provider (IdP) exactly. If there is any mismatch, the IdP will reject the request.
In proxied environments, the IdP communicates with the external proxy rather than the internal GLPI server directly. If your internal GLPI instance is configured with an internal hostname or IP address (e.g., http://internal.ip/), GLPI will generate metadata using this internal schema. Because your proxy is forwarding traffic from the public URL (e.g., https://external.address.ext/), the scheme mismatch will break the flow.
CRITICAL RULE: GLPI's "URL of the application" setting must be configured to your external, public-facing URL. The samlSSO plugin intentionally relies on this setting to generate its SAML metadata paths. Keeping this configuration unified forces alignment and prevents external connection failures.
Schema Mappings and TLS Offloading
A common source of errors is TLS offloading on the proxy, where the proxy decrypts HTTPS traffic and forwards plain HTTP internally. Even if GLPI's application URL is configured correctly, PHP will detect a plain HTTP connection. The resulting mismatch between the generated URL (https://...) and the detected connection scheme (http://...) will cause SAML signature and URI validations to fail.
To resolve this issue, you must configure your proxy to send X-Forwarded headers (specifically X-Forwarded-Proto, X-Forwarded-Port, and X-Forwarded-Host) back to GLPI.
Additionally, you must enable the "Requests proxied" setting in the samlSSO configuration. This tells the underlying SAML library to validate incoming URLs using the X-Forwarded headers rather than the default PHP server variables. Enabling this option unlocks a built-in validation tool in the UI to help you verify that these headers are arriving correctly.
Cookies and Session Protection
A common misconception is that the samlSSO plugin uses its own cookies. We do not. The plugin uses a secure database state machine to track authentication flows without cookie dependency.
However, GLPI's core session handler enforces strict cookie security. Because SAML authentication redirects the browser back and forth between GLPI and the IdP, your browser's session cookies can easily be blocked or invalidated if proxy settings are misaligned. This will result in immediate logouts or HTTP 400 Bad Request errors.
The root cause is that PHP cannot automatically detect that it is operating securely behind a TLS-offloaded proxy. If GLPI issues cookies with the cookie.secure flag enabled (which is standard practice), but PHP detects the incoming request as unsecured HTTP, GLPI will flag the returned session cookie as invalid.
To resolve this, you must explicitly tell GLPI that it is operating in a secure context. In containerized or clustered environments, create or edit the file config/local_defined.php and insert the following code block:
Why this is important: The cookie.secure configuration determines the allowed cookie.samesite settings. Although the plugin actively clears request taints, the flow will fail if cookies are not set to SameSite Strict or SameSite Lax. Since SameSite enforcement varies by browser brand, a misconfiguration will result in inconsistent login issues for your users.
For an in-depth technical breakdown of this behavior, review GitHub Issue #120 (https://github.com/DonutsNL/samlsso/issues/120).
Mis à jour