Tip

This is the documentation for the 24.06 version. Looking for the documentation of the latest version? Have a look here.

LDAP User Authentication¶

Though Lightweight Directory Access Protocol (LDAP) is technically a repository for user information, it also supports mechanisms for user authentication via bind operations.

There are many popular user directory implementations which use LDAP, including Active Directory, OpenLDAP, FreeIPA, and more.

Note

LDAP server implementations and schemas vary widely. Any examples in this documentation must be adjusted to match what the LDAP server expects.

Danger

Communication between an LDAP server and a host authenticating against the LDAP sever, such as TNSR, should be private. In other words, the best practice is to not only employ SSL/TLS encryption in LDAP, but to also ensure this communication takes place over a VPN, a directly connected secure network, or similar secure link.

While LDAP can operate using SSL/TLS to encrypt its communication, not every LDAP server supports that feature. When using plain TCP communication to an LDAP sever, data in the queries and responses is not encrypted which could expose potentially sensitive user information.

LDAP Configuration¶

TNSR supports multiple LDAP servers so long as they share the same LDAP schema and related settings. To configure LDAP settings, start in config mode and use the ldap command to enter config-ldap mode:

tnsr(config)# ldap
tnsr(config-ldap)#

Within config-ldap mode the following commands are available:

attribute-override <attr-name> <value>

This optional command overrides various attributes from the LDAP server with local values TNSR will use instead of those defined remotely.

gecos

GECOS information about a user, such as their full name, location, phone number, etc.

gidNumber

Group ID number

homeDirectory

Home directory for the user. Can be set here if there is one directory shared between all LDAP users, e.g. /home/guest.

Warning

This directory must already exist, TNSR will not create it automatically.

loginShell

Login shell for the user when they login via SSH.

For example, to force all LDAP users into the TNSR CLI when they login, use /usr/bin/clixon_cli.

uidNumber

User ID number.

userPassword

User Password.

basedn <dn-string>

Required parameter which sets the base Distinguished Name (DN) for all search queries. This value is appended to a relative distinguished name to qualify it. Typically set to the root of the LDAP structure, e.g. dc=example,dc=com

binddn <dn-string> <secret>

Optional parameter to set an LDAP user and password for TNSR to use when performing search and bind operations. Some LDAP servers allow anonymous binds, others are more strict and require authentication.

The <dn-string> value must be in the form of a fully qualified distinguished name, such as cn=myuser,dc=example,dc=com.

groupdn <dn-string>

Optional parameter to set a distinguished name for a group of which authenticating LDAP users must be a member.

The <dn-string> value must be in the form of a fully qualified distinguished name, such as cn=TNSR,ou=Groups,dc=example,dc=com.

peer-ca <ca-name>

Name of the CA which signed the LDAP server certificate. The CA must be imported into the TNSR PKI system (Certificate Authority Management). TNSR will use this CA to validate the TLS certificate supplied by the LDAP server.

This is required for transport modes tcp-starttls and tcp-ssltls.

scope (base|one|sub)

Determines where, and how deep, TNSR will perform an LDAP search to locate a match.

base: Searches the base DN only and no deeper.
one: Searches the base DN and one level beneath it.
sub: Searches the entire subtree of the directory, starting with the base DN.

Tip

This is typically the best choice, and is nearly always required for Active Directory configurations.

server <name> <host> [port <port>]

This required command defines an LDAP server

<name>: Short local name to use when referring to this LDAP server in TNSR configuration. This can be up to 15 characters long.
<host>: The address of the LDAP server. This can be a fully qualified domain name, an IPv4 IP address, or an IPv6 IP address.

Note

If this LDAP server uses SSL, the value of this field must match the certificate presented by the LDAP server. Typically this means it must be a hostname which resolves to the IP address of the LDAP server, but the specific requirements depend on the contents of the server certificate.

For example, with a value of ldap.example.com in this field, the server certificate must include an FQDN value of ldap.example.com, and ldap.example.com must resolve to 192.168.1.5. One exception to this is if the IP address of the server also happens to be the listed in the server certificate.
port <port>: This setting specifies the port on which the LDAP server is listening for LDAP queries. The default port is 389 for Standard TCP and STARTTLS, and 636 for SSL.

timeout <sec>

The time, in seconds, after which LDAP operations are considered as failed. This controls the timeout for connecting to the LDAP server as well as the time TNSR will wait for search query responses. Can be in the range of 3-60 seconds.

transport (tcp|tcl-ssltls|tcp-starttls)

This setting controls which transport method TNSR will use to communicate with the LDAP server.

Warning

LDAP queries will contain sensitive data, such as usernames, passwords, and other information about the user. The best practice is for TNSR to use encryption when communicating with the LDAP server, if the LDAP server supports it. Both SSL/TLS and STARTTLS will encrypt traffic between TNSR and the LDAP server.

tcp: Plain unencrypted TCP connections. This is not secure, but is widely supported and also useful for debugging with packet captures. Do not use this protocol across untrusted networks.
tcl-ssltls: Connects using SSL/TLS to encrypt LDAP queries.

Note

Not all LDAP servers support SSL/TLS, check the LDAP server documentation and configuration.
tcp-starttls: Connects using standard TCP and then negotiates encryption with the server using STARTTLS.

Note

Not all LDAP servers support STARTTLS, check the LDAP server documentation and configuration.

version (2|3)

Chooses which version of the LDAP protocol is employed by the LDAP server, either 2 or 3, typically 3.

Note

This only defines the LDAP server and configuration. TNSR will not use the server unless it is added to an authentication server group. That group must then be configured for use elsewhere, such as for system user authentication.

Example¶

This example configures one LDAP server in a typical OpenLDAP style schema:

tnsr(config)# ldap
tnsr(config-ldap)# server excoldap ldap.example.com
tnsr(config-ldap)# scope sub
tnsr(config-ldap)# basedn "dc=example,dc=com"
tnsr(config-ldap)# version 3
tnsr(config-ldap)# attribute-override loginShell "/usr/bin/clixon_cli"
tnsr(config-ldap)# transport tcp-starttls
tnsr(config-ldap)# peer-ca ldapca
tnsr(config-ldap)# exit

Viewing LDAP Configuration¶

To view the current LDAP, use the show ldap [(parameters|servers)] command.

On its own, the show ldap command outputs both a current server list and the configuration parameters. This output can be filtered using the additional keywords.

To view the current LDAP configuration:

tnsr(config)# show ldap parameters
Scope    Timeout Version Base DN
sub        45       3    dc=example,dc=com

Transport       Peer CA
tcp-starttls    /etc/pki/tls/tnsr/CA/ldapca.crt

Attribute                Value
loginShell               /usr/bin/clixon_cli

To view a list of servers:

tnsr(config)# show ldap servers
Name                     Host
excoldap                 ldap.example.com