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

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.

LDAP Authentication

Introduction

The LDAP module supports various LDAP configurations, including 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 php5-ldap support module.

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

 $config['auth_ldap_binddn'] = "cn=LookupUser,cn=Users,dc=ad,dc=example,dc=com";
 $config['auth_ldap_bindpw'] = "topsecret123";

 $config['auth_ldap_attr']['uid'] = "sAMAccountName";
 $config['auth_ldap_attr']['uidNumber'] = "objectSid";
 $config['auth_ldap_attr']['cn'] = "name";
 $config['auth_ldap_attr']['dn'] = "distinguishedname";
 $config['auth_ldap_objectclass'] = "person";

 $config['auth_ldap_version'] = 3;
 $config['auth_ldap_server'] = "domaincontroller.example.com";
 $config['auth_ldap_port']   = 389;
 $config['auth_ldap_starttls'] = TRUE;

 $config['auth_ldap_prefix'] = "CN=";
 $config['auth_ldap_suffix'] = ",CN=Users,DC=ad,DC=example,DC=com";
 $config['auth_ldap_group']  = array("CN=Observium Users,OU=Groups,DC=ad,DC=example,DC=com");
 $config['auth_ldap_groupbase'] = "OU=Groups,DC=ad,DC=example,DC=com";

 $config['auth_ldap_groupmembertype'] = "fulldn";
 $config['auth_ldap_groupmemberattr'] = "member";

 unset($config['auth_ldap_groups']);
 $config['auth_ldap_groups']['CN=Observium Admins,OU=Groups,DC=example,DC=COM']['level'] = 10;
 $config['auth_ldap_groups']['CN=Observium Users,OU=Groups,DC=example,DC=COM']['level'] = 1;  

AD requires a BIND DN defined to be able to search the directory for the user with the sAMAccountName logging in.

Users are in the default Users CN, 2 groups are defined, giving user level 10 and 1 respectively.

Special code is in place in Observium if the uidNumber attribute is set to objectSid to convert the Windows AD SID into a uidNumber-like field.

Active Directory with SSO

Same configuration as above, plus the following:

 $config['auth_ldap_kerberized'] = 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.example.com.keytab
 KrbAuthRealms AD.EXAMPLE.COM
 KrbServiceName HTTP/observium.example.com@AD.EXAMPLE.COM
 KrbLocalUserMapping On
 AuthLDAPGroupAttribute member
 AuthLDAPGroupAttributeIsDN On
 AuthLDAPURL ldap://domaincontroller.example.com:389/cn=Users,dc=ad,dc=example,dc=com?sAMAccountName?sub?(objectClass=*)
 AuthLDAPBindDN "cn=lookupUser,cn=Users,dc=ad,dc=example,dc=com"
 AuthLDAPBindPassword topsecret123
 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 php5-radius PHP module. Note, this module not exist for php7. Example of install this module in Ubuntu 14.04 (and later):

 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

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.