Date: 11-04-2022

Secure Protocols

Symas OpenLDAP offers two protocols for securing (encrypting) replication connections:

• LDAPS (ldaps://\/)
• LDAP over TLS (ldap://\/ + START_TLS)

Both protocols require the use of a common TLS CA certificate issued by a trusted certificate authority (CA) for establishing an encrypted connection between the replication consumer and replication provider.

TLS Certificates

Bind method-specific certificate requirements and examples are covered in later sections of this document.

OpenLDAP uses x509 certificates for encryption and authentication. Certificates can be sourced from text files (.pem, .cer, etc.) or from Mozilla NSS cert/key databases.

For encryption, a CA (certificate authority) certificate file is shared between all hosts that connect with each other. CA certificate files contain one or more public encryption keys issued by a trusted certificate authority (Verisign, Entrust, etc.) to your organization. If the CA certificate file on the replication consumer does not contain an encryption key that matches the replication provider, an encrypted connection will not be established.

For authentication (via the SASL/Exeternal bind method/mechanism), the replication consumer uses a TLS certificate to present to the replication provider. The provider verifies certain data in the consumer's certificate is valid and then maps the identity used in the certificate to an LDAP user responsible for replication. Full details details in Securing SASL Binds

Global SSL/TLS Certificate Configuration

SSL/TLS certificates must be configured globally. The global TLS configuration serves two purposes:

1. It defines which certificates the server will honor for incoming connections.
2. It sets the default certificate files used for external LDAP connections made by the server (syncrepl, chaining, etc.)
3. If using dynamic configuration (cn=config), use the olcTLS* settings defined below as attributes of the cn=config object in the configuration DIT
4. If using static configuration (slapd.conf), use the TLS* settings defined below in an area of slapd.conf, in the area above the backend configurations

All servers must have a globally defined TLS CA certificate file defined by:

• TLSCACertificateFile | olcTLSCACertificateFile \

If using certificate-based SASL/External authentication, the server certificate files are defined by:

• TLSCertificateFile | olcTLSCertificateFile \
• TLSCertificateKeyFile | olcTLSCertificateKeyFile \

The global TLS certificate settings may be overridden in the consumer's syncrepl configuration directive (details below).

Replication Entities

Syncrepl clients must use the identity of a valid LDAP user entry with read access to the entire DIT.

It is strongly recommended that when using simple binds, the entry used is not the rootDN of the DIT because the credentials of the replication user must be stored in plain text in the syncrepl configuration stanza.

Replication User Entries

When using simple binds, the replication user entry must be present in the DIT and must be in implementation of the "person" object class:

dn: cn=replicator,ou=admin,dc=example,dc=com
objectClass: person
objectClass: top
cn: replicator
sn: Replicator
description: Replication User
userPassword: secret

When using SASL binds, the replication user entry can exist in the configuration alone and is not required to be present in the DIT.

Replication User Entry Access Control and Limits

When using a user entry/identity instead of the rootDn (and you really should do this), access controls and search limits for the entry/identity must be configured to ensure complete replication:

Replication User Entry ACLs

Replication user entries must have unlimited read access to the entire DIT. If full read access is not allowed, replication will fail.

Access controls for the entry/identity should be placed at the top of the ACLs. This helps improve performance because the entry/identity is allowed to read everything in the DIT so it bypasses the need for any specialized ACL evaluations.

cn=config

dn: olcDatabase{1}mdb,cn=config
changetype: modify
replace: olcAccess
olcAccess: to * by dn.exact="cn=replicator,ou=admin,dc=example,dc=com" read

slapd.conf

access to * by dn.exact="cn=replicator,ou=admin,dc=example,dc=com" read

Replication User Entry Limits

The replication user entry must be able to receive an unlimited number of search results (size) and must not be limited to the amount of time a search takes. If the size is not set to unlimited, the number of search results will be limited to 500 entries, potentially preventing all of a DIT from being replicated. Evidence of this condition is the repeated presence of (err=4) sizeLimitExceeded messages in the slapd log file.

Bind Methods

There are two methods that may be used for replication clients to bind with providers: simple binds and SASL binds.

Securing With SASL Binds

SASL binds use external authentication mechanisms to validate users. The most common mechanisms are:

• EXTERNAL (x509 certificates)
• GSSAPI/Kerberos
• LDAP (separate LDAP databases)

There are several advantages to using SASL binds:

1. When using modern mechanisms, the connection between the client and server is guaranteed to be encrypted before user credentials are passed over the wire.
2. User credentials are not stored in the LDAP database; instead they are handled by the SASL mechanism. This reduces the risk of exposing plain text or hashed userPassword attributes from misconfigured LDAP servers or unsecured backup LDIF files.
3. Authenticating users via Kerberos, Active Directory or external LDAP helps maintain a more unified user authentication infrastructure (one less username and password.)

Identity Mapping

SASL mechanisms authenticate with user identities formatted differently than the user identity in the LDAP database. To overcome this, OpenLDAP performs identity mapping using regular expression-based (perl syntax) patterns with the authz-regexp setting. The authz-regexp settings has two parameters:

1. A search pattern to match and/or capture elements of authorization DN provided by a SASL mechanism
2. A replacement pattern that uses the captured authorization DN elements to a user DN recognized by the LDAP server

Examples are provided below.

x509 Certificate Authentication (EXTERNAL)

With x509 certificate authentication,

the x509 certificate presented by the client is first validated (certificate issuer, expiration, etc.) Once validated, slapd uses the Subject or subjectAltName in the certificate as the identity to use for authentication. For example, a client certificate has the following subject:

/C=US/ST=WA/L=Seattle/O=Example/OU=Security/CN=consumer_01.example.com/emailAddress=security@example.com

The following authz-regexp setting will match the subject above (or similar DNs with "consumer_NN.example.com" and translate it to the DN of the replication user:

authz-regexp
  "/C=US/ST=WA/L=Seattle/O=Example/OU=Security/CN=consumer_\d\d.example.com/emailAddress=security@example.com"
  "cn=replicator,dc=example,dc=com"

GSSAPI/Kerberos Authentication

For example, a user's identity in Kerberos is bob_smith@EXAMPLE.COM. When a

authz-regexp "uid=([^,]*),cn=gssapi,cn=auth"
  "krb5PrincipalName=$1@example.com,ou=KerberosPrincipals,dc=example,dc=com"

The EXTERNAL (x509 certificate-based) authorization mechanism is the simplest to implement.

• [ ] Pros/Cons
• [ ] Authz Config
• [ ] SASL Config Example (cn=config)
• [ ] SASL Config Example (slapd.conf) 

The use of DIGEST-MD5, CRAM-MD5, PLAIN and LOGIN is discouraged.

Securing Simple Binds

• Simple binds use a traditional username (bindDn) and password (credentials) scheme for authentication. Though this is the simplest method, it is also the least secure as the bind credentials must be saved in clear text in the syncrepl configuration stanza (hashed passwords cannot be read.)

• [ ] Required
• [ ] Simple Config Example (cn=config)
• [ ] Simple Config Example (slapd.conf)