
= External Authentication
:description: Learn how to configure external authentication like Active Directory, Novell eDirectory, or another LDAP-enabled directory in {page-component-title}.

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

== Configure external authentication

The {page-component-title} web app uses https://spring.io/projects/spring-security[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:

[cols="1,3a"]
|===
| 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: +
[source, xml]
----
<!-- 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 {page-component-title} 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`.

[caption=]
.LDAP configuration parameters
[cols="1,3"]
|===
| 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.
|===

NOTE: If your directory requires an SSL connection and is signed with a private certificate authority, make sure to add the certificates to your xref:deep-dive/admin/configuration/https/https-client.adoc[truststore].

You must restart {page-component-title} 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:

[source, console]
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 {page-component-title} 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`.
