This document describes how to configure the LDAP integration for Tetrate Service Bridge (TSB).
LDAP integration in TSB provides the following main features:
- LDAP as an Identity Provider to leverage user login to TSB.
- Synchronization of the users and groups from LDAP to TSB.
LDAP is configured in a single file that is mounted by the different services
that need to access it. The file is usually stored in the
Here is an example of the LDAP ConfigMap:
Some operations require running privileged queries against the LDAP server,
such as fetching the entire group and user list, or authenticating users using
a search. In those cases, if credentials are needed they must be configured in
a Kubernetes Secret. By default the
ldap-credentials secret is created as
binddn: 'base64-encoded full DN of the user to use to authenticate'
bindpassword: 'base64-encoded password'
Here are detailed descriptions of every field in the LDAP configuration file:
The connection to the LDAP Server is configured as follows:
The server element is mandatory, and has the following fields:
|String||The address of the LDAP server||Yes||-|
|Integer||The port where the LDAP server is listening||Yes||-|
|Boolean||Whether TLS will be used to connect to the LDAP server||No|
Using a custom CA
When using TLS connections, you may need to configure a custom CA. That can be done
by creating the
custom-host-ca secret in the namespace where the TSB management plane
is installed (
tsb by default) as follows:
kubectl create secret generic custom-host-ca \
--from-file=ca-certificates.crt=<path to custom CA file> \
LDAP search configuration is done in the
search section. It is mandatory and
configures all the queries that are executed against the LDAP server.
The following fields configure the user and group search queries:
|String||DN of the node where the lookup will start||Yes||-|
|Boolean||Flag to configure if the lookup should be recursive||No|
|String||String representing a time duration||No||0 (max timeout)|
User and group synchronization
User and group synchronization is done by running the corresponding queries. The following example shows two example queries that can be used to get users and groups from a standard LDAP server.
membershipattribute is used to match users with the groups they belong to.
For every found group, this attribute will be read to extract the information
of the members of the group.
Note that the queries are highly dependent on the LDAP tree structure and everyone will have to change them to match it.
The following fields configure the user and group search queries:
|String||LDAP search filter used to match user records||Yes||-|
|String||LDAP search filter used to match group records||Yes||-|
|String||Name of the attribute in group records that configures membership||Yes||-|
Identity Provider Configuration
There are two ways of using LDAP as an Identity provider:
- Using Direct Bind Authentication
- Using a Search based Authentication
It is preferred to use the direct bind authentication, as performance is better,
but it requires user
DNs to be uniform across the entire LDAP tree. Is this is
not the case, a more flexible search based authentication can be configured to
authenticate users based on a configured query.
Both approaches are not exclusive, though. If both are configured, the Direct Bind Authentication will be attempted first and fallback to the Search based Authentication if users cannot be authenticated directly.
Direct Bind Authentication
Authentication in LDAP is done by performing a bind operation against a DN. The DN is expected to be a user record that has a password configured, and the bind operation tries to match the given DN and password with an existing record. Authentication succeeds if the binding operation succeeds.
DNs, however, are commonly in the form:
but this format is not convenient for regular logins, as users shouldn't be
asked to type the full DN in a login form. Instead, the direct authentication
allows to configure a pattern to match the login user against, and use that as
The following example configures a Direct Bind Authentication pattern:
In this example, upon login, the
%s in the pattern will be replaced by the
provided login user, and the resulting DN will be used for the bind
|String||Pattern to create the DN used to authenticate, with a ||Yes||-|
Search based authentication
Direct bind authentication works fine if all users that exist can be matched against the same DN pattern. In some cases, however, users might be created in different parts of the LDAP tree (for example, each user is created inside a group for a specific department of the organization) making it impossible to have one single pattern to match them all.
In this case, the approach is perform a search on the LDAP tree looking for record that matches the given username, then attempt a bind authentication with the DN of the found record.
In order to perform the search, a connection must be established to the LDAP server, and that may require credentials if the server is not configured with anonymous access. A pattern that is commonly used is to have a read-only user that can be used to perform these authentication look ups.
The following example shows how to configure the Search based authentication:
In this example a search is configured to lookup the tree starting at
dc=tetrate,dc=io. Credentials are provided to perform the lookup, and a search
filter that will match all records that are of type
person and have the
attribute equal to the given username. Similar to the Direct Auth pattern, the
Search pattern expects a
%s placeholder that will be replaced by the given
|String||LDAP search filter used to match a record for the desired user with a %s placeholder to be replaced by the given username||Yes||-|
Combining direct and search authentication methods
It is possible to combine both authentication methods, to have a more flexible
authentication configuration. When both methods are configured, the
direct bind authentication will have precedence, as it is more efficient because it
does not have to traverse the LDAP tree.
Here is a complete example that uses both authentication strategies:
Using Microsoft Active Directory
Microsoft Active Directory implements the LDAP bind authentication in a
different way. Instead of using a full DN for the LDAP bind operation, it uses
the user (which should be in the form:
Since this is the username that is likely to be configured in a login form, direct authentication could be simply configured as follows:
Search based authentication in Active Directory can be configured with the following filter, that matches the standard way of identifying user accounts in AD, in case Direct authentication does not cover all the authentication needs: