User Accounts from LDAP
TODO: proof-read and test
This document describes how to configure the LDAP integration for Tetrate Service Express (TSE). LDAP integration in TSE allows you to use LDAP as an Identity Provider for user login to TSE, as well as synchronizing users and groups from LDAP to TSE automatically.
This document assumes that you already have working knowledge of configuring an LDAP service, as well as how to authenticate using it.
LDAP can be configured through
ManagementPlane CR or Helm values. Following is an example of custom resource YAML that uses LDAP as TSE Identity Provider. You will need to edit the
ManagementPlane CR or the Helm values and configure the relevant sections. Please refer to
LDAPSettings for more details.
The following sections will explain more about what each part of the YAML file means.
Identity Provider Configuration
There are two ways of using LDAP as an Identity provider:
- Using Direct Bind Authentication
- Using a Search based Authentication
Using the Direct Bind Authentication is preferred as performance is better, but it requires user Distinguished Names ("DN"s) to be uniform across the entire LDAP tree. If this is not the case, a more flexible Search Based Authentication can be configured to authenticate users based on pre-configured queries.
These approaches are not mutually exclusive. If both are configured, the Direct Bind Authentication will be attempted first and if users cannot be authenticated, TSE will fallback to using the Search based Authentication.
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. 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 like
uid=nacx,ou=People,dc=tetrate,dc=io. This format is not convenient for regular logins, as users shouldn't be asked to type the full DN in a login form. Direct Bind Authentication allows you 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:
In this example, upon log in, the
%s in the pattern will be replaced by the provided login user, and the resulting DN will be used for the bind authentication.
Search based authentication
As previously explained, 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 could be created inside a group for a specific department within the organization) making it impossible to have one single pattern to match them all.
In this case, you can perform a search on the LDAP tree looking for a record that matches the given username, then attempt a bind authentication with the DN of the record.
In order to perform the search, a connection must be established to the LDAP server. This may require credentials if the server is not configured with anonymous access. Please refer to the "Credential and Certificate" section for more details.
The following example shows how to configure the Search based authentication:
In this example a search is configured to lookup the tree starting at
iam.matchFilter uses the query defined in
search.baseDN). And will attempt to match all records that are of type
person and with the
uid attribute equal to the given username. Similar to Direct Bind Authentication, the Search pattern expects a
%s placeholder that will be replaced by the given username.
Combining direct and search authentication methods
It is possible to combine both authentication methods, to configure a more flexible authentication configuration. When both methods are configured, Direct Bind Authentication will have precedence, as it does not require a traversal of the LDAP tree, and is therefore more efficient.
An example that uses both authentication strategies might look like the following
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:
Credential and Certificate
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.
You can use
tctl install manifest management-plane-secrets to create required credentials and certificates to connect to your LDAP server.
tctl install manifest management-plane-secrets \
--ldap-bind-dn <ldap-bind-dn> \
--ldap-bind-password <ldap-bind-password> \
--ldap-ca-certificate "$(cat ldap-ca.cert)" \
--tsb-admin-password <tsb-admin-password> \
--tsb-server-certificate "$(cat foo.cert)" \
--tsb-server-key "$(cat foo.key)" > managementplane-secrets.yaml
If you cannot use the above command and need to do this manually, create
ldap-credentials secret as follows
binddn: 'base64-encoded full DN of the user to use to authenticate'
bindpassword: 'base64-encoded password'
Also create a
custom-host-ca secret if your LDAP is configured to present a self-signed certificate.
kubectl create secret generic custom-host-ca \
--from-file=ca-certificates.crt=<path to custom CA file> \
User and group synchronization
User and group synchronization is done by running the sync queries in the LDAP configuration above. 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.