User Authentication Options

In order to seamlessly integrate with your environment, iTop can use several authentication mechanisms. Some part of the iTop behavior is defined at the web server level, however it is possible to mix the different authentication types on a per user basis.

For example if you already have an LDAP server for authenticating the end-users, it may be convenient to use this LDAP authentication for end-users and local passwords for functional logins (for automation processes and scripts).

Authentication types

In the context of this document, “External authentication” means that the user authentication is performed completely outside of iTop (by the web server or some kind of web server add-on). In this case the iTop application will just be passed the name of the authenticated user, once it has been validated by the web server. This is what happens if you install iTop under Apache in a directory protected with a .htaccess file. “External authentication” is also used for authentication using an external server. In this case the User is “External” but the logon type is not “external”.

When deploying iTop, you have to decide whether the application will use an external authentication mechanism or rely on the iTop internal mechanism. If the application uses “internal” authentication, then several types of authentication may coexist for the same installation (for example you can configure iTop to use the form based dialog and use a mix of LDAP and Internal users).

Different types of user Accounts

If the authentication is not “external”, then iTop will actively participate to this authentication. Currently iTop supports two types of internal authentications:

  • “Local”: based on passwords stored encrypted in the iTop database
  • “LDAP”: by interacting with a remote LDAP or Active Directory server

Login Types (Console and Portal)

In order to authenticate a user, the application has to prompt the user for a login and a password. iTop provides several methods to handle this dialog with the end user:

Login Type Purpose Limitations
form Form based login, best suited for interactive login. Provides also a logout/logoff functionality Not designed for use by batch/scripts or when the web browser is “hidden” from the end-user (i.e. Excel web queries)
basic Basic HTTP authentication. Compatible with all applications supporting this protocol (e.g. wget, Excel web queries) No logoff/logout functionality.
cas Use JA-SIG CAS APIs to connect to a CAS server for authentication Provides transparent single-sign-on with other CAS applications, for example a LifeRay portal
url Compatible with any application. Needed if you want to run web queries in OpenOffice. The password has to be written in clear text in the address of the page !
external Used when the authentication is performed by the web server itself before even accessing the iTop application. iTop does not perform any authentication when an “external” user connects. iTop simply trusts the parameters passed by the web server.

more details

  • “Form based dialog”: this is the default mechanism that displays a formatted dialog to the end-user, as shown on the picture below:

iTop Login Form

  • “Basic Authentication”: this mechanism relies on the Basic Authentication of the HTTP protocol. With most web browsers, this appears as a pop-up to the end user. Command line tools (like wget) can generally use this type of authentication.

Basic Authentication Popup Dialog

  • “CAS”: in this mode iTop delegates the authentication to a CAS compatible server
  • URL”: Some scripts or applications have very limited capabilities for passing authentication credentials. In such a case it is possible to pass directly a login and password as parameters in the URL. Note that due to security considerations, this method is disabled by default, but can be enabled by configuration.
  • “External”: This type of login is used when the authentication has already been performed by the web server and iTop is just passed the name of the authenticated user as server side variable.

Login Types (Web services)

In order to access web services such as the REST API, you will have to provide authentication data within you HTTP request.

Refer to this page if invoking the “web service” from the command-line.

Depending on the current configuration of allowed_login_types, you will have to choose one of the following authentications methods:

Allowed Login Type How to form the HTTP request Example with curl (linux)
basic user and password provided in the HTTP header as per the Basic authentication standard
curl -F param1=xyz... --basic -u $NAME:$PASSWORD
form auth_user and auth_pwd must be POSTed
curl -F param1=xyz... -F auth_user=$USER -F auth_pwd=$PASSWORD 
url auth_user and auth_pwd must be passed in the URL
curl -G -F param1=xyz... -F auth_user=$USER -F auth_pwd=$PASSWORD
In the examples above, $USER and $PASSWORD environmnent variables hold the credentials. Alternatively, you may want to give them in clear on the command-line… at your own risk!

Configuration file

The parameter allowed_login_types in the iTop configuration file determines the behavior of the iTop application by defining which logon methods are enabled, and in which order the application will try them.

This parameter is a text string, in which the values are separated by the pipe ( | ) character. The string is made of a combination of form, basic, url, cas and external in the desired order.

The default mode is the first one in the list. It defines the behavior of the application when no credential is supplied. The first “mode” must be one of form, basic, cas or external.

Also a password policy is set by default and can be customized.

'login_mode' page parameter

When connecting to any iTop web page, it is possible to override the default login mode, by specifying the parameter “login_mode” in the URL.

The value is one of the allowed modes: form, basic, url, cas, external. This login mode will be used (for this connection only, it's not persisted) provided that the corresponding mode is enabled in the configuration file. If the value is not valid, it is ignored and the first “mode” defined in the configuration file is used.

For example if the configuration file contains:

allowed_login_types => 'form|basic|external',

and a page is called with the parameter ?login_mode=basic, then the Basic authentication mechanism will be used for this page.

Now if a page is called with the parameters ?login_mode=url&auth_user=foo&auth_pwd=bar, the url mode being excluded from the configuration, the default mode (in the example above: form) will be used.


For an instance of iTop in which the users are authenticated either by the local password (stored in the iTop database) or by an LDAP server, and using either their web browser (to navigate in the application) or Microsoft Excel to run some reports (as web queries), the following value can be put in the configuration file:

'allowed_login_types' => 'form|basic',

When connecting to the application, end-users will be prompted to enter their login/password using the usual iTop login form. When using the application interactively, the end-user can log off the application using the “log off menu”.

When using Excel, it is possible, by adding &login_mode=basic at the end of the link to the page used for the web query, to have Excel prompt the user for their login/password when the web query is launched for the first time.

In this configuration is it also possible to have scripts retrieving data from iTop using a command line application like wget, with the following syntax:

wget --http-user=<login> --http-password=<password> -O test.csv --auth-no-challenge ""

Or by using this alternate command line:

wget --no-check-certificate --http-user=admin --http-password=admin2 -O test.csv ""

In the first command line, wget will send automatically the credentials to the web server (using the Basic authentication mechanism) and iTop will detect their presence.

In the second case, wget will not send any credentials first, but telling iTop that the preferred way to authenticate is “basic” (i.e. basic authentication), wget will get a response “401 unauthorized” from the web server, and will retry with the supplied credentials.

Basic Authentication and Apache in CGI mode

PHP inside the Apache web server can be configured to run in two different modes: as a module or as a CGI.

When using the basic authentication mechanism, iTop relies on the web server to populate two PHP internal variables: $_SERVER['PHP_AUTH_USER'] and $_SERVER['PHP_AUTH_PW']. When PHP runs as an Apache module, the two variables are automatically populated by the web server when the end-user fills the “basic authentication” pop-up dialog but this is not the case when PHP runs as a CGI.

In this latter case, a simple rewrite rule can be used to pass the authentication information to PHP.

Here is how to do it:

Make sure that the rewrite engine module is activated in Apache, otherwise the “rewrite rule” will be ignored (if you are not sure if the rewrite engine is no, you can comment out the two lines <IfModule mod_rewrite.c> and </IfModule> in the sample below. Then restart Apache. If you seen an error about “RewriteEngine on” not being recognized as a valid configuration directive in the Apache log file, then rewrite engine is not configured on your web server).

Use your favorite test editor to write the following code in a .htaccess file at the root of the iTop web directory (make sure that the user that runs the PHP/CGI process has enough rights to read this file).

<IfModule mod_rewrite.c> 
RewriteEngine on 
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L] 

This causes the Apache server to populate the server variable $_SERVER['HTTP_AUTHORIZATION'] with the credentials (base64 encoded). iTop reads and decodes this variable to extract the login and password.

Integrating with an external authentication

iTop can use an external authentication mechanism (Apache's .htaccess file, CA SiteMinder agent, etc…), however the users' profile is always defined in iTop and for each user allowed to connect to iTop there must be an iTop “External user” record in the database.

When using an external authentication mechanism, any request to the iTop application is intercepted and the end-user is asked to enter her/his authentication before connecting to iTop. In such a case iTop is unaware of the authentication means (login/password, certificate stored on smart card…). The only information that matters to iTop is the “login” (i.e. identifier) of the authenticated user.

iTop uses the standard mechanism for PHP applications by reading by default the $_SERVER['REMOTE_USER'] server variable . If an “External user” record with the corresponding login is found in the iTop database, this user will become connected to iTop. If no match is found, the next authentication mechanism will be used and the user will prompted to authenticate with iTop.

Depending on the external authentication mechanism used, the web server may place the authentication information in different variables, therefore the variable used to retrieve this “external authentication” can be specified in the iTop configuration file. Look for the parameter:
'ext_auth_variable' => '$_SERVER[\'REMOTE_USER\']',

For example if your single-sign-on system uses the cookie variable auth_user to pass the user name, you can use something like:

'ext_auth_variable' => '$_COOKIE[\'auth_user\']',

If your system is using http headers you can as well use the PHP function getallheaders() that return an array of each headers variables.

'ext_auth_variable' => 'getallheaders()[\'SSL_DN_CERTIFICATE\']',
In order to ensure that the external authentication is used first (preventing iTop from prompting the already authenticated user a second time), make sure that in the iTop configuration file, the order for allowed_login_types specifies “external” as the first login mode, as shown below:
'allowed_login_types' => 'external|form|basic',

Since the authentication is entirely delegated, iTop cannot offers a logout mechanism.
For user which were authenticated using the external method, the logout menu entry is hidden. Beware that the iTop session cookie will remain until the browser window is closed !

Single Sign-On on Windows

Since iTop uses the PHP variable $_SERVER['REMOTE_USER'] to identify external users, this becomes really simple if your web server is running on Windows. Using IIS you can rely on the Integrated Windows Authentication and if using Apache you can use the sspi_auth_module. Both will set the variable $_SERVER['REMOTE_USER'] to the authenticated user as “DOMAIN\USERNAME”. Simply create your External users names the same way: DOMAIN\USERNAME and the iTop authentication will be transparent to your end users.

Sample configuration for external authentication using Apache .htpasswd

In the sample below the users are authenticated by a .htpasswd file stored in /var/www/.

You can use the following command to generate login and password for a corresponding <user>

htpasswd -c /var/www/.htpasswd <user>

Then before activating the external authentication, you have to create at least one External user corresponding to a user defined in the .htpasswd file withe the profile “Administrator”.

This is very important as the local authentication in iTop will be deactivated automatically by the apache server.

Then to activate External authentication in iTop you have to set the external option to be the first one in the iTop configuration file.

iTop configuration

$MySettings = array( 
        'allowed_login_types' => 'external|form|basic', 

Once done, you just have to change the configuration of your Apache web server as follow:

Apache configuration file

<Directory /var/www/> 
        AuthUserFile /var/www/.htpasswd 
        AuthName "Please identify yourself..." 
        AuthType Basic 
        require valid-user 

Integration Test script

If you use a third party authentication mechanism, you can place the following PHP script in a file in the /pages directory of iTop. Then point your web browser to it to test if your external authentication passes the appropriate information to iTop.

// Script to test External Authentication 
echo "<h1>External Authentication: Integration Test Script</h1>"; 
        $aAllowedLoginTypes = utils::GetConfig()->GetAllowedLoginTypes(); 
        $sAllowedLoginTypes = implode('|', $aAllowedLoginTypes); 
        echo "<p>allowed_login_types set to '$sAllowedLoginTypes'</p>\n"; 
        if (!in_array('external', $aAllowedLoginTypes)) 
                    echo "<p>Check your iTop configuration file, ". 
                           "<b>allowed_login_type</b> does not enable ". 
                           "'external' authentication.</p>"; 
                   echo "<p>Ok, external authentication is enabled by allowed_login_type.</p>"; 
                $sExternalAuthVariable = utils::GetConfig()->GetExternalAuthenticationVariable(); 
                echo "<p>External Authentication Variable: '$sExternalAuthVariable'</p>\n"; 
                if ($sExternalAuthVariable != '') 
                        $sEval = '$bVarIsSet = isset('.$sExternalAuthVariable.');'; 
                        if ($bVarIsSet) 
                                $sEval = '$sAuthUser = '.$sExternalAuthVariable.';'; 
                                echo "<p>External Authentication Variable set to: ". 
                                if ($sAuthUser != '') 
                                        echo "<p><b>Ok, integration with external authentication ". 
                                                 "successful !</b></p>\n"; 
                                        echo "<p>Empty user information passed by the web ". 
                                echo "<p>External Authentication Variable <b>NOT</b> set.</p>\n"; 
                        echo "<p>Check your iTop configuration file, <b>ext_auth_var</b> is set ". 
                                 "to an empty string.</p>\n"; 
catch(ConfigException $e) 
        echo "<p>iTop configuration file not found. Did you already install iTop ?</p>\n"; 
echo "<hr/>\n"; 
echo "<p>For information:</p>"; 
echo "<pre>\$_SERVER variable:\n"; 
echo "\$_COOKIE variable:"; 
echo "\getallheaders() array of headers:"; 
echo "</pre>\n"; 

This script will return the Server variables as follow:

This will help you to identify the variable that define the authenticated user. It has to return the same value as the login stored in .htpasswd file and the login of the corresponding iTop External user

Using such configuration, you cannot use the form mode use by iTop by default. The whole authentication is managed by Apache.

Thus you may encounter difficulties to handle web services calls, but the command line scripts work (cron.php or synchro_import.php)

Configuration of LDAP authentication

iTop supports LDAP authentication against a remote LDAP server (or Windows Active Directory server). Both types of users (users with an account stored in the iTop local database and users with an LDAP account) can coexist on the same instance of iTop, on a per user basis.

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

New LDAP User

Configure iTop to connect to your LDAP server

Once iTop is installed, open the file 'config-itop.php' and look for the section authent-ldap . It should looks as shown below:

      'authent-ldap' => array ( 
               'host' => 'localhost', 
                'port' => 389, 
                'default_user' => '', 
                'default_pwd' => '', 
                'base_dn' => 'dc=mycompany,dc=com', 
                'user_query' => '(&(uid=%1$s))', 
                'options' => array ( 
                        17 => 3, 
                        8 => 0, 
                'debug' => false,
                'servers' => array(
                    'MySecond-LDAP-Server' => array(
                        'host' => 'server1',
                        'port' => 389,
                        'default_user' => '',
                        'default_pwd' => '',
                        'base_dn' => 'dc=mycompany,dc=com',
                        'user_query' => '(&(uid=%1$s))',
                        'options' => array (
                                17 => 3,
                                8 => 0,
                        'debug' => false,


  • The host parameter must contain the IP address or host name of your LDAP server
  • The port parameter is the TCP port number to be used for connecting to LDAP (LDAP's default is 389)
If you specify both a host and a port but no protocol, then PHP will try to connect without SSL (i.e. the default protocol is ldap://)

If you specify a protocol in the host parameter, then the value of the port is ignored by PHP (i.e. ldap:// implies port 389 and ldaps:// implies port 636).

In order to connect via LDAPS using a non-standard port, you must specify both the protocol and the port in the host and pass null for the port.


  'authent-ldap' => array ( 
               'host' => 'ldaps://', 
               'port' => null,

Refer to ldap_connect for more information.

  • default_user and default_pwd identify an LDAP account with enough rights to connect to your LDAP server (in read-only mode) in order to search for the specified user. On most systems an anonymous user can do this, so you can leave these two fields blank.
  • base_dn defines the “root” used for searching for the user/logins. It can be something like “dc=mycompany,dc=com” or “ou=People,dc=mycompany,dc=com”. If you're not sure, ask your LDAP administrator.
  • user_query defines a LDAP query that will be used for searching for the users. You can write whatever valid LDAP query using any of the following placeholders:
    • %1$s : iTop login of the user (i.e. what he/she types in the login form)
    • %2$s : User's First Name
    • %3$s : User's last name
    • %4$s : User's email
  • debug must be set to true to turn on debug traces output (in the file log/error.log). Since the debug traces contain passwords in clear text, it is recommended to turn them off in production, but they are useful to troubleshoot the behavior of the application during configuration phases.
  • servers : Array of server configuration identical to the default one. The name of the server is the name referenced in the LDAP User definition. (if empty, then the default configuration is used).

} <note tip> The ''host'' parameter can contain a list of LDAP servers separated by a space. If the first server in the list fails to respond, the code will try the second one, and so on. <code> 'host' => 'ldap:// ldap://', </code> </note> <note tip> When connecting to a Windows Active Directory the query to retrieve the user based on her/his Windows login looks like: '(samaccountname=%1$s) ' </note> <note warning> The parameters %2$s, %3$s and %4$s are non-empty only if the User record (in iTop) is associated with a Person (i.e. if the “Contact” field is not empty for this User). </note> The last part of the configuration, ''options'' defines some LDAP specific options. See for the full list of possible options. You can use either the PHP constants (like LDAP_OPT_PROTOCOL_VERSION - with no quote) or their numeric equivalent (i.e. LDAP_OPT_PROTOCOL_VERSION equals 17). In the example above: <code> LDAP_OPT_PROTOCOL_VERSION => 3 LDAP_OPT_REFERRALS => false </code> <note tip> If you get an error 'Cannot bind to LDAP server, invalid DN syntax', check the syntax of the 'default_user' in your iTop configuration file. For some LDAP servers, the user name must be a complete name like: 'cn=admin,dc=mycompany,dc=com' and not just 'admin'. </note> ===== Configuration of CAS authentication ===== iTop Supports CAS authentication against an external CAS server. CAS users are created by selecting the **External user** type when prompted for a “New user Account”: {{ :3_2_0:admin:user-creation.png |

Configure iTop to connect to your CAS server

Install Central Authentication Service on your iTop server to be able to connect to a CAS server.

Once iTop is installed, open the file 'config-itop.php' and add cas to the allowed_login_types:

//'cas' first, means login will be automatically redirected to CAS
allowed_login_types => 'cas|form|basic|external',

The configuration is located in the general iTop parameter.

New in 2.7.0: the configuration has moved to the section authent-cas. For compatibility reasons, the configuration of the previous versions (in iTop's parameters) is supported.

It should looks as shown below:

      'authent-cas' => array ( 
                'cas_debug' => false,
                'cas_host' => '',
                'cas_port' => '',
                'cas_context' => '',
                'cas_version' => '',
                'service_base_url' => '',

All the possible parameters are:

Parameter Type Visible ? Description Default Value
cas_context string No The CAS context
cas_debug bool No Activate the CAS debug false
cas_default_profiles string No A semi-colon separated list of iTop Profiles to use when creating a new user if no profile is retrieved from CAS Portal user
cas_host string No The name of the CAS host
cas_logout_redirect_service string No The redirect service (URL) to use when logging-out with CAS
cas_memberof string No A semicolon separated list of group names that the user must be member of (works only with SAML - e.g. cas_version⇒ “S1”)
cas_memberof_attribute_name string No New in 2.7.0: The name of the attribute memberOf on the CAS server memberOf
cas_port integer No The port used by the CAS server 443
cas_profile_pattern string No A regular expression pattern to extract the name of the iTop profile from the name of an LDAP/CAS group /^cn=([^,]+),/
cas_server_ca_cert_path string No The path where to find the certificate of the CA for validating the certificate of the CAS server
cas_update_profiles bool No Whether or not to update the profiles of an existing user from the CAS information false
cas_user_synchro bool No Whether or not to synchronize users with CAS/LDAP false
cas_version string No The CAS protocol version to use: “1.0” (CAS v1), “2.0” (CAS v2) or “S1” (SAML V1) ) 2.0
service_base_url string No The iTop server URL New in iTop 2.7.8 and after 3.0.2

Example of a working configuration:

      'authent-cas' => array (
                'cas_context' => '/cas',
                'cas_debug' => true,
                'cas_host' => '',
                'cas_memberof' => 'Configuration Manager',
                'cas_memberof_attribute_name' => 'businessCategory',
                'cas_port' => 8443,
                'cas_version' => 'S1',
                'cas_user_synchro' => true,
                'service_base_url' => '',
latest/admin/user_authentication_options.txt · Last modified: 2024/06/20 17:28 (external edit)
Back to top
Contact us