Authentication

Overview

The authentication mechanism Observium uses is configured via a parameter in config.php

$config['auth_mechanism'] = "mysql";

Currently supported mechanisms are mysql, ldap, ad, radius and http-auth. If you want to change the authentication mechanism, you have to change this setting!

If the system you are using is not supported and you want to develop your own, see Developing Authentication Modules for developer information.

Debugging

Enabling Debugging

By default debugging is disabled before the user is logged in to prevent exposing data. This can make diagnosing authentication problems difficult. You can enable debugging output during login by adding the following to config.php

$config['web_debug_unprivileged'] = TRUE;

Debugging will then be enabled if you add /debug/ to the end of the URL.

MySQL Authentication

Introduction

This is the default authentication mechanism, using users internal to Observium, with their separately maintained passwords.

Configuration

No configuration is necessary; the MySQL database settings are configured for Observium already, add users via the CLI scripts or the web interface.

Apache REMOTE_USER Authentication

Introduction

This authentication module takes a server variable, by default REMOTE_USER used by Apache. It doesn't require users to be in MySQL and will give all authenticated users the configured userlevel.

Configuration

First configure observium for the remote mechanism.

$config['auth_mechanism'] = "remote";

It takes various config options

• auth_remote_variable - what server variable to use (defaults to REMOTE_USER).
• auth_remote_userlevel - what user level to give to remotely authenticated users. All users are automatically given this privilege level.
• auth_remote_logout_url - what URL to redirect the user to in order to perform a logout. Because even if we clear our session variable, the user will just get logged back in on the next pageview. If this variable is not set, the logout button is not available.

LDAP Authentication

Introduction

The LDAP module supports various LDAP configurations. By setting this up correctly, you can authenticate your users through your centralized user directory. User creation or password changes are not possible with this module. With the correct configuration (see below) you can use Kerberos SSO through this module as well.

This module requires the php LDAP module to be installed and enabled.

Configuration

 $config['auth_ldap_version'] = 3; # v2 or v3
 $config['auth_ldap_server']  = "ldap.yourserver.com";
 $config['auth_ldap_port']    = 389;

LDAP server configuration.

 $config['auth_ldap_starttls'] = FALSE;

LDAP TLS setting, set to "optional" if you want to enable TLS but don't want to depend on it being supported. Set to "require" if you want to ensure that your LDAP connection supports TLS.

 $config['auth_ldap_prefix'] = "uid=";
 $config['auth_ldap_suffix'] = ",ou=People,dc=example,dc=com";

How users are identified in your LDAP server, prefix+username+suffix will form the complete user DN.

 $config['auth_ldap_group']  = array("cn=observium,ou=groups,dc=example,dc=com");

Required group to be able to access Observium. Multiple groups are possible. Unset if you don't want to use this feature.

 $config['auth_ldap_groupbase'] = "ou=groups,dc=example,dc=com";

The LDAP base DN for your groups.

 $config['auth_ldap_binddn'] = ""; // Initial LDAP bind dn and password, leave empty for bind with user's dn
 $config['auth_ldap_bindpw'] = "";
 $config['auth_ldap_bindanonymous'] = FALSE;

If your LDAP server does not allow anonymous binding, set up DN and password here, so we can search for the user's dn for authentication.

If your user's DN is comprised of prefix+username+suffix, you can disable anonymous bind, and Observium will connect to LDAP using the user's specified credentials.

 $config['auth_ldap_attr']['uid'] = "uid";             // LDAP attribute containing the user login name
 $config['auth_ldap_attr']['uidNumber'] = "uidNumber"; // LDAP attribute containing the numeric user ID
 $config['auth_ldap_attr']['cn'] = "cn";               // LDAP attribute containing the user's full name
 $config['auth_ldap_attr']['dn'] = "dn";               // LDAP attribute containing the user's DN
 $config['auth_ldap_groupmemberattr'] = "memberUid";   // Use your unique attribute for username, example "uniqueMember"

Attribute mapping, defaults are for a regular OpenLDAP setup.

 $config['auth_ldap_objectclass'] = "posixAccount";    // objectClass to filter out valid users, use * for all objects under ldap_suffix tree

LDAP Object Class which your users are in, used to list the users to be able to give them permissions.

 $config['auth_ldap_groupmembertype'] = "nodn";        // Available membertypes: 'nodn' (default, uses $username);
                                                       // 'fulldn' ($config['auth_ldap_prefix'] . $username . $config['auth_ldap_suffix'])

If your LDAP group memberships use the user's full DN (CN=Joe,OU=People,DC=example,DC=com) instead of just their username (joe), set this to fulldn.

 $config['auth_ldap_groups']['CN=admin,OU=Groups,DC=example,DC=COM']['level'] = 10;
 $config['auth_ldap_groups']['CN=pfy,OU=Youth,OU=Groups,DC=example,DC=COM']['level'] = 7;
 $config['auth_ldap_groups']['support']['level'] = 1;

Configure the user levels people get when they are in a certain LDAP group. Spaces are allowed. Using the group's name instead of the full DN is possible, as long as this group is directly within your groupbase configured above.

 $config['auth_ldap_recursive'] = TRUE;                // Active Directory recursive lookup for nested groups

Support recursive lookups for groups. You can disable this if you don't want it, or don't use it, as this will add extra load to your LDAP/AD server.

 $config['auth_ldap_recursive_maxdepth'] = 3;          // Max depth for recursive lookup

Maximum amount of nested groups to go through before giving up.

 $config['auth']['remote_user'] = FALSE; // Trust Apache server to authenticate user, READ DOCUMENTATION FIRST!!

Using this setting in combination with a bit of Apache configuration, you can automatically log in to Observium from browsers supporting the GSSAPI Negotiate function (ie a Windows machine in your AD Domain or a Linux machine signed in to your Kerberos infrastructure). This replaces the log in part, required LDAP group memberships for access and user level are still checked. As we don't receive the password from the user, an LDAP bind DN must be configured.

Examples

OpenLDAP

 $config['auth_ldap_server'] = "ldap.example.com";
 $config['auth_ldap_port'] = 389;
 $config['auth_ldap_suffix'] = ",ou=People,dc=example,dc=com";
 $config['auth_ldap_prefix'] = "uid=";
 $config['auth_ldap_group']  = array("cn=observium,ou=Group,dc=example,dc=com");
 $config['auth_ldap_groupbase'] = "ou=Group,dc=example,dc=com";
 $config['auth_ldap_groups']['admin']['level'] = 10;
 $config['auth_ldap_groups']['nagios']['level'] = 7;

Active Directory (AD) Authentication

Introduction

The AD module supports Microsoft's Active Directory. By setting this up correctly, you can authenticate your users through your centralized user directory. User creation or password changes are not possible with this module. With the correct configuration (see below) you can use Kerberos SSO through this module as well.

This module requires the php LDAP module to be installed and enabled.

Configuration

 $config['auth_ad_domain']  = "contoso.com";

Active Directory domain name (in FQDN format).

 $config['auth_ad_basedn'] = "DC=contoso,DC=com";

The LDAP base DN for your directory. Optional, if you have set your domain FQDN (auth_ad_domain).

 $config['auth_ad_server']  = "dc1.contoso.com";
 $config['auth_ad_port']    = 389;

AD domain controller configuration. Multiple hostnames are supported, which are tried in order. Leaving the server list empty (unset) will use SRV records to retrieve the DCs for the domain, if the domain name (in FQDN format) was set.

 $config['auth_ad_tls'] = FALSE;

TLS setting, set this when using LDAPS (usually on port 636) rather than STARTTLS which starts out in plain text (usually on port 389).

 $config['auth_ad_starttls'] = 'no';

STARTTLS setting, set to optional if you want to enable TLS but don't want to depend on it being supported. Set to require if you want to ensure that your domain controller supports TLS. Set to no if not using TLS. This setting is ignored if you have set auth_ad_tls to TRUE.

 $config['auth_ad_validatecert'] = TRUE;

By default, Observium validates the TLS certificate presented by the domain controller (either via direct TLS or via STARTTLS). Disable if you do not have trusted certificates.

 $config['auth_ad_group']  = array("CN=Observium Users,OU=groups,DC=contoso,DC=com");

Required group membership to be able to access Observium. Multiple groups are possible. Unset if you don't want to use this feature. You can specify either the DN (CN=...) or the actual group name ("Observium users"). If this parameter is unset, Observium will filter on the auth_ad_groups configured below, if any.

 $config['auth_ad_binddn'] = ""; // Initial LDAP bind dn and password
 $config['auth_ad_bindpw'] = "";

Set up an AD user's DN or UPN and password here, so we can bind to the domain controller. We cannot only bind using the user's credentials as the user's password is not available to us on anything but the logon form.

 $config['auth_ad_groups']['CN=admin,OU=Groups,DC=contoso,DC=COM']['level'] = 10;
 $config['auth_ad_groups']['CN=pfy,OU=Youth,OU=Groups,DC=contoso,DC=COM']['level'] = 7;
 $config['auth_ad_groups']['Support Engineers']['level'] = 1;

Configure the user levels people get when they are member of a certain AD group. Spaces are allowed. You can specify either the DN (CN=...) or the actual group name ("Observium users").

 $config['auth']['remote_user'] = FALSE; // Trust Apache server to authenticate user, READ DOCUMENTATION FIRST!!

Using this setting in combination with a bit of Apache configuration, you can automatically log in to Observium from browsers supporting the GSSAPI Negotiate function (ie a Windows machine in your AD Domain or a Linux machine signed in to your Kerberos infrastructure). This replaces the log in part only, required AD group memberships for access and user level are still checked.

Examples

 $config['auth_ad_domain'] = "contoso.com";

 $config['auth_ad_binddn'] = "LookupUser@contoso.com";
 $config['auth_ad_bindpw'] = "topsecret123";

 $config['auth_ad_server'] = "dc1.contoso.com";
 $config['auth_ad_port']   = 389;
 $config['auth_ad_starttls'] = "require";

 unset($config['auth_ad_group']);

 unset($config['auth_ad_groups']);
 $config['auth_ad_groups']['CN=Observium Admins,OU=Groups,DC=contoso,DC=com']['level'] = 10;
 $config['auth_ad_groups']['CN=Observium Users,OU=Groups,DC=contoso,DC=com']['level'] = 1;  

This will connect to dc1.contoso.com using STARTTLS, binding with the LookupUser. 2 groups are defined, giving user in them access levels 10 and 1 respectively. Users outside of these groups do not have access.

Active Directory with SSO

Same configuration as above, plus the following:

 $config['auth']['remote_user'] = TRUE;

This will make Observium trust your Apache server to do the correct authentication and not request username/password from your LDAP server anymore.

Then set up your Apache server to do Kerberos authentication against your AD, using mod_auth_kerb with configuration similar to the following:

 AuthName "Observium"
 AuthType Kerberos 
 KrbMethodNegotiate on
 KrbMethodK5Passwd on 
 Krb5Keytab /etc/apache2/keytab/http.observium.contoso.com.keytab
 KrbAuthRealms CONTOSO.COM
 KrbServiceName HTTP/observium.contoso.com@CONTOSO.COM
 KrbLocalUserMapping On
 Require valid-user

Please see Google for more information about getting service keytabs to work and other Apache/Kerberos issues. This configuration will authenticate you with the webserver through your domain ticket, if you don't have one, an HTTP Basic Auth popup will request your username and password.

HTTP Authentication

Introduction

This module was contributed by NFOrce - we know of no active users, and it is not actively maintained by us; it relies on your Apache server to pass through authentication (you could use any of the available authentication modules - pam, ldap, mysql, etc); if the user is not in the database, the guest username configured is assumed. It also uses the users table in the database that the regular MySQL authentication module uses. How well this works out for user maintenance through the Observium interface is unknown.

Configuration

 $config['http_auth_guest'] = "guest";

If the user passed by Apache is not found in the Observium (MySQL) user database, the logged in user is assigned the username set here.

RADIUS Authentication

Introduction

This module uses the RADIUS protocol to authenticate users. User creation or password changes are not possible with this module.

If groups not set in configuration (see below), than all authenticated users are level 10 automatically. But if groups set and used, then the users who aren't found in groups have no access (user level 0).

This module requires the PHP radius module. Example of install this module for PHP 5.6 in Ubuntu 14.04:

 sudo apt-get install php5-radius
 sudo cp /etc/php5/conf.d/radius.ini /etc/php5/mods-available/
 sudo php5enmod radius
 sudo service apache2 restart

For newer Installs with PHP 7.x version, module named a little different and installation is easier (Ubuntu/Debian example):

 sudo apt install php-radius
 sudo phpenmod radius
 sudo service apache2 restart

Configuration

 $config['auth_radius_server']  = array('127.0.0.1'); // RADIUS server list
 $config['auth_radius_port']    = 1812;               // Server port  

This array contains a list of RADIUS servers Observium will try to connect to. The port is identical to all servers.

 $config['auth_radius_secret']  = 'secret';           // RADIUS authentication secret

Set the correct RADIUS secret here to be able to connect.

 $config['auth_radius_timeout'] = 5;                  // Timeout in seconds
 $config['auth_radius_retries'] = 2;                  // Number of retries to reconnect to RADIUS server

Retries and timeout settings before the next server is used.

 $config['auth_radius_id']      = '';                 // RADIUS NAS Identifier (if empty, used local hostname)

NAS-Identifier (32) attribute string sent to RADIUS server. When ID empty, used local server hostname. This attribute can used for identification of the client.

 $config['auth_radius_method']  = 'PAP';              // Authentication method to use: PAP (default, unencrypted), CHAP (windows radius not supported), MSCHAPv1, MSCHAPv2

Authentication method for sent user passwords to RADIUS server. PAP - default unencrypted, CHAP (CHAP_MD5) - basic password encryption by md5, not supported by Microsoft IAS server, MSCHAPv1 and MSCHAPv2 - can used with Microsoft IAS server.

 $config['auth_radius_groupmemberattr'] = 'Filter-Id';  // Attribute number or name containing the name of a group. Allowed: Filter-Id (11), Reply-Message (18)

Attribute name or number, where stored string with group name. This group name compared with keys in $config['auth_radius_groups'] and sets appropriate user level.

 $config['auth_radius_groups']['admin']['level']  = 10; // Full administrative access
 $config['auth_radius_groups']['cto']['level']     = 7; // Global read access with secured info (ie rancid configs)
 $config['auth_radius_groups']['pfy']['level']     = 5; // Global read access
 $config['auth_radius_groups']['support']['level'] = 1; // Only login access, for access to devices/entities require bind entity permissions

Configure the user levels people get when they are in a certain RADIUS group. Spaces are allowed. If $config['auth_radius_groups'] not set in config, all authenticated users are level 10 automatically.