LDAP authentication
Currently, Vitess supports two ways to authenticate to vtgate
via the MySQL protocol:
- Static : You provide a static configuration file to
vtgate
with user names and plaintext passwords ormysql_native_password
password hashes. This file can be reloaded without restartingvtgate
. Further details can be found here. - LDAP : You provide the necessary details of an upstream LDAP server, along with credentials and configuration, to query it. Using this information, the LDAP passwords for a user can then be used to authenticate the same user against
vtgate
. You can also integrate with LDAP groups to allow ACLs to be managed using information from the LDAP server.
In this guide, we will examine the capabilities of the vtgate
LDAP integration and how to configure them.
Requirements #
There are a few requirements that are necessary for the vtgate
LDAP integration to work:
- The communication between
vtgate
and the LDAP server has to be encrypted. - Encrypted communication to LDAP has to be via LDAP over TLS (STARTTLS) and not via LDAP over SSL (LDAPS). The latter is not a standardized protocol and is not supported by Vitess. Ensure that your LDAP server and the LDAP URI (hostname/port) that you provide supports STARTTLS.
- The application MySQL protocol connections to
vtgate
that use LDAP usernames/passwords need to use TLS. This is required because of the next point, but can be bypassed. We strongly DO NOT recommend doing this. - The application needs to be able to, and configured to, pass its password authentication using the cleartext MySQL authentication protocol. This is why it is required that the MySQL connection to
vtgate
be encrypted first. This is required because LDAP servers do not standardize their password hashes and, as a result, a cleartext password is required byvtgate
to bind (i.e. authenticate) against the LDAP server to verify the user's password. Note that some applications might not support passing cleartext MySQL passwords without alteration or configuration. An example is recent versions of the MySQL CLI clientmysql
need the additional--enable-cleartext-plugin
option to allow the passing of cleartext passwords.
Configuration #
To configure vtgate
to integrate with LDAP you will have to perform various tasks:
- Generate/obtain TLS certificate(s) for the
vtgate
server(s), and configurevtgate
to use them. Further details can be found here. - Obtain or add the necessary LDAP user/groups for integration with
vtgate
. In general, you will need:- LDAP user entries for each of the MySQL users you want to use at the
vtgate
level. An example might be a readonly user, a readwrite user, and an admin/DBA user. - Ensure these users are part of one or more LDAP groups. This is not strictly required by Vitess, but is leveraged to obtain group membership that can then be used in Vitess (
vttablet
)ACLs. At the moment if you use an LDAP user that is not a member of an LDAP group, the MySQL client authentication tovtgate
will fail, even if the password is correct.
- LDAP user entries for each of the MySQL users you want to use at the
- As mentioned above, you also need to have:
- Your LDAP server setup for STARTTLS
- Obtained the LDAP URI to connect to the LDAP server
- The CA certificate, that your LDAP server TLS certificate is signed by, in PEM format
- Make sure that you are accessing the LDAP server via a hostname or IP SAN that is defined in your LDAP server TLS certificate. If not, you will not be able to use your LDAP server as-is from
vtgate
.
Once you have your prerequisites above ready, you can now construct your JSON configuration file for vtgate
using the command line parameter -mysql_ldap_auth_config_file
. The content of this file is a JSON format object with string key/value members as follows:
{
"LdapServer": "ldapserver.example.org:389",
"LdapCert": "path/to/ldap-client-cert.pem",
"LdapKey": "path/to/ldap-client-key.pem",
"LdapCA": "path/to/ldap-server-ca.pem",
"User": "cn=admin,dc=example,dc=org",
"Password": "adminpassword!",
"GroupQuery": "ou=groups,ou=people,dc=example,dc=org",
"UserDnPattern": "uid=%s,ou=users,ou=people,dc=example,dc=org",
"RefreshSeconds": 300
}
Not all these options are necessary in all configurations. Here are what each key/value option represents:
- LdapServer : Hostname/IP and port to access the LDAP server via using STARTTLS. Note that as mentioned above, this needs to match the server TLS certificate presented by the LDAP server. This is required.
- LdapCert : Path to the local file that contains the PEM format TLS client certificate that you want to present to the LDAP server. This is optional unless you use client-certificates with the LDAP server. If you are using this option,
LdapKey
is also required. - LdapKey : Path to the local file that contains the PEM format TLS private key for the client certificate you want to present to the LDAP server. This is optional unless you use client-certificates with the LDAP server. If you are using this option,
LdapCert
is also required. - LdapCA : Path to the local file that contains the PEM format TLS CA certificate to verify against the TLS server certificate presented by the LDAP server. This is required.
- User : DN of the LDAP user you will be authenticating to the LDAP server to read information such as group membership. Required, unless you are using LDAP client certificates to authenticate to the LDAP server. If you are using this option,
Password
option is also required. - Password : Cleartext password for the LDAP user specified above in
User
. This is required, unless you are using LDAP client certificates to authenticate to the LDAP server. If you are using this option,User
option is also required. - GroupQuery : LDAP base DN from which to start the group membership query to establish the group of which the
User
specified (or implied via the client certificate) is a member. The group membership query itself is hardcoded to the LDAP query filter of(memberUid=%s)
where%s
is the authenticating username. This is required. - UserDnPattern : LDAP DN pattern to autofill with MySQL username passed during MySQL client authentication to
vtgate
. This DN is then used, along with the password provided tovtgate
, to attempt to bind with the LDAP server. If the bind is successful, you know that the password provided tovtgate
was valid. This is required. - RefreshSeconds : Number of seconds that you should cache individual LDAP credentials for in-memory at the
vtgate
. This is used to reduce load on the LDAP for high traffic MySQL servers. As well as to avoid short LDAP server outages from causing Vitess/vtgate
authentication outages. Default value is 0, which means do not cache. For production it is recommended to set this value to something reasonably high, for example at least a few minutes. This is optional.
Note that vtgate
only does very basic validation of the values passed here and that incorrect configurations may just fail at runtime. If you are lucky, relevant errors may be logged by vtgate
, but in many cases incorrect configuration will just result in a vtgate
instance that you cannot log into via the MySQL protocol.
For debugging this, it is useful to have access to the logs from your LDAP server that you are pointing to. The logs would preferably be at trace or debug level, so that you can see each LDAP bind and search operation against the LDAP server as you are testing.
Once you have constructed the above file, you will need to remove any options that references static authentication from your vtgate
command line such as:
-mysql_auth_server_static_file
-mysql_auth_server_static_string
-mysql_auth_static_reload_interval
-mysql_auth_server_impl static
and add the following new options:
-mysql_auth_server_impl ldap -mysql_ldap_auth_config_file /path/to/ldapconfig.json