Opsview Knowledge Center

LDAP / Active Directory

Authenticate Users in Opsview Monitor

If you want to authenticate Users in Opsview Monitor from LDAP or Active Directory (AD), there are two options:

  • Users can authenticate to Opsview Monitor using their LDAP or AD credentials
  • Optionally, you can run a synchronization script to create Users in Opsview Monitor based on LDAP group membership. This also controls authorization by assigning the Users' Roles based on the group in which they are a member.

See Logging into Opsview Monitor Using LDAP Credentials and the child articles for information on setting up LDAP/AD integration, testing, troubleshooting and more.

Logging into Opsview Monitor using LDAP Credentials

The process is:

  • Set up an LDAP realm for the Opsview Monitor web application
  • For Users associated with that realm, their credentials will be passed to LDAP for verification.

Please follow steps:
Setting Up an LDAP Realm through to Troubleshooting for information on setup, configuration, troubleshooting and more.

Setting up an LDAP Realm

To configure LDAP or AD authentication, you will need to add configuration to the file usr/local/opsview-web/opsview_web_local.yml. If this file does not exist, then you need to create it.

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

The opsview_web_local.yml file needs to look like the following for Active Directory:

---
authentication:
  realms:
    ldap:
      credential:
        class: Password
        password_field: password
        password_type: self_check
      store:
        class: LDAP
        ldap_server: ldap.company.com
        ldap_server_options:
          timeout: 30
        binddn: anonymous
        bindpw: secret
# Use bindpw_encrypted instead of bindpw if you want an encrypted value. Use the 'opsview_crypt' tool to generate the value
#        bindpw_encrypted: 88ff95374e563866f6c3c2af4517979a3dc14ea3cbdadb8684ada121e210e818
        start_tls: 0
        user_basedn: cn=Users,dc=ldap,dc=company,dc=com
        user_filter: (sAMAccountName=%s)
        user_scope: one
        user_field: samaccountname
        user_search_options:
          deref: always
        use_roles: 0
        opsview_sync:
          group_dir: /usr/local/nagios/etc/ldap
          group_basedn: cn=Users,dc=ldap,dc=company,dc=com
          group_filter: (&(objectClass=group)(sAMAccountName=%s))
          group_scope: one

Note:

The user_field must be samaccountname in lowercase. If you set the user_field to

sAMAccountName, you could get this error:

Deep recursion on subroutine "Catalyst::Authentication::Store::LDAP::User::stringify" at /usr/local/nagios/perl/lib/Catalyst/Authentication/Store/LDAP/User.pm line 290, <DATA> line 466.

For OpenLDAP, the opsview_web_local.yml file needs to look like the following:

---
authentication:
  realms:
    ldap:
      credential:
        class: Password
        password_field: password
        password_type: self_check
      store:
        class: LDAP
        ldap_server: localhost
        ldap_server_options:
          timeout: 30
        binddn: anonymous
        bindpw: secret
# Use bindpw_encrypted instead of bindpw if you want an encrypted value. Use the 'opsview_crypt' tool to generate the value
#        bindpw_encrypted: 88ff95374e563866f6c3c2af4517979a3dc14ea3cbdadb8684ada121e210e818
        start_tls: 0
        user_basedn: ou=People,dc=ldap,dc=company,dc=com
        user_filter: (&(objectClass=posixAccount)(objectClass=inetOrgPerson)(uid=%s))
        user_scope: sub
        user_field: uid
        user_search_options:
          deref: always
        use_roles: 0
        opsview_sync:
          group_dir: /usr/local/nagios/etc/ldap
          group_member_field: memberUid
          group_basedn: ou=Group,dc=ldap,dc=company,dc=com
          group_filter: (&(objectClass=posixGroup)(cn=%s))
          group_scope: sub

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

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.

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:

ldap_server: ldap.company.com

to

ldap_server: 
  - ldap.company.com
  - backup-ldap.company.com

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

        start_tls: 1
        start_tls_options:
          verify: required
          cafile: /home/nagios/ca.pem

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:

ldap_server_options:
  timeout: 30
changes to 
ldap_server_options:
  timeout: 30
  scheme: ldaps
  cafile: /path/to/ssl/certs/certificate.csr
  verify: require

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

When configured, you can run /usr/local/nagios/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:

nagios@system$ opsview_watchdog opsview-web restart


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

/usr/local/nagios/bin/opsview_sync_ldap is a script to run nightly as the nagios 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, initiate an Opsview Monitor reload.

This will create Users and set their contact information based on the XML data. If the User already
exists (based on the Username), then his 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 /usr/local/nagios/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:

<contact>
<name>%NAME%</name>
<username>%SAMACCOUNTNAME%</username>
<comment>%USERPRINCIPALNAME%</comment>
<role><name>View some, change none</name></role>
<variables><name>EMAIL</name><value>%USERPRINCIPALNAME%</value></variables>
<variables><name>RSS_MAXIMUM_ITEMS</name><value>100</value></variables>
<variables><name>RSS_MAXIMUM_AGE</name><value>2880</value></variables>
<variables><name>RSS_COLLAPSED</name><value>1</value></variables>
<variables><name>PAGER</name><value>%telephonenumber%</value></variables>
</contact>

Note that 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

<contact>
<name>%NAME%</name>
<username>%SAMACCOUNTNAME%</username>
<comment>%USERPRINCIPALNAME%</comment>
<role><name>View all, change none</name></role>
<variables><name>EMAIL</name><value>%USERPRINCIPALNAME%</value></variables>
<variables><name>RSS_MAXIMUM_ITEMS</name><value>100</value></variables>
<variables><name>RSS_MAXIMUM_AGE</name><value>2880</value></variables>
<variables><name>RSS_COLLAPSED</name><value>1</value></variables>
</contact>

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 /var/log/opsview-web.log.

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:

/usr/local/nagios/bin/opsview_sync_ldap -t

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

/usr/local/nagios/bin/opsview_sync_ldap -t -u {username} -p {password}

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:

/usr/local/nagios/bin/opsview_sync_ldap -y

Opsview-web will not restart

If you get the error:

Cannot find version string in opsview_web.yml - file is possibly invalid (remove any hardtabs)

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:

End tag mismatch (contact != notification_period) [Ln: 21, Col: 9]

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

Host Group/Service Group names incorrect

If you get an error similar to:

DBIx::Class::Row::insert(): DBI Exception: DBD::mysql::st execute failed: Column 'hostgroupid' cannot be null [for Statement "INSERT INTO hostgroupnotify (contactid, hostgroupid) VALUES (?, ?)" with ParamValues: 1=undef, 0='3'] at /usr/local/nagios/bin/opsview_sync_ldap line 211

Then the Host Group you have specified in the XML file does not exist.

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.

LDAP / Active Directory

Authenticate Users in Opsview Monitor