Sidebar

Combodo

iTop Extensions

Authentication with SSO SAML

name:
Combodo-saml
description:
SSO SAML connector for iTop authentication
version:
1.1.4
release:
2023-07-13
itop-version-min:
2.7.0
code:
combodo-saml
state:
Stable
diffusion:
Client Store, iTop Hub
php-version-max:
PHP 8.1

A small extension to add the SAML SSO to iTop. The extension embeds the onelogin/php-saml library and can be deployed as any other iTop extension.

Features

The extension extends the login page and provides 2 extra pages: acs.php (Assertion Consumer Service, the return page after a successful login by SAML) and sls.php (Single Logout Service, the return page after a successful logout by SAML).

The login can be either transparently redicted to the SAML IdP server or co-exist with the traditional login/password form, as shown below:

 iTop Login page with SAML

This extension had been tested with the following Identity Providers:

  • Keycloak
  • Sign and Go
  • Simple SAML
  • ADFS Windows
  • Azure AD
  • Okta
The SAML/SSO authentication method is not compatible with Microsoft Excel Web Query feature. Since Excel supports only the basic authentication mode. To have the basic authentication working in parallel to SAML/SSO authentication, you need either a local or LDAP iTop user account.

Revision History

Date Version Description
2023-07-13 1.1.4 * N°6506 - Remove tests folder from builds
2023-07-05 1.1.3 * N°6358 - Fix CSRF security issue
2022-10-25 1.1.2 * N°5635 - Add compatibility with PHP 8.0 & 8.1
* N°5635 - Fix missing use statement
2022-04-19 1.1.1 Fix issue N°5096 - SAML configuration menu restricted to administrators
2021-08-06 1.1.0 Add compatibility with iTop 3.0
2021-05-18 1.0.7 Fix compatibility issues with iTop before 2.7.4
2021-03-08 1.0.6 fix SAML login when using reverse proxy
2021-01-28 1.0.5 - Improved debug log.
- new parameter can_logoff to enable the “Logoff menu” (disabled by default)
2020-11-27 1.0.4 Resolve problems with logout requests for Microsoft Azure (ADSF) identity providers by sending the nameId into the logout request.
2020-11-19 1.0.3 - Improved logging to log/saml.log (when debug ⇒ true)
- Better compatiblity with some SAML IdP for the logout (retrieveParametersFromServer ⇒ true by default)
- Configurable SAML icon in the login form (via the parameter saml_logo_url)
- Better generation of the SP MetaData (taking care of pre-filling all expected values)
2020-10-09 1.0.2 Enhanced configuration wizard and better meta data generation.
2020-07-10 1.0.0 First version

Limitations

The user provisioning (i.e. creation of the user accounts in iTop) is handled not by this extension. The current version of the extension only enables the authentication of existing iTop user accounts by a SAML IdP.

Requirements

  • A SAML Identity Provider (IdP) server configured to be accessible from iTop.
  • iTop accounts of the class ExternalUser corresponding to the SAML users.
  • if You use itop data collector for ldap, you need the latest version 1.2.4 if SAML is the default authentication

Configuration

Configure iTop to connect to your SAML server

You can use the menu “SAML Configuration” to generate the configuration for iTop as a SAML Service Provider and to import the metadata of your Identity Provider into iTop.

To configure iTop as a Service Provider (SP) follow these steps (in this order):

  1. Import the XML meta data of your Identity Provider into iTop using the first form of the configuration wizard.
  2. Select the appropriate attribute to get the login from your IdP and generate a pair of private key and certificate, then save the Service Provider configuration using the second form of the configuration wizard.
  3. Export the XML meta data to your IdP using the link at the bottom of the page.

SAML configuration form

When you import the metadata from the Identity Provider into iTop, the iTop configuration file is updated to include SAML in the allowed_login_types. By default saml is added after form in the list of allowed login types, meaning that the traditional login/password authentication mode remains available.

'allowed_login_types' => 'form|saml|basic|external',

If you move saml to be the first login type, this means that the login will be automatically redirected to SAML.

'allowed_login_types' => 'saml|form|basic|external',

In that case to access iTop pages with an internal user, you have to add the parameter login_mode=form in the URL. This can be useful to connect to iTop webservices, exports, etc…

For instance <itop_url>/pages/UI.php?login_mode=form

You can use the SAML online tools to generate a private key/certificate pair for testing.

Once the configuration is complete, it is located in the section combodo-saml of the iTop configuration file.

It should looks as shown below:

config-itop.php
'combodo-saml' => array (
    'strict' => true,
    'debug' => false,
    'retrieveParametersFromServer' => true,
    'idp' => array (
      'entityId' => '',
      'singleSignOnService' =>
      array (
        'url' => '',
        'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
      ),
      'singleLogoutService' =>
      array (
        'url' => '',
        'responseUrl' => '',
        'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
      ),
      'nameid' => 'uid',
      'sp' => array(
          'entityId' => 'https://....',
          'privatekey' => '.....',
          'x509cert' => '.....',
      ),
      'security' => array(
          'wantMessagesSigned' => false,
          'wantAssertionsSigned' => true,
          'authnRequestsSigned' => true,
          'logoutRequestSigned' => true,
          'logoutResponseSigned' => true,
      ),
    ),
In order to troubleshoot the SAML configuration process, you check the debug checkbox (or set 'debug' => true, in the configuration file). When the debug mode is enabled, more debug information is logged into the file saml.log in the log directory of iTop for each attemp to log in or log out. Do not turn on this setting in production since the log file is neither trimmed nor rotated and may potentially become huge.

All the possible parameters are:

Parameter Type Visible ? Description Default Value
cacheDuration number no The attribute “cacheDuration” in the XML meta data of the SP. As a number of days. 7
can_logoff bool no Whether or not to display the “Logoff” menu in iTop to let users log off from the SAML server (and thus disconnect from all their SSO applications).
Since 1.2.0 User will be logged off the SAML server only if the idp→singleLogoutService is provided. See Questions & Answers below for more information.
false
contactPerson array no To populate the contact information in the meta data for the IdP. Check OneLogin SAML settings for more information.
debug bool yes Activate the SAML debug. The debug output goes to the log file log/saml.log false
idp array yes Identity Provider Data that we want connected with our SP
nameid string yes The name of the attribute (in the IdP response) that contains the login/identifier uid
organization array no To populate the organization information in the meta data for the IdP. Check OneLogin SAML settings for more information.
saml_logo_url string no The URL to the SAML logo displayed on the login page of iTop. If not present the default SAML logo wil be displayed. Specify an empty string to remove the logo from the form.
security array yes Some security configuration flags. If you change any value in this array, refresh the configuration of the IdP with updated meta data. Check OneLogin SAML settings for more information.
sp array yes The configuration of iTop as a Service Provider. Check OneLogin SAML settings for more information.
strict bool yes If 'strict' is True, then the PHP Toolkit will reject unsigned or unencrypted messages if it expects them to be signed or encrypted. Also it will reject the messages if the SAML standard is not strictly followed: Destination, NameId, Conditions … are validated too. true
retrieveParametersFromServer bool no Try to change this value if an error di displayed when processing the Logout Response… See this page for more information.
validUntil number no The attribute “validUntil” in the XML meta data of the SP. As a number of days relative to the time at which the meta data are generated. 2
The configuration wizard should generate a minimal (and consistent) configuration. You can still manually edit the generated configuration to fine tune the many possible parameters (security settings, contact information…). Just make sure that you refresh the IdP with updated meta data in order to keep the configuration of both the SP and IdP consistent.

Commented version of the configuration:

config-itop.php
'combodo-saml' => array (
    // If 'strict' is True, then the PHP Toolkit will reject unsigned
    // or unencrypted messages if it expects them to be signed or encrypted.
    // Also it will reject the messages if the SAML standard is not strictly
    // followed: Destination, NameId, Conditions ... are validated too.
    'strict' => true,
    // Enable debug mode (to print errors).
    'debug' => false,
    // Service Provider Data that we are deploying.
    // Identity Provider Data that we want connected with our SP.
    'idp' => array (
        // Identifier of the IdP entity  (must be a URI)
        'entityId' => '',
        // SSO endpoint info of the IdP. (Authentication Request protocol)
        'singleSignOnService' => array (
            // URL Target of the IdP where the Authentication Request Message
            // will be sent.
            'url' => '',
            // SAML protocol binding to be used when returning the <Response>
            // message. OneLogin Toolkit supports the HTTP-Redirect binding
            // only for this endpoint.
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
        ),
        // SLO endpoint info of the IdP.
        'singleLogoutService' => array (
            // URL Location of the IdP where SLO Request will be sent.
            'url' => '',
            // URL location of the IdP where the SP will send the SLO Response (ResponseLocation)
            // if not set, url for the SLO Request will be used
            'responseUrl' => '',
            // SAML protocol binding to be used when returning the <Response>
            // message. OneLogin Toolkit supports the HTTP-Redirect binding
            // only for this endpoint.
            'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
        ),
        // Public x509 certificate of the IdP
        'x509cert' => '',
        /*
         *  Instead of use the whole x509cert you can use a fingerprint in order to
         *  validate a SAMLResponse, but we don't recommend to use that
         *  method on production since is exploitable by a collision attack.
         *  (openssl x509 -noout -fingerprint -in "idp.crt" to generate it,
         *   or add for example the -sha256 , -sha384 or -sha512 parameter)
         *
         *  If a fingerprint is provided, then the certFingerprintAlgorithm is required in order to
         *  let the toolkit know which algorithm was used. Possible values: sha1, sha256, sha384 or sha512
         *  'sha1' is the default value.
         *
         *  Notice that if you want to validate any SAML Message sent by the HTTP-Redirect binding, you
         *  will need to provide the whole x509cert.
         */
        // 'certFingerprint' => '',
        // 'certFingerprintAlgorithm' => 'sha1',
 
        /* In some scenarios the IdP uses different certificates for
         * signing/encryption, or is under key rollover phase and
         * more than one certificate is published on IdP metadata.
         * In order to handle that the toolkit offers that parameter.
         * (when used, 'x509cert' and 'certFingerprint' values are
         * ignored).
         */
        // 'x509certMulti' => array(
        //      'signing' => array(
        //          0 => '<cert1-string>',
        //      ),
        //      'encryption' => array(
        //          0 => '<cert2-string>',
        //      )
        // ),
    ),
),

Usage

SAML users are created by selecting the External user type when prompted for a “New user Account”:

Those users can be provision using data import or data synchronization

Question and Answer

Q: How to configure SAML with Windows authentication?
A:
To configure iTop single sign on with SAML and Windows authentication you have to execute the following configuration:

  1. On your windows ADFS server, you have to choose the option “Integrated windows authentication” in addition to “Forms authentication”
  2. On the iTop server you have to add the following configuration parameter requestedAuthnContext in the configuration section iTop SAML. For instance:
Configuration
'combodo-saml' => array (
   ...
   'security' => array (
     'wantMessagesSigned' => false,
     'wantAssertionsSigned' => true,
     'authnRequestsSigned' => true,
     'logoutRequestsSigned' => true,
     'logoutResponseSigned' => false,
     'requestedAuthnContext' =>
     array (
        0 => 'urn:federation:authentication:windows',
     ),
   ),
),

Q: What happens if I set the conf. parameter can_logoff to true?
A:
It all depends on the combinaison of both can_logoff and idp parameters.

can_logoff idp→singleLogoutService Result
✔️/❌ User can't logoff from iTop nor SAML server
✔️ From 1.1.5 User will log off from iTop but will remain connected on the SAML server
✔️ ✔️ User will log off from both iTop and the SAML server

Note that the 2nd use case can be helpful if you want to log off from iTop in order to reconnect as another user, but remain connected to the SAML server for other applications.

Troubleshooting

To understand the error codes, ahve a look at the reference documentation of the SAML protocol. Here is a version in the Microsoft Documentation

OneLogin provide a series of helpful SAML online tools here.

extensions/combodo-saml.txt · Last modified: 2024/03/21 10:14 (external edit)
Back to top
Contact us