> For the complete documentation index, see [llms.txt](https://help.glpi-project.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.glpi-project.org/doc-plugins/fr/plugins-glpi/saml-2.md).
# SAML
### Requirements (on-premise)
| GLPI Version | Minimum PHP | Recommended | Plugin version | State |
| ------------ | ----------- | ----------- | ------------------------------------------------- | ------------------- |
| 10.0.x | 8.1 | 8.2 | [GLPI SAML](https://github.com/DonutsNL/glpisaml) | Deprecated |
| 11.0.x | 8.2 | 8.4 | [SAMLSSO](https://github.com/DonutsNL/samlsso) | Actively maintained |
{% hint style="info" %}
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
{% endhint %}
***
### Download the plugin (on-premise)
From the marketplace (**`Setup`** > **`Plugins`**), download the **SAMLSSO plugin**
Install the 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` > `samlSSO`**
* Either click **`Add`** or 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>Userdomain`** option either blank or default (youruserdomain.tld).
{% hint style="info" %}
*This option does potentially expose client and configuration information to the visiting clients.*
{% endhint %}
Buttonized login
* **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>Userdomain`** option to the correct domainname.
{% hint style="info" %}
*This option does allow you to configure multiple top level domains using a comma separated list i.e. domain1.tld, domain2.tld, etc.*
{% endhint %}
Domain based redirection
{% hint style="info" %}
*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.*
{% endhint %}
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>Enforced`** option 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.
{% hint style="info" %}
*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.*
{% endhint %}
***
## 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.**
{% hint style="info" %}
*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.*
{% endhint %}
{% hint style="info" %}
*For Entra,Google see specific configuration instructions.*
{% endhint %}
***
## Entra ID (Active Directory)
* In GLPI, open the **`IdP`** > **`Transit` tab.**\
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.
{% hint style="success" icon="lightbulb-on" %}
*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.*
{% endhint %}
* Next open the **`IdP`** > **`Service Provider`** tab.\
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 the **`Service Provider`** tab.
### **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)`**.
{% hint style="info" %}
*SamlSSO derives the URL from the GLPI configuration, for this reason it cannot be updated via the plugin page.*
{% endhint %}
### **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](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-self-signed-certificate).
{% hint style="danger" %}
*NEVER USE THE PROVIDED CERTIFICATE. It is used for regression testing and should not be used for production purposes, ever!*
{% endhint %}
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](https://entra.microsoft.com/)
* Create a new ‘enterprise application.’
Add a new Entra application
* Next search for the ‘Entra saml toolkit’ and select it.
Choose SAML Toolkit
* Name the configuration and click create.
Name your app
* Click **Single Sign On** in the created Enterprise Application
* Select the method option: **SAML**.
SAML Method
### **End-points**
The **first Entra section** configures the required end-points. Provide the values from the SP page in the appropriate configuration locations.
Setup GLPI
{% hint style="info" %}
*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.*\
{% endhint %}
### **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.
{% hint style="info" %}
*The Username <> NameID field is locked its value is determined by the NameId format.*
{% endhint %}
### **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.
Add rules
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.
Extract certificate
* 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 certificates`** field. 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`**.
{% hint style="info" %}
*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..
{% endhint %}
### **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., ), GLPI will generate metadata using this internal schema. Because your proxy is forwarding traffic from the public URL (e.g., ), 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:
{% code overflow="wrap" %}
```php
).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.glpi-project.org/doc-plugins/fr/plugins-glpi/saml-2.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.