LDAP Configuration

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.

Configuration overview

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 ldap-config ConfigMap.

Here is an example of the LDAP ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: ldap-config
  namespace: tcc
data:
  config.yaml: |
    server:
      host: ldap
      port: 389
      tls: false
    search:
      basedn: dc=tetrate,dc=io
      recursive: true
    iam:
      matchdn: "cn=%s,ou=People,dc=tetrate,dc=io"
      matchfilter: "(&(objectClass=person)(uid=%s))"
    sync:
      usersfilter: "(objectClass=person)"
      groupsfilter: "(objectClass=groupOfUniqueNames)"
      membershipattribute: uniqueMember

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 follows:

apiVersion: v1
kind: Secret
metadata:
  name: ldap-credentials
  namespace: tcc
data:
  binddn: 'base64-encoded full DN of the user to use to authenticate'
  bindpassword: 'base64-encoded password'

Configuration details

Here are detailed descriptions of every field in the LDAP configuration file:

Connection

The connection to the LDAP Server is configured as follows:

server:
host: ldap.default.svc.cluster.local
port: 389
tls: false

The server element is mandatory, and has the following fields:

Field	Type	Description	Required	Default
host	String	The address of the LDAP server	Yes	-
port	Integer	The port where the LDAP server is listening	Yes	-
tls	Boolean	Whether TLS will be used to connect to the LDAP server	No	false

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> \
    --namespace tcc

Search configuration

LDAP search configuration is done in the search section. It is mandatory and configures all the queries that are executed against the LDAP server.

search:
  basedn: dc=tetrate,dc=io
  recursive: true
  timeout: 2m

The following fields configure the user and group search queries:

Field	Type	Description	Required	Default
basedn	String	DN of the node where the lookup will start	Yes	-
recursive	Boolean	Flag to configure if the lookup should be recursive	No	false
timeout	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.

The 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.

sync:
  usersfilter: '(objectClass=person)'
  groupsfilter: '(objectClass=groupOfUniqueNames)'
  membershipattribute: uniqueMember

The following fields configure the user and group search queries:

Field	Type	Description	Required	Default
usersfilter	String	LDAP search filter used to match user records	Yes	-
groupsfilter	String	LDAP search filter used to match group records	Yes	-
membershipattribute	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: uid=nacx,ou=People,dc=tetrate,dc=io, 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 DN.

The following example configures a Direct Bind Authentication pattern:

iam:
  matchdn: 'uid=%s,ou=People,dc=tetrate,dc=io'

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 authentication.

Field	Type	Description	Required	Default
matchdn	String	Pattern to create the DN used to authenticate, with a %s placeholder to be replaced by the given username	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:

iam:
  matchfilter: '(&(objectClass=person)(uid=%s))'

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 uid 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 username.

Field	Type	Description	Required	Default
matchfilter	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:

iam:
  matchdn: 'uid=%s,ou=People,dc=tetrate,dc=io'
  matchfilter: '(&(objectClass=person)(uid=%s))'

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: user@domain).

Since this is the username that is likely to be configured in a login form, direct authentication could be simply configured as follows:

iam:
  matchdn: '%s'

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:

iam:
  matchfilter: '(&(objectClass=user)(samAccountName=%s))'