LDAP certificate provider

Prev Next

This section describes how AppGate ZTNA works with LDAP certificate identity providers (IdPs).

AppGate ZTNA supports standard enterprise IdPs such as Active Directory (Entra ID). These IdPs authenticate users who connect through the client and administrators who sign in to the Controller Management interface.

By specifying multiple LDAP servers, AppGate ZTNA selects one at random, providing LDAP load balancing and failover.


Prerequisites for an LDAP certificate provider

Configure your LDAP server for encrypted communication. If SSL is enabled and the LDAP server has a valid certificate, the Controller automatically establishes an encrypted session with the directory server.


Shortening lookup times with an LDAP certificate provider

If an AppGate system relies on Active Directory (AD) group memberships, perform an audit of both user and machine group memberships before deployment. This audit helps clean up the directory structure and optimizes lookup performance.

Why lookup times matter

Lookup times directly affect authentication behavior:

  • The Controller waits up to five seconds for a response from the LDAP server.

  • If multiple LDAP servers are configured, the Controller moves to the next server after five seconds.

  • If only one LDAP server is configured, the Controller waits up to ten seconds.

  • Headless clients retry sign-in continuously until authentication succeeds.

In environments with many headless clients, repeated retries can flood Controllers with sign-in requests, which compounds any latency or availability issues in the directory servers.

Reducing lookup times through IdP configuration

To keep lookup times as short as possible, fully configure the identity provider. Specifically, use the Base DN, Membership Base DN, and Membership Filter fields to limit the scope of LDAP searches.

If these fields are not configured, LDAP searches span the entire directory tree, significantly increasing lookup time.

  • Base DN. Defines the portion of the LDAP tree that contains users. It may also include user groups, but the smaller the Base DN, the better the lookup performance.

  • Membership Base DN. Defines the portion of the LDAP tree that includes user groups. After a user is authenticated, the Controller performs a second LDAP query using this value to identify group memberships. If nothing is defined in this field, the Controller uses the Base DN.

  • Membership Filter. Further restricts the group search. Any filter configured here is concatenated with the search base and applied during the Controller’s group lookup query. Using a Membership Filter limits the number of objects evaluated, which helps reduce lookup times even further.

Group resolution behavior

How group membership is resolved depends on how Base DN is defined:

  • If Base DN includes only users, group membership is derived solely from the user record. For example:

    • The user record might list only sweden-sales

    • Nested group relationships, such as sweden-sales > sales > commercial, are not discovered.

  • If Base DN includes both users and groups, group membership is derived from group records.

    • The user is correctly identified as a member of sweden-sales, sales, and commercial.

Using Membership Base DN for performance and accuracy

Using Membership Base DN allows the Base DN to be minimized, which reduces the scope of the initial user search and shortens lookup times. Group searches are then performed against Membership Base DN, ensuring that all relevant group memberships— including nested groups—are returned.

This approach also reduces the scope of the second group lookup, further improving performance.

Using mulitple IdPs to shorten lookup times

The use of multiple IdPs can also minimize lookup times. If you have two different classes of users, such as human users with full clients and headless clients, you can create two different IdPs and use different Base DN, Membership Filter, and/or Membership Base DN values against an optimized tree structure. If your users were everywhere but the headless client users were recently added, then a filter like objectCategory=appgate-headless.* could be used.

The following is an example of an LDAP configuration:

Configuration settings for user filters and membership for an LDAP Certificate identity provider.


Certificate Prerequisites

AppGate ZTNA requires an RSA-based certificate that meets the following requirements:

  • Includes the clientAuthentication extended key usage extension.

  • Includes a valid subjectAlternativeName field.

  • Incluides the private key.

AppGate ZTNA supports hardware-based and soft certificates, as long as both use the standard Windows certificate storage system. All certificates must be stored in Certificates - Current User > Personal > Certificates.

The following example shows two valid certificates with the correct Intended Purpose: one smartcard-based certificate and one locally-stored soft certificate.

Certificate details for User1, including expiration date and intended purposes listed.


Authentication with an LDAP certificate provider

When you sign in with a certificate IdP, the client displays a list of valid certificates. This works as follows:

  • Admin UI sign-in. Select the LDAP Certificate provider from the identity provider list. The sign-in attempt uses the certificate selected previously.

  • Client sign-in. When the client profile specifies a certificate IdP, AppGate ZTNA signs in using the certificate selected previously. The Controller maps attributes based on the subjectAlternativeName field to populate user claims and issue claims and entitlement tokens.

  • Claims token renewal. When the user's claims token expires, the client renews it automatically using the cached certificate selection. This is transparent to the user.

  • Password user interaction. The password user interaction works for LDAP certificate (despite the name). When this user interaction is triggered, the user must select OK in the message, as long as the certificate is still present and valid. If the certificate has a PIN, the user must reenter it. After completion, the user is allowed access to the entitlement. You can also use this method when setting up the Linux headless client.