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).

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.

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).

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

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:

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

• “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.

• “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.

The different possibilities can be summarized in the table below:

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.

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 "http://127.0.0.1/webservices/export.php?expression=SELECT%20Contact&format=csv"

Or by using this alternate command line:

wget --no-check-certificate --http-user=admin --http-password=admin2 -O test.csv "https://127.0.0.1/webservices/export.php?expression=SELECT%20Contact&format=csv&login_mode=basic"

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.

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_USER']. 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] 
</IfModule> 

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.

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 the server variable $_SERVER['REMOTE_USER']. 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.

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\']',

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

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

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

Apache configuration file

httpd.conf

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

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.

auth-test.php

<?php 
// 
// Script to test External Authentication 
// 
require_once('../approot.inc.php'); 
require_once(APPROOT.'core/config.class.inc.php'); 
require_once(APPROOT.'application/utils.inc.php'); 
 
echo "<h1>External Authentication: Integration Test Script</h1>"; 
try 
{ 
        $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>"; 
        } 
        else 
        { 
                   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.');'; 
                        eval($sEval); 
                        if ($bVarIsSet) 
                        { 
                                $sEval = '$sAuthUser = '.$sExternalAuthVariable.';'; 
                                eval($sEval); 
                                echo "<p>External Authentication Variable set to: ". 
                                         "'$sAuthUser'</p>\n"; 
                                if ($sAuthUser != '') 
                                { 
                                        echo "<p><b>Ok, integration with external authentication ". 
                                                 "successful !</b></p>\n"; 
                                } 
                                else 
                                { 
                                        echo "<p>Empty user information passed by the web ". 
                                                 "server.</p>\n"; 
                                } 
                        } 
                        else 
                        { 
                                echo "<p>External Authentication Variable <b>NOT</b> set.</p>\n"; 
                        } 
                } 
                else 
                { 
                        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"; 
print_r($_SERVER); 
echo "\$_COOKIE variable:"; 
print_r($_COOKIE); 
echo "</pre>\n"; 
?>

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”:

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

config-itop.php

      '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, 
                                        ), 
        ), 

Where:

• 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)
• '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

    'host' => 'ldap1.mycompany.com ldap2.mycompany.com', 

The last part of the configuration, options defines some LDAP specific options. See http://www.php.net/manual/en/function.ldap-set-option.php 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:

LDAP_OPT_PROTOCOL_VERSION => 3 
LDAP_OPT_REFERRALS => false