LDAP authentication in YSQL

• YSQL
• YCQL

The LDAP authentication method is similar to the password method, except that it uses LDAP to verify the password. Therefore, before LDAP can be used for authentication, the user must already exist in the database (and have appropriate permissions).

LDAP Authentication can be enabled in the YugabyteDB cluster by setting the LDAP configuration with the --ysql_hba_conf_csv flag.

YugabyteDB supports simple bind and search + bind modes for LDAP authentication.

Simple bind mode

In simple bind mode, YB-TServer binds to the Distinguished Name ("DN") constructed with "prefix username suffix" format. The following is an example using simple bind mode:

--ysql_hba_conf_csv='host all yugabyte 127.0.0.1/0 password,"host all all 0.0.0.0/0 ldap ldapserver=ldap.yugabyte.com ldapprefix=""uid="" ldapsuffix="", ou=DBAs, dc=example, dc=com"" ldapport=389"'

Configurations

The following configurations are supported for simple bind mode:

Search + bind mode

In search + bind mode, YB-Tserver binds to the LDAP directory with a fixed username and password, specified with ldapbinddn and ldapbindpasswd, and performs a search for the user trying to log into the database. This mode is commonly used by LDAP authentication schemes in other software.

For searching the LDAP directory, if no fixed user name and password is configured on the YB-TServer, an anonymous bind will be attempted to the directory. The search is performed over the subtree at ldapbasedn, and tries to do an exact match of the attribute specified in ldapsearchattribute. When the user is found, the server disconnects and rebinds to the directory as this user via the password specified by the client to verify that the login is correct.

The following is an example of search + bind mode:

--ysql_hba_conf_csv='host all yugabyte 127.0.0.1/0 password,"host all all 0.0.0.0/0  ldap ldapserver=ldap.yugabyte.com ldapbasedn=""dc=yugabyte, dc=com"" ldapsearchattribute=uid"'

Configurations

The following configurations are supported for search + bind mode:

Create secrets for Kubernetes

In Kubernetes, you can create secrets with sensitive information in the namespace where you are running YugabyteDB. Later, when creating universe pods, you can refer to those secrets in environment variables to use in configuring LDAP.

To create a secret:

1. Kubernetes expects secret data to be in base64 format. Run the following command in a shell to convert a password into base64 format:

   printf 'PASSWORD' | base64
   

   Replace PASSWORD with your password.

2. Add the following contents to a YAML file:

   apiVersion: v1
   kind: Secret
   data:
     <KEY_NAME>: <Base64_password>
   metadata:
     annotations:
     name: <SECRET_NAME>
   type: Opaque
   

   Replace Base64 password with the base64 password you generated.

   Provide a key name and secret name.

3. Execute the following command to create the secret in the namespace running YugabyteDB:

   kubectl apply -n <namespace> -f <path-to-yaml-file>
   

   Replace namespace with the namespace running YugabyteDB. Replace path-to-yaml-file with the full path to the YAML file you created in the preceding step.

4. To use the secret for LDAP in a universe in YugabyteDB Anywhere, create the provider and add the following override configuration:

   tserver:
     secretEnv:
     - name: YSQL_LDAP_BIND_PWD_ENV
       valueFrom:
         secretKeyRef:
           key: <KEY_NAME>
           name: <SECRET_NAME>
   

   Where YSQL_LDAP_BIND_PWD_ENV is the name of the environment variable assigned to the Kubernetes secret, and KEY_NAME and SECRET_NAME are the values you assigned when creating the secret.

   Any universe that you create with this provider can use the secret for the LDAP password. The secret can include multiple key-value pairs; only the specific key's value is passed as the LDAP password.

   Note that this provider only works if the namespace entered in the Namespace field is user-created; namespaces auto-generated by YugabyteDB Anywhere are not supported.

Example configuration

To use LDAP password authentication on a new YugabyteDB cluster, follow these steps:

1. Start the YugabyteDB cluster using the --ysql_hba_conf_csv configuration flag to enable LDAP authentication on YB-TServer.

   Use the following configuration to start the cluster:

   --ysql_hba_conf_csv='host all yugabyte 127.0.0.1/0 password,"host all all 0.0.0.0/0 ldap ldapserver=ldap.forumsys.com ldapprefix=""uid="" ldapsuffix="", dc=example, dc=com"" ldapport=389"'
   

   Note

   This sample configuration uses an online LDAP test server to set up the LDAP authentication with YugabyteDB.

   For convenience, the configuration uses two host-based authentication rules:

   • The first rule host all yugabyte 127.0.0.1/0 password allows access from localhost (127.0.0.1) to the admin user (yugabyte) with password authentication. This allows the administrator to log in to set up the roles (and permissions) for LDAP users.
   • The second rule configures LDAP authentication for all other user/host pairs, using simple bind with a uid-based username (ldapprefix) and a suffix defining the domain component (dc).

2. Start the YSQL shell (ysqlsh) specifying the yugabyte user, and enter the password (default is yugabyte) when prompted.

   $ ./ysqlsh -U yugabyte -W
   

   ysqlsh (11.2-YB-2.3.3.0-b0)
   Type "help" for help.
   
   yugabyte=#
   

3. To display the current values in the ysql_hba.conf file, run the following SHOW statement to get the file location:

   yugabyte=# SHOW hba_file;
   

                        hba_file
   -------------------------------------------------------
    /Users/yugabyte/yugabyte-data/node-1/disk-1/pg_data/ysql_hba.conf
   (1 row)
   

4. View the file. The ysql_hba.conf file should have the following configuration:

   # This is an autogenerated file, do not edit manually!
   host all yugabyte 127.0.0.1/0 trust
   host all all      0.0.0.0/0  ldap ldapserver=ldap.forumsys.com ldapprefix="uid=" ldapsuffix=", dc=example, dc=com" ldapport=389
   

5. Configure database role(s) for the LDAP user(s). The following commands create a ROLE for user riemann supported by the test LDAP server:

   yugabyte=# CREATE ROLE riemann WITH LOGIN;
   yugabyte=# GRANT ALL ON DATABASE yugabyte TO riemann;
   

6. Connect using LDAP authentication.

   Connect via ysqlsh using the riemann LDAP user and password specified in the Online LDAP Test Server page.

   $ ./ysqlsh -U riemann -W
   

   You can confirm the current user by running the following command:

   yugabyte=# SELECT current_user;
   

    current_user
   --------------
    riemann
   (1 row)