Authentication backends

This plugins allows to use alternative authentication backends for Rudder: LDAP/AD and radius.

Configure enabled backends

By default, both authentication and authorization are handle in the rudder-users.xml file. But you may want to rely on your existing entreprise Active Directory or LDAP to take care of the authentication part.

To choose the scheme to use, either use 'file' or 'ldap' for the rudder.auth.provider parameter in configuration file: /opt/rudder/etc/rudder-web.properties.

After a change in Rudder /opt/rudder/etc/rudder-web.properties configuration file, you need to restart the web application with the command:

systemctl restart rudder-jetty

You can also use a comma separated list of authentication provider to use, like 'ldap,file' in which case each one will be tested in turned for authentication.

When set to 'ldap' or 'radius', passwords in rudder-users.xml are ignored and the authentication is delegated to the LDAP or radius server configured.

By convention, when LDAP authentication is enable, 'password' field in rudder-users.xml are set to 'LDAP'.

After a change in rudder-users.xml configuration file, you need to reload user information. This can be done with user-management plugin (either in UI or via API, see that plugin documentation for more information), or by restarting the web application with the command:

systemctl restart rudder-jetty

For example, to use first and ldap authentication, and then in case the user is not found in ldap, fall-back in file authentication, you will specify:

rudder.auth.provider=ldap,file

For example, that rudder-users.xml file will configure "admin" by file access, and "joe" by LDAP:

<authentication hash="sha512">
  <user name="admin" password="ab7f...b8a538dc69dd8de907ec" role="administrator" />
  <user name="joe" password="LDAP" role="administrator" />
</authentication>

Be careful to have only one rudder.auth.provider property in your file!

In case your authentication backend does not work, you can still configure the rootAccount in /opt/rudder/etc/rudder-web.properties to regain an administrator access. Once logged as an administrator, you can go to the Plugins > Authentication Backends page to check that Rudder interpreted correctly your configuration.

In particular, check that Computed list of providers entry matches your will.

LDAP / AD backend configuration

The configuration properties that need to be added in /opt/rudder/etc/rudder-web.properties file to configure the LDAP or AD authentication backend are displayed below.

For convenience, the part betweeb ---- add in rudder-web.properties ---- and ---- end of add in rudder-web.properties ---- can be directly added in your /opt/rudder/etc/rudder-web.properties file.

Note that key "rudder.auth.provider" is likelly to already exists. In that case, just update it with the sequence of authentication backend you want to try.

---- add in rudder-web.properties ----

###########################
# Rudder Authentication    #############################################################
###########################

#
# update provider:
#
rudder.auth.provider=ldap


###########################
# LDAP Authentication      #############################################################
###########################


# The following parameters allow to configure the LDAP authentication provider.
# The LDAP authentication procedure is a typical bind/search/rebind, in which
# an application connection (bind) is used to search (search) for an user entry
# given some base and filter parameters, and then, a bind (rebind) is tried on
# that entry with the credential provided by the user.
# That allows to separate the user DN (especially RDN) from the search criteria while
# in the same time supporting users located in several different organisational units.
#
# Be careful, authorizations are still done based on the content of rudder-user.xml,
# meaning that each user should have access to Rudder MUST have a line in that file.
# Without that line, the user can have a successful LDAP authentication, but
# won't be able to do or see anything in Rudder (only logout).
#

# === EXAMPLE / ldapsearch test===
#
# With the example data below, if the user "jon.doe" try to login with password "mypasswd",
# the corresponding `ldapsearch` request are:
#
# 1/ search for user with `service` login:
# ----
# $ ldapsearch -LLL -o ldif-wrap=no -h ldap.mycorp.com -p 389 -x -D "cn=rudder,ou=services,dc=mycorp,dc=com" -w secret -b "ou=Users,dc=mycorp,dc=com" -s sub '(&(cn=jon.doe)(objectclass=person))' 1.1
#
#  dn: cn=jon.doe,ou=Paris,ou=Users,dc=mycorp,dc=com
# ----
#
# Errors and unexpected:
# - an authentication error here means that your rudder service user does not have the
#   rights to do a search and will not be able to find the corresponding user full DN;
# - you should get exactly one result: the DN to use in the second request. If you don't
#   get any results, check the base DN and the LDAP filter.
#
# 2/ bind request with user DN (search user own entry with its credentials):
# ----
# $ ldapsearch -LLL -o ldif-wrap=no -h ldap.mycorp.com -p 389 -x -D "cn=jon.doe,ou=Paris,ou=Users,dc=mycorp,dc=com" -w mypasswd -b "cn=jon.doe,ou=Paris,ou=Users,dc=mycorp,dc=com" -s base 1.1
#
# dn: cn=jon.doe,ou=Paris,ou=Users,dc=mycorp,dc=com
# ----
#
# Errors and unexpected:
# - an authentication error here is likely to mean that the user password is not correct,
#   but you should also check your LDAP directory ACLs.
#

#
# Connection URL to the LDAP server, in the form:
# ldap://hostname:port/base_dn
#
rudder.auth.ldap.connection.url=ldap://ldap.mycorp.com:389/dc=mycorp,dc=com

#
# Bind DN used by Rudder to do the search. This is the "service" or
# "application" DN for Rudder in you LDAP directory, or an LDAP user with
# enought rights to be able to walk the user branch configured below.
# LDAP dn, no default value.
#
rudder.auth.ldap.connection.bind.dn=cn=rudder,ou=services,dc=mycorp,dc=com

#
# Bind password used by Rudder service (the DN configured just above) to do the search.
# String, no default value.
#
rudder.auth.ldap.connection.bind.password=secret

#
# Search base and filter to use to find the user.
# The search base can be left empty. In that
# case, the root of directory is used.
#
rudder.auth.ldap.searchbase=ou=People

#
# In the filter, {0} denotes the value provided as
# login by the user.
# The filter must lead to at most one result, which
# will be used to try the (re)bind request.
#
rudder.auth.ldap.filter=(&(uid={0})(objectclass=person))

#
# An AD example would be:
#
#rudder.auth.ldap.searchbase=
#rudder.auth.ldap.filter=(&(sAMAccountName={0})(objectclass=user))

---- end of add in rudder-web.properties ----

Using a certificate for secure connection to LDAP/AD

If you want to connect with a secure connection to an LDAP or AD, you need to add the directory certificate to Rudder’s JVM keystore.

Without that, you will see errors in /var/log/rudder/webapp/XXXXXXX_stderrout.log files like:

WARN  application - Login authentication failed for user 'xxx' from IP '127.0.0.1|X-Forwarded-For:xxx.xxx.xxx.xxx': simple bind failed: xxx.xxx:636; nested exception is javax.naming.CommunicationException: simple bind failed:

xxx.xxx:636 [Root exception is java.net.SocketException: Connection or outbound has closed]

Adding certificate to JVM keystore

# copy the certificate somewhere in /opt/rudder

cd path/to/jdk<in-use-version>/lib/security

keytool -importcert -trustcacerts -keystore cacerts -storepass changeit -noprompt -alias "rudder-ldap-certificate" -file <path to AD server certificate>

Error because certificate is 1024 bits

Since JVM version 8, certificate of size 1024 or less are forbidden by default. If you still use a certificate with that size, you will get errors like:

Root exception is javax.net.ssl.SSLHandshakeException: PKIX path validation failed: java.security.cert.CertPathValidatorException: Algorithm constraints check failed on keysize limits: RSA 1024 bit key used with certificate

To correct that problem, you need to remove that restriction (and update your certificates for security):

  • edit path/to/jdk<in-use-version>/conf/security/java.security

  • check constraints on RSA keysize like RSA keySize < 1024 and change them to match your key size for properties:

  • jdk.tls.disabledAlgorithms

  • jdk.certpath.disabledAlgorithms

  • restart rudder-jetty

Radius backend configuration

Below follow the configuration properties that need to be added in /opt/rudder/etc/rudder-web.properties file to configure the Radius authentication backend.

For convenience, the part under "---- add in rudder-web.properties----" can be directly added in your /opt/rudder/etc/rudder-web.properties file.

Note that key rudder.auth.provider is likelly to already exists. In that case, just update it with the sequence of authentication backend you want to try.

---- add in rudder-web.properties ----

###########################
# Rudder Authentication    #############################################################
###########################

# update provider list:
rudder.auth.provider=radius

###########################
# Radius Authentication    #############################################################
###########################

#
# The following parameters allow to configure authentication with a
# Radius server.
#


#
# Use "radius" auth type to enable radius authentication
#
#rudder.auth.provider=file,radius

#
# IP or hostname of the Radius server. Both work, but it is preferred to use an IP.
#
rudder.auth.radius.host.name=192.168.42.80

#
# Authentication port for the Radius server
#
rudder.auth.radius.host.auth.port=1812

#
# The shared secret as configured in your Radius server for Rudder application / host.
#
rudder.auth.radius.host.sharedSecret=secret

#
# Time to wait in seconds when trying to connect to the server before giving up.
#
rudder.auth.radius.auth.timeout=10

#
# Number of retries to attempt in case of timeout before giving up.
#
rudder.auth.radius.auth.retries=0

#
# Authentication protocol to use to connect to the Radius server. The default
# one is 'pap' (PAP).
# Available protocols::
# - pap
# - chap
# - eap-md5
# - eap-ttls
#
# For `eap-ttls`, you can append `key=value` parameters, separated by `:` to the
# protocol name to specify protocol option, for example:
# `eap-tls:keyFile=keystore:keyPassword=mypass`
#
rudder.auth.radius.auth.protocol=pap

---- end of add in rudder-web.properties ----

← API authorizations Branding →