External Authentication

If you have an existing directory for authenticating users, you can configure Horizon to use that system to grant users access to log in, in addition to allowing log in from users defined directly within your Horizon server.

Configure external authentication

The Horizon web app uses Spring Security for its user authentication, authorization, and accounting (AAA) concerns.

The Spring Security configuration files are located in at ${OPENNMS_HOME}/jetty-webapps/opennms/WEB-INF. Only one authentication service can be enabled in the spring-security.d subdirectory.

The following files are used for external authentication:

File Description

File	Description
applicationContext-spring-security.xml	The main Spring Security context configuration file for the OpenNMS web app. The `authentication-provider` parameter must be uncommented to enable external authentication: `<!-- To enable external (for example, LDAP, RADIUS) authentication, uncomment the following. You must also rename and customize exactly ONE of the example files in the spring-security.d subdirectory.--> <authentication-provider ref="externalAuthenticationProvider" />`
spring-security.d/*	Directory containing example files for common use cases. You must copy one of these files, rename it, and edit its details. There cannot be more than one active `.xml` file in this directory.
*.xml.disabled	Skeleton files included with Horizon as starting files for your configuration. The `.disabled` files are ignored when Spring Security loads.

applicationContext-spring-security.xml

The main Spring Security context configuration file for the OpenNMS web app. The authentication-provider parameter must be uncommented to enable external authentication:

<!-- To enable external (for example, LDAP, RADIUS) authentication, uncomment the following.
You must also rename and customize exactly ONE of the example files in the
spring-security.d subdirectory.-->
<authentication-provider ref="externalAuthenticationProvider" />

spring-security.d/*

Directory containing example files for common use cases. You must copy one of these files, rename it, and edit its details. There cannot be more than one active .xml file in this directory.

*.xml.disabled

Skeleton files included with Horizon as starting files for your configuration. The .disabled files are ignored when Spring Security loads.

Anatomy of an LDAP configuration

Whether the authentication source is an Active Directory, a Novell eDirectory, or some other LDAP-enabled directory, the basic components (expressed as "beans" in Spring Framework lingo) that need to exist and be configured are the same.

While Active Directory and OpenLDAP (and others) implement the same LDAP protocol, their schemas are substantially different. The biggest difference is the memberOf attribute, which is not supported by the default LDAP v3 specification and is not present in common OpenLDAP installs, but comes standard with AD. This has a significant implication in that you cannot filter a user search by nested group membership, and most installs tend not to be fully hierarchical. You can either create dedicated per-role LDAP groups or map existing groups to roles by selecting and configuring the appropriate userGroupLdapAuthoritiesPopulator.

LDAP configuration parameters
Property	Description
authenticationSource	Provide credentials to bind to your directory in the `defaultUser` and `defaultPassword` properties.
contextSource	Define your LDAP server URLs and search base. If you have multiple LDAP servers, include them as separate `<beans:value>` entries.
userGroupLdapAuthoritiesPopulator	Define where Spring Security should find groups in your directory. By defining `groupToRoleMap` entries, groups in your directory can be mapped to one or more security roles. This determines what level of access to grant to users in specific groups.
userSearch	Define where Spring Security should find users in your directory.

If your directory requires an SSL connection and is signed with a private certificate authority, make sure to add the certificates to your truststore.

You must restart Horizon after making any changes to your Spring Security configuration. Before doing this, we recommend you make sure that your changes have not led to malformed .xml files:

xmllint --noout applicationContext-spring-security.xml spring-security.d/*.xml

If this command produces no output, then the .xml files are well formed.

If your configuration is set correctly, you will be able to log in to the Horizon web UI using your directory credentials after restarting OpenNMS.

Troubleshooting

If your server is not allowing login via your configured external authentication provider, check your authentication logs. They are written to ${OPENNMS_HOME}/logs/web.log.