Search the docs

Securing LDAP Connections with LDAPS or StartTLS

Hammerspace can connect to an LDAP server in one of three transport modes:

Transport mode What it does

LDAP

Plain LDAP. Nothing is encrypted, including the bind secret if you use one. No certificate is involved.

LDAPS

LDAP over TLS from the start of the connection (ldaps://), conventionally on port 636.

STARTTLS

Opens a plain LDAP connection (ldap://), conventionally on port 389, and upgrades it to TLS before any directory data is exchanged.

With LDAPS or StartTLS, the LDAP server’s certificate must be acceptable to two different checks, described below. Most failures with a secure transport come from satisfying the first check but not the second.

What Hammerspace Checks

The connection test checks the server’s identity only. The connection test runs when you add or update a name service, when you click Test Connection, when you run name-service-config --test-connect, and in the scheduled health checks. It accepts the certificate if a Subject Alternative Name (SAN) in it matches the server address you configured:

  • A DNS name in the SAN must match a configured host name. A wildcard such as *.example.com matches one level only (ldap1.example.com, but not ldap1.east.example.com).

  • An IP address in the SAN must match a configured IP address.

  • The certificate’s Common Name (CN) is not considered. A certificate without a matching SAN fails the test.

The connection test does not check the certificate chain, the signature, or the validity dates. A self-signed or expired certificate passes it as long as the SAN matches.

SSSD checks the whole certificate at run time. Lookups made after the name service is saved — by NFS and by User/Group Lookup — go through SSSD on the Anvil. SSSD requires the certificate to be valid and to chain to a CA certificate in the Anvil’s system trust store, and this requirement cannot be relaxed. Hammerspace fills the Anvil’s system trust store from its own trust store, which you manage with cert-add or the Trusted Certificates tab.

Because the two checks differ, a name service can pass the connection test, show operational state UP, and still fail every lookup. The scheduled health checks use the connection test too, so they do not detect this.

Trusting the LDAP Server Certificate

Add the certificate of the CA that issued the LDAP server’s certificate to the Hammerspace trust store before you add the name service.

  1. Obtain the issuing CA certificate in PEM format. Use the root CA certificate where possible. The root CA alone is enough when the LDAP server sends its intermediate CA certificates along with its own certificate, which is the usual configuration.

  2. Add it to the Hammerspace trust store in one of these ways:

    • In the GUI, on the Trusted Certificates tab of Administration  TLS. See Add a Trusted CA Certificate Using the Management GUI. In Hammerspace 5.3, the GUI adds root CA certificates only.

    • In the Admin CLI, with cert-add --pem "<pem_content>". To add an intermediate CA certificate, put the intermediate certificate and its root together in <pem_content> (intermediate first) and add --trust-intermediate-ca; an intermediate given on its own is rejected, even when its root is already in the trust store. If the LDAP server uses a self-signed certificate that is not a CA certificate, add that certificate itself with --trust-self-signed-certificate. See Manage Certificates and CAs.

  3. Add the name service, with the server address set to a name or IP address that appears in the server certificate’s SAN. See Adding an LDAP Name Service.

  4. Verify with User/Group Lookup or name-service-config --resolve-user. A successful connection test alone does not prove that the certificate is trusted.

Hammerspace copies the trust store to every node and adds its certificates to each node’s operating-system trust store. You cannot add the LDAP server’s own certificate when it is issued by a CA (a CA-signed leaf certificate); cert-add rejects it with Certificate is not a CA or self-signed. Add the issuing CA instead.

If you add a CA certificate to fix a name service that already exists, you do not need to change or re-add the name service: SSSD picks up the new CA on its own, and lookups succeed within about a minute. Check with User/Group Lookup.

Choosing the Server Address

The address you configure is used both for the connection-test identity check and by SSSD, so:

  • Configure the server by the DNS name in its certificate’s SAN, and make sure the Anvil nodes can resolve that name in DNS.

  • Configure the server by IP address only if the certificate carries that IP address in its SAN.

What You See When the Certificate Is Wrong

The certificate does not name the configured address. The secure transport modes fail the connection test. What happens next depends on whether you set a transport mode:

  • If you set LDAPS or STARTTLS, the add or update fails with Failed to connect to LDAP server '<domain>' using address '<address>' with transport mode <mode>. The message does not give the reason.

  • If you left the transport mode unset and the server also accepts plain LDAP, the test falls back to LDAP, and the name service is added with transport mode LDAP — unencrypted. The failed secure attempts are listed with the result (in the GUI, click Show Details; in the Admin CLI, under Connection attempts:), and a SAN mismatch is reported there as Server identity mismatch: expected <address>, but certificate SANs were: <SAN list>. Check the Transport mode of the name service after adding it.

The fallback happens only when the SAN does not match. When the SAN matches but the certificate is not trusted, the test keeps the secure transport mode (STARTTLS when the server offers it) and the name service is added — and its lookups then fail as described next.

Reconfigure the name service with an address that the certificate names, or have the certificate reissued with the address in its SAN.

The certificate is not trusted, has expired, or has a broken chain. The connection test passes and the name service shows UP, but lookups fail: User/Group Lookup and --resolve-user report User '<user>@<domain>' not found, with no error text, and NFS users are not mapped to their UIDs and GIDs. Users and groups that SSSD has already cached from earlier lookups keep resolving until their cache entries expire (the SSSD default is 90 minutes), so the symptom is often that new users are not found while existing users still work. Add the issuing CA to the trust store as described above.