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
Logon Types
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:
Logon Type | Purpose | Limitations |
---|---|---|
form | Form based logon, best suited for interactive logon. 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:
-
“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.
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
.
'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.
Example
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.
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_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.
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 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',
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
In the sample below the users are authenticated by a
.htpasswd
file stored in /var/www/
.
iTop configuration
$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>
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.
- 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'); require_once(APPROOT.'application/startup.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"; ?>
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”:
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:
- 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, ), 'debug' => false, ),
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
anddefault_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 totrue
to turn on debug traces output (in the filelog/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.
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.
'host' => 'ldap://ldap1.mycompany.com ldap://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
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”:
Configure iTop to connect to your CAS server
Once iTop is installed, open the file 'config-itop.php' and add
cas to the allowed_login_types
:
- config-itop.php
-
//'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.
authent-cas
.
For compatibility reasons, the configuration of the previous
versions (in iTop's parameters) is supported.It should looks as shown below:
- config-itop.php
-
'authent-cas' => array ( 'cas_debug' => false, 'cas_host' => '', 'cas_port' => '', 'cas_context' => '', 'cas_version' => '', ),
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 |
Example of a working configuration:
- config-itop.php
-
'authent-cas' => array ( 'cas_context' => '/cas', 'cas_debug' => true, 'cas_host' => 'cas-server.combodo.net', 'cas_memberof' => 'Configuration Manager', 'cas_memberof_attribute_name' => 'businessCategory', 'cas_port' => 8443, 'cas_version' => 'S1', 'cas_user_synchro' => true, ),