Hey! These docs are for version 6.5, which is no longer officially supported. Click here for the latest version, 6.7!


Opsview Monitor supports authentication of Users from LDAP or Active Directory (AD). However, each user needs to be configured in Opsview so that the correct access control is given to the user.

There are two stages:

  • [Set up an LDAP realm](🔗), so logins will be directed to your LDAP or AD server.

  • [Configure a synchronization script](🔗) to create Users in Opsview Monitor based on LDAP group membership. This also controls authorization by assigning the User's Role based on the group in which they are a member.

## Setting up an LDAP Realm

To configure LDAP or AD authentication, you will need to add configuration to the file `/opt/opsview/deploy/etc/user_vars.yml`.

Once the changes have been made to `/opt/opsview/deploy/etc/user_vars.yml`, you must run the following command as the `root` user:



**Warning**: Do NOT make edits to `/opt/opsview/webapp/opsview_web_local.yml`. This is now an Ansible managed file and will be overwritten upon running Opsview Deploy setups.

**Warning**: Do not change `opsview_web.yml` as this file is overwritten during an upgrade!

The `user_vars.yml` file needs to have the following appended to it for Active Directory:



**Note**: The user_field must be `samaccountname` in lowercase. If you set the user_field to `sAMAccountName`, you could get this error:



For OpenLDAP, the `/opt/opsview/deploy/etc/user_vars.yml` file needs to have the following appended:



If you are not using the synchronization script below, you will need to create Users in Opsview Monitor with a username which matches the User's LDAP account name, as this will not be done automatically.

**Warnings:**

  • Make sure the file is created with read permissions for the opsview user.

  • This file is yml based, so it is very particular about whitespace. Do not use tabs; it must be spaces to separate the file.

**Multiple Realms**

  • This is possible by adding another section under "realms" with the same indentation as the initial "ldap" configuration. PLEASE NOTE, that the realm name must be different from "ldap", for example if you are adding LDAP for another department or country, you may use something like "ldap_uk" or "ldap_noc".

Depending on your LDAP configuration, your basedn and user_field may vary. Also, the basedn may be _ou_ rather than _cn_ depending on your LDAP tree.

**Note:** The user_scope or group_scope defines how far down in the LDAP tree to search. A setting of _one_ means only search down one level. A setting of _sub_ means to search all levels below. You may need to set to _sub_ to find the appropriate entries.

The LDAP server needs to have a system user defined that can query specific basedns. The authentication works by initially binding to LDAP with the binddn user, searching for an appropriate user account based on the user_field attribute. It then rebinds to LDAP with that user DN and the given password. In the above example, the binddn user is anonymous with a password of secret, although this can be changed. The binddn user needs enough permissions to search for other users, and to search for group memberships.

To define multiple LDAP servers the 'ldap_server:' entry should be changed from:



to



Ensure you keep the indentation correct.

### Using TLS

To use start_tls, you need to add some additional entries, as follows (note: indentation is significant):



Further available options are listed on http://search.cpan.org/~marschap/perl-ldap-0.65/lib/Net/LDAP.pod#start_tls

### Using LDAPS

To use LDAPS, you need to use the common name (FQDN) of the LDAP server instead of its IP address. Some additional entries are required under the ldap_server_options section:



changes to



The verify field can be set to 'none', 'optional', or 'require' with the most secure option being 'require'.

When configured, you can run `/opt/opsview/webapp/bin/opsview_sync_ldap -t` to test the connection with your LDAP server.

To make the LDAP/AD authentication realm available in the web user interface (UI), restart Opsview Web:



**Note**: When there is more than one realm defined, there is an extra drop down item in the User edit page to select which realm to use on a per-user basis. The User is then authenticated via that particular realm in the future.

## Synchronization Script

`/opt/opsview/webapp/bin/opsview_sync_ldap` is a script to run nightly as the opsview user to make changes to the list of Users based on the LDAP directory. This includes which Role they have for authorisation purposes. It goes through the following steps:

  • Parse LDAP connect information from opsview_web.yml and opsview_web_local.yml

  • Connect to LDAP with the specified binddn and bindpassword

  • Read each group file from the specified directory

  • For each group, get a list of Users in that group. Find those Users and expand the group XML file based on attributes for that User

  • If specified at command line, commit changes and remove Users that do not belong in any of the groups

  • If a change has been made, go to Configuration > Apply Changes to make use of the new configuration in production.

This will create Users and set their contact information based on the XML data. If the User already exists (based on the Username), then their details will be updated.

**Note**: If you have manually added Users into Opsview Monitor for the ldap realm and then wish to use the sync script, run it without the -y option (to ignore making changes); this is because it could remove existing Users if your group permissions in LDAP have not been set up correctly.

## Default Group Attributes

The opsview_sync_ldap script expects to find the group definition files in /opt/opsview/webapp/etc/ldap by default. Each file in this directory should match a group name that is defined in LDAP. Each file is in XML format, and tells the sync script which Roles should be assigned to which Users.

### Example 1 - READ SOME opsview-admin.xml

For example, you could have a file called opsview-admin (you can also suffix with .xml if you wish) with the contents of:



This will search for the group called `opsview-admin` in LDAP using the group_filter specified in the configuration. All members of this group will then have an Opsview configuration created.

Within the XML, you can use macros, which are of the format %MACRONAME%. The macro name will be expanded with the LDAP attributes returned. You can run `opsview_sync_ldap -a` to list all the attributes returned from LDAP. Any fields that are not defined in the XML will be inserted with default values.

If a User belongs to more than one group, then a warning will be displayed. The User will be created with the first group information it matches against. In LDAP, the user should not belong to two different groups.

### Example 2 - READ ONLY yourldapgroup.xml



## Troubleshooting

If you get the error message 'Authentication error: contact administrator' on the log in page, check the audit log entries as this will show the specific authentication failure. These failures may be problems such as the LDAP server being unavailable, or it not being possible to bind with the credentials specified in the configuration file. The error will also be seen in the syslog.

### Seeing your LDAP Structure

If you need to navigate your LDAP directory and see the structure, you may wish to use a product such as [Apache Directory Studio](🔗) which provides this functionality.

### Testing LDAP connectivity

Use opsview_sync_ldap with -t to test connectivity to LDAP, using the configured bind credentials:



You can also enter a username and password to see if the credentials will work correctly and allow a user to log in:



This uses the same routines that Opsview Monitor would use, so if it works here then authentication via Opsview Monitor should work too. Remember, if you make changes to opsview_web_local.yml, you must restart opsview-web for these to take effect in the web front end.

Finally, to add all users into Opsview run:



Add this script to crontab if you want this to be regularly run.

### Opsview-web will not restart

If you get the error:



Then you have probably got tabs in the opsview_web_local.yml file. YML requires spaces only; remove tabs from the configuration file.

### XML Invalid

If you get an error similar to:



Then your XML is likely to be incorrect. Check that the XML is valid.

### Problem Logging In Via Web Interface

If it takes multiple attempts to log in to the web interface, check to see if you have multiple domain controllers and ensure they are all reachable from the Opsview Master server.