LDAP / Active Directory

Securely Authenticate Users.

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:

cd /opt/opsview/deploy
./bin/opsview-deploy lib/playbooks/orchestrator-install.yml

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:


---
opsview_core_web_local_overrides:
  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 # set this to your own LDAP user
          bindpw: secret          # set this to the password of the user
          # 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: sub
          user_field: samaccountname
          user_search_options:
            deref: always
          use_roles: 0
          opsview_sync:
            group_dir: /opt/opsview/webapp/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 /opt/opsview/perl/lib/Catalyst/Authentication/Store/LDAP/User.pm line 290, <DATA> line 466.

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

---
opsview_core_web_local_overrides:
  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 # set this to your own LDAP user
          bindpw: secret          # set this to the password of the user
          # 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: /opt/opsview/webapp/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 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.

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:

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: /opt/opsview/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 /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:

[email protected]$ 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

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

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

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

<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>
<enable_tips>0</enable_tips>
<language>de</language>
<sharednotificationprofiles><name>Receive all alerts during work hours</name></sharednotificationprofiles>
</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 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:

/opt/opsview/webapp/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:

/opt/opsview/webapp/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:

/opt/opsview/webapp/bin/opsview_sync_ldap -y

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

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.

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.