LDAP authentication

Overview

Use the LDAP provider to authenticate with OpenLDAP or Microsoft Active Directory (AD). This guide covers directory configuration, group resolution, connection testing, and certificates.

Before you begin

  • You have an administrator account in F5 Insight.
  • You have a directory account that can read users and groups.
  • F5 Insight can reach your directory server.
  • You have the directory connection details and attribute mappings.

Configure a group-to-role mapping before testing user access. F5 Insight blocks access when no role is found. See External authentication and role-based access control.

Important

If there’s any risk of username collisions, don’t use local and external users together. Keep external usernames distinct from all local usernames.

Avoid the external username admin. F5 Insight assigns Admin to that username regardless of remote role mappings.

When a local and an external username collide, you can no longer manage the local user or reset the local password. For example, after an external admin login, the local admin account disappears from the user list. See Known authentication issues.

Note

Reset Password appears for external users, but password resets apply only to local users. Manage directory passwords through your directory service.

Configuring an LDAP provider

  1. Log in to F5 Insight as an administrator.
  2. Navigate to Settings ‣ User Administration ‣ SSO Identity Providers.
  3. Select LDAP.
  4. Fill in the required configuration fields:
Field Description Required
Provider Name Display name for the provider (appears on the login screen) Yes
Server URL LDAP server hostname or IP address with port (for example, ldap://ldap.example.com:389 or ldaps://ldap.example.com:636) Yes
Base DN Base Distinguished Name for user search queries Yes
Bind DN Distinguished Name used to authenticate with the LDAP server Yes
Bind Password Password for the Bind DN account Yes
LDAP Attributes Mapping of LDAP attributes to user properties (for example, mail, username, and so on) Yes
Userbase DN User search base DN Yes
User filters Attribute name used to find the directory entry that matches the login value, such as uid or sAMAccountName. Don’t enter a full LDAP filter expression. Yes
User object LDAP object class used for user entries Yes
  1. Select Create to save the configuration and Activate to enable the provider on the screen.

Use these examples to choose the lookup attribute and account mappings for your directory. The Active Directory values are schema examples.

For account mappings, attribute names are case-sensitive in F5 Insight. Match the spelling that your directory returns. Enter one attribute name per mapping, not a list of alternatives.

LDAP lookup and attribute examples
Form setting Purpose OpenLDAP Active Directory
User filters Finds the directory entry that matches the value you enter at login. uid sAMAccountName or userPrincipalName
User ID attribute Supplies the stable, unique identifier for the account. This is separate from the account username. uid sAMAccountName or userPrincipalName
Username attribute Supplies the account username after F5 Insight finds the directory entry. This can differ from User filters. uid sAMAccountName or userPrincipalName
Email attribute Supplies the email address. mail mail
Displayname attribute Supplies the display name. displayName or cn displayName
First name attribute Supplies the first name. givenName givenName
Last name attribute Supplies the last name. sn sn

Keep User ID attribute stable. If you change the identifier, existing user links can change.

The OpenLDAP sample directory entry uses cn for the display name.

Note

Username in Test LDAP User Authentication is the login value, not an attribute name.

For example, set User filters to sAMAccountName and Username attribute to userPrincipalName. Enter usera in the test’s Username box. F5 Insight finds the entry whose sAMAccountName is usera. If the entry’s userPrincipalName is user@example.com, F5 Insight uses user@example.com as the account username.

Note

Only one active LDAP and one active OKTA, PING are allowed.

Note

After activation, a “Log in with <Provider Name>” button appears on the login page immediately.

Note

For the OpenLDAP example, set User filters to uid. For Active Directory, use your directory’s user lookup attribute. Do not enter a full LDAP filter string such as (&(objectClass=inetOrgPerson)(uid={0})) in that field.

Note

The LDAP server must be reachable on a standard LDAP port: 389 for LDAP (or LDAP with StartTLS) and 636 for LDAPS. Make sure firewall and network policy rules allow traffic from F5 Insight to the selected port.

Configure OpenLDAP

OpenLDAP uses the LDAP provider type. Follow Configuring an LDAP provider with the connection settings for your directory.

  1. Set Userbase DN to the container that contains your user entries, such as ou=People,dc=ldap,dc=example,dc=com.
  2. Set User filters to the user lookup attribute, such as uid. Don’t enter a full LDAP filter expression.
  3. Set User object to the object class for your users, such as inetOrgPerson.

For sample directory entries and attribute mappings, see OpenLDAP configuration notes and sample LDIF expectations.

For role mapping, enter the exact group common name (CN), such as f5-admin, in Grouped Resource Attribute. Matching is case-sensitive. The cn= prefix is optional, and anything after the first comma is ignored. For example, f5-admin, cn=f5-admin, and cn=f5-admin,ou=Groups,dc=ldap,dc=example,dc=com all identify f5-admin.

If the user’s memberOf attribute provides no groups, F5 Insight searches under ou=groups,<BASE_DN> using member or memberUid membership attributes. Replace <BASE_DN> with your configured Base DN. If the search base doesn’t exist, F5 Insight logs a warning that also notes the unsuccessful memberOf lookup.

Configure Active Directory

Microsoft Active Directory (AD) also uses the LDAP provider type. Follow Configuring an LDAP provider with the connection settings for your directory.

  1. Set Userbase DN to the search base that contains your AD user entries.
  2. Set User filters to your directory’s user lookup attribute. Don’t enter a full LDAP filter expression.
  3. Set User object to the object class for your AD user entries.

For Active Directory, the full user principal name (UPN) is a workaround to avoid collisions with local usernames. Set Username attribute to userPrincipalName instead of the short username attribute. User filters can still use sAMAccountName for login lookup. Verify that the resulting account username doesn’t match any local username, including admin. If there’s still a risk of collisions, don’t use local and external users together.

F5 Insight first reads the memberOf attribute on the user’s directory entry. For each group distinguished name (DN), it extracts the CN for role mapping. For example, CN=F5 Admins,CN=Users,DC=example,DC=com resolves to F5 Admins. Groups resolved through memberOf don’t need to be under ou=groups.

For role mapping, enter F5 Admins in Grouped Resource Attribute to match that group. The cn= prefix is optional, and anything after the first comma is ignored. For example, F5 Admins, cn=F5 Admins, and cn=F5 Admins,CN=Users,DC=example,DC=com all identify F5 Admins.

Matching preserves the group’s exact casing. For example, domain admins doesn’t match Domain Admins. If memberOf provides no groups, F5 Insight uses the OpenLDAP-style fallback described in Configure OpenLDAP. See Role mapping to assign roles.

Custom CA certificates for LDAP/LDAPS authentication

F5 Insight 1.2.2 lets you use custom Certificate Authority (CA) certificates to secure LDAP authentication. As an administrator, you can:

  • Upload a CA certificate or CA bundle to the Trust Store.
  • Select the uploaded CA when you configure an LDAP identity provider.
  • Validate the LDAP server certificate for LDAPS connections using the selected CA.

Warning

LDAP + StartTLS with a custom CA certificate is not functional for runtime login in this release. Use LDAPS with a custom CA instead. If your environment requires StartTLS, apply the workaround script before you configure the provider. See Known limitations.

Supported LDAP connection types

F5 Insight supports three LDAP connection types. The level of custom CA support differs for each type.

Connection type Custom CA support Notes
Plain LDAP Not required No TLS is used. A CA certificate is not needed.
LDAPS Supported Recommended for custom CA deployments. Uses port 636 by default.
LDAP + StartTLS Partial Backend validation works with a custom CA, but runtime login has known limitations. See Known limitations.

Certificate requirements

Before you upload a CA certificate, make sure it meets the following requirements.

File format

  • The certificate must be PEM encoded.
  • Accepted file extensions are .pem, .crt, or .cer (as long as the content is PEM format).
  • If your file is in DER or binary .cer format, convert it to PEM before you upload it.

Certificate chain

  • Upload the full CA bundle (root and intermediate certificates), not only the LDAP server’s leaf certificate.
  • If the LDAP server does not send its intermediate certificate chain, include the full chain in your uploaded bundle.

Server certificate matching

  • The Subject Alternative Name (SAN) in the LDAP server certificate must match the hostname in your LDAP URL.
  • If you use an IP address in the LDAP URL, the server certificate must include that IP address as an IP SAN.
  • The LDAP server must present the configured server certificate along with a matching private key.

Note

F5 Insight does not support LDAP mutual TLS or client certificate authentication.

Verify the LDAP server certificate

Before you configure F5 Insight, verify that your LDAP server’s TLS certificate is valid. Run the following OpenSSL command to test the connection:

openssl s_client \
  -connect ldap.example.com:636 \
  -servername ldap.example.com \
  -CAfile ca-bundle.pem \
  -verify_hostname ldap.example.com

Look for this result in the output:

Verify return code: 0 (ok)

If the verification fails, review the custom CA troubleshooting section before you continue.

Configure a custom CA for LDAPS

Use these steps for LDAPS connections. This is the recommended approach for custom CA deployments.

  1. Go to Authentication ‣ Identity Providers.

  2. Select an existing LDAP provider and select Edit, or select Create to add a new one.

    LDAP provider edit screen showing Edit and Create buttons

    The LDAP provider configuration screen.

  3. In the Server URL field, enter the LDAPS URL for your LDAP server.

    Use the explicit port in the URL. For example:

    ldaps://ldap.example.com:636

  4. Make sure the StartTLS checkbox is cleared.

  5. In the CA certificate section, select Upload and select your CA certificate file or full CA bundle.

  6. From the Certificate Authority dropdown, select the CA you uploaded.

  7. Select Test Connection to verify that F5 Insight can reach and validate the LDAP server.

  8. Select Save.

    Save button on the LDAP provider configuration screen

    The LDAP provider configuration screen with the Save button.

  9. Activate the provider and test an LDAP login to confirm the setup works.

Configure a custom CA for LDAP + StartTLS

Use these steps only if your environment requires StartTLS. For reliable custom CA support, LDAPS is recommended. See Known limitations.

  1. Go to Authentication ‣ Identity Providers.

  2. Select an existing LDAP provider and select Edit, or select Create to add a new one.

  3. In the Server URL field, enter the LDAP URL for your server.

    Important

    Do not include a port number in the URL. The system defaults to port 389 automatically. Adding a port causes malformed Server Name Indication (SNI) requests during the TLS upgrade.

    For example:

    ldap://ldap.example.com

  4. Select the StartTLS checkbox.

  5. In the CA certificate section, select Upload and select your CA certificate file or full CA bundle.

  6. From the Certificate Authority dropdown, select the CA you uploaded.

  7. Select Test Connection to verify that F5 Insight can reach and validate the LDAP server.

  8. Select Save.

  9. Activate the provider and test an LDAP login to confirm the setup works.

Troubleshoot custom CA certificate issues

Use this section to resolve common errors related to custom CA certificates for LDAP.

Error Cause Solution
x509: certificate signed by unknown authority The selected CA does not include the certificate that signed your LDAP server’s certificate. Upload the correct CA certificate or full CA bundle to the Trust Store. Make sure the bundle includes the root and any intermediate CAs in the trust chain.
hostname mismatch The hostname in the LDAP URL does not match any Subject Alternative Name (SAN) entry in the LDAP server certificate. Update the LDAP URL to use the hostname that appears in the server certificate’s SAN field. If neither hostname is correct, reissue the LDAP server certificate with the correct SAN.
Server presents a default container certificate (for example, CN=openldap or docker-light-baseimage) The LDAP server is still using a default container certificate instead of your issued certificate. Install the issued server certificate and its matching private key on the LDAP server. Restart the LDAP service after you replace the certificate.
EOF during LDAPS validation The LDAP server is closing the TLS connection before the handshake completes. This can happen when the server or an upstream device (such as F5 BIG-IP) requires client certificate authentication. Check the LDAP server configuration and any TLS profiles on intermediate devices. Make sure client certificate authentication is not required, because F5 Insight does not support mutual TLS for LDAP connections.
StartTLS connection refused or SNI errors The provider URL contains a port number (for example, ldap://ldap.example.com:389). Adding a port to a StartTLS URL causes malformed Server Name Indication (SNI) requests during the TLS upgrade. Remove the port number from the provider URL. Use only the hostname — for example, ldap://ldap.example.com. The system defaults to port 389 automatically.

Workaround: apply a custom CA for StartTLS

workaround.sh

#!/bin/bash
set -e

# --- Configuration Variables ---
NAMESPACE="f5-insight"
DEPLOYMENT="f5-insight-zitadel"
CONFIGMAP_NAME="ldap-custom-ca-bundle"
CERT_MOUNT_PATH="/etc/ssl/ldap-custom-certs"
CERT_ENV_VAL="/etc/ssl/certs:/etc/ssl/ldap-custom-certs"

# --- Input Validation ---
if [ -z "$1" ]; then
  echo "Error: Missing certificate file."
  echo "Usage: ./apply-zitadel-starttls-workaround.sh <path-to-custom-ca.crt>"
  exit 1
fi

CA_FILE="$1"

if [ ! -f "$CA_FILE" ]; then
  echo "Error: File '$CA_FILE' not found."
  exit 1
fi

echo "============================================================"
echo "Applying ZITADEL StartTLS Custom CA Workaround"
echo "Target Namespace: $NAMESPACE"
echo "Certificate File: $CA_FILE"
echo "============================================================"

# Step 1: Create or Update the ConfigMap
echo "[1/4] Injecting certificate into ConfigMap: $CONFIGMAP_NAME..."
kubectl create configmap $CONFIGMAP_NAME \
  -n $NAMESPACE \
  --from-file=ldap-custom-ca.crt="$CA_FILE" \
  --dry-run=client -o yaml | kubectl apply -f -

# Step 2: Patch the ZITADEL Deployment
echo "[2/4] Patching ZITADEL deployment to mount the certificate..."
NOW=$(date +%s)

kubectl patch deployment $DEPLOYMENT \
  -n $NAMESPACE \
  --type strategic \
  -p "{
    \"spec\": {
      \"template\": {
        \"metadata\": {
          \"annotations\": {
            \"f5insight.io/ldap-ca-workaround-restarted-at\": \"$NOW\"
          }
        },
        \"spec\": {
          \"containers\": [
            {
              \"name\": \"zitadel\",
              \"env\": [
                {
                  \"name\": \"SSL_CERT_DIR\",
                  \"value\": \"$CERT_ENV_VAL\"
                }
              ],
              \"volumeMounts\": [
                {
                  \"name\": \"$CONFIGMAP_NAME\",
                  \"mountPath\": \"$CERT_MOUNT_PATH\",
                  \"readOnly\": true
                }
              ]
            }
          ],
          \"volumes\": [
            {
              \"name\": \"$CONFIGMAP_NAME\",
              \"configMap\": {
                \"name\": \"$CONFIGMAP_NAME\"
              }
            }
          ]
        }
      }
    }
  }"

# Step 3: Wait for the rollout to complete
echo "[3/4] Waiting for ZITADEL pods to restart..."
kubectl rollout status deployment/$DEPLOYMENT -n $NAMESPACE --timeout=180s

echo "[4/4] Done! The workaround has been successfully applied."
echo "============================================================"
echo "Next Steps:"
echo "In the F5 Insight UI, configure your LDAP Provider:"
echo " - Server: ldap://<YOUR_LDAP_HOSTNAME> (Do NOT use custom ports)"
echo " - StartTLS: Checked"
echo " - CA: Select the same Custom CA uploaded to the Trust Store"
echo "============================================================"

Apply the workaround

Important

Complete this workaround after you upload the CA certificate and save the LDAP provider configuration in the F5 Insight UI.

  1. Connect to the F5 Insight virtual machine (VM) using SSH.

  2. Create the workaround script:

    nano workaround.sh

    Paste the script content into the editor, then save and close the file.

  3. Make the script executable:

    chmod +x workaround.sh

  4. Copy the CA certificate from your LDAP server to the F5 Insight VM.

    Use scp to transfer the file. For example:

    scp <username>@<ldap-server-ip>:<path-to-certificate>/custom-ca.crt ./custom-ca.crt

    Alternatively, create a new file on the VM and paste the certificate content directly.

  5. Run the workaround script with the path to your CA certificate:

    sudo ./workaround.sh ./custom-ca.crt

  6. Test an LDAP login to confirm that the custom CA is now used for StartTLS connections.

Known limitations for custom CA

  • Updating a CA on an existing LDAP provider: When you update the CA certificate on an existing LDAP provider, the new CA might not take effect for runtime login. The system can save the updated certificate in the provider configuration, but login requests might continue to use the previous CA.

    If a CA update does not take effect after you save the provider, delete the existing LDAP provider and create a new one with the updated CA certificate.

  • LDAP + StartTLS with custom CA: Backend validation can use the selected custom CA, but runtime login has known limitations with the current identity management component. For reliable custom CA support, use LDAPS instead of LDAP + StartTLS. If your environment requires StartTLS, apply the workaround script.

OpenLDAP configuration notes and sample LDIF expectations

The following values represent the expected LDAP entry patterns used by OpenLDAP deployments similar to the sample data used for F5 Insight validation.

Expected user object classes and attributes

User entries are expected under a people container such as ou=People,dc=ldap,dc=example,dc=com with object classes:

  • person
  • organizationalPerson
  • inetOrgPerson

Common user attributes expected by provider mapping:

  • uid: login identifier (for example, adminuser)
  • mail: email address
  • cn: display name
  • givenName: first name
  • sn: last name
  • userPassword: LDAP bind password hash

Expected group object classes and attributes

Group entries are expected under a groups container such as ou=Groups,dc=ldap,dc=example,dc=com.

Dual-compatible group entries can include both:

  • groupOfUniqueNames with uniqueMember DN values
  • posixGroup with gidNumber and memberUid values

This supports both DN-based and POSIX username-based membership lookup.

Sample LDIF entry shapes

dn: uid=adminuser,ou=People,dc=ldap,dc=example,dc=com
 objectClass: person
 objectClass: organizationalPerson
 objectClass: inetOrgPerson
 uid: adminuser
 mail: adminuser@ldap.example.com
 cn: Addy Ministrator
 givenName: Addy
 sn: Ministrator
 userPassword: {SSHA}<hash>

dn: cn=admin,ou=Groups,dc=ldap,dc=example,dc=com
 objectClass: groupOfUniqueNames
 objectClass: posixGroup
 cn: admin
 gidNumber: 10002
 uniqueMember: uid=adminuser,ou=People,dc=ldap,dc=example,dc=com
 memberUid: adminuser

Associated OpenLDAP search commands

Use these commands to validate expected directory content and group mapping behavior.

# Base user lookup by uid
ldapsearch -x -H ldap://localhost \
 -b ou=People,dc=ldap,dc=example,dc=com \
 -D "cn=admin,dc=ldap,dc=example,dc=com" -w <password> \
  "(uid=adminuser)" dn uid mail cn givenName sn

# Inspect one group and verify dual object classes and membership attributes
ldapsearch -x -H ldap://localhost \
 -b ou=Groups,dc=ldap,dc=example,dc=com \
 -D "cn=admin,dc=ldap,dc=example,dc=com" -w <password> \
  "(cn=admin)" dn objectClass gidNumber uniqueMember memberUid

# POSIX-style group membership query
ldapsearch -x -H ldap://localhost \
 -b ou=Groups,dc=ldap,dc=example,dc=com \
 -D "cn=admin,dc=ldap,dc=example,dc=com" -w <password> \
  "(memberUid=adminuser)" dn cn

# Dual-mode membership query (DN-based OR POSIX-style)
ldapsearch -x -H ldap://localhost \
 -b ou=Groups,dc=ldap,dc=example,dc=com \
 -D "cn=admin,dc=ldap,dc=example,dc=com" -w <password> \
 "(|(uniqueMember=uid=adminuser,ou=People,dc=ldap,dc=example,dc=com)(memberUid=adminuser))" dn cn

Test the LDAP connection

Note

Editing an LDAP provider: LDAP edit configuration requires a password to enable the test connection button.

Note

The Test Connection option is available for LDAP providers only. It validates the LDAP connection and retrieves the available LDAP groups.

For Active Directory, connection validation and runtime group lookup suppress LDAP referral continuations so that searches under the domain root do not stall on referrals. LDAP operations have a 30-second timeout. An operation that exceeds this limit returns a timeout error. This limit applies to individual operations, not the entire Test Connection workflow.

LDAP login

  1. Navigate to the F5 Insight login page.
  2. Select Sign in with <LDAP Provider Name> (for example, Log in with <LDAP Provider Name>).
  3. You are redirected to the LDAP credential screen.
  4. Enter your LDAP username and password.
  5. Upon successful authentication, you are redirected to the F5 Insight dashboard with permissions based on your assigned role.

Example - OpenLDAP role mapping

OpenLDAP user Group name F5 Insight role Access level
john.smith f5-admin Admin Full access including User Administration
jane.doe f5-operator Operator Operational access, no User Administration
bob.wilson f5-viewer Viewer Read-only access
new.user (not configured) None Access denied

Example - Active Directory role mapping

For a user whose memberOf attribute contains CN=F5 Admins,CN=Users,DC=example,DC=com, set Grouped Resource Attribute to F5 Admins. Map that group to Admin. You can also enter cn=F5 Admins or cn=F5 Admins,CN=Users,DC=example,DC=com. The prefix is optional, and anything after the first comma is ignored. Matching remains case-sensitive, so f5 admins doesn’t match F5 Admins.

To grant read-only access to another AD group, create a separate mapping from that group’s exact CN to Viewer. Without a matching role mapping, access is blocked.