Project: YugabyteDB (App Definition and Development / Database)
File: ldap-authentication-ysql.md

title: LDAP authentication in YSQL headerTitle: LDAP authentication in YSQL linkTitle: LDAP authentication description: Configuring YugabyteDB to use an external LDAP authentication service using YSQL. menu: v2.18: identifier: ldap-authentication-1-ysql parent: authentication weight: 732 type: docs <ul class="nav nav-tabs-alt nav-tabs-yb"> <li > <a href="../ldap-authentication-ysql/" class="nav-link active"> <i class="icon-postgres" aria-hidden="true"></i> YSQL </a> </li> <li > <a href="../ldap-authentication-ycql/" class="nav-link"> <i class="icon-cassandra" aria-hidden="true"></i> YCQL </a> </li> </ul> 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 flag. YugabyteDB supports simple bind and search + bind modes for LDAP authentication. 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: ```sh --ysqlhbaconf_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"' ``` The following configurations are supported for simple bind mode: | T-Server flag | Default value | Description | | : | : | :- | | `ldapserver` | (empty) | Names or IP addresses of LDAP servers to connect to. Separate servers with spaces. | | `ldapport` | 389 | Port number on LDAP server to connect to. | | `ldapscheme` | (empty) | Set to `ldaps` to use LDAPS. This is a non-standard way of using LDAP over SSL, supported by some LDAP server implementations. See also the `ldaptls` option for an alternative. | | `ldaptls` | 0 | Set to 1 to make the connection between PostgreSQL and the LDAP server use TLS encryption. | | `ldapprefix` | (empty) | String to be prepended to the user name when forming the DN for binding to the LDAP server. | | `ldapsuffix` | (empty) | String to be appended to the user name when forming the DN for binding to the LDAP Server. | 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

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: ```sh --ysqlhbaconf_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"' ``` The following configurations are supported for search + bind mode: | T-Server flag | Default value | Description | | : | : | :- | | `ldapserver` | (empty) | Names or IP addresses of LDAP servers to connect to. Separate servers with spaces. | | `ldapport` | 389 | Port number on LDAP server to connect to. | | `ldapscheme` | (empty) | Set to `ldaps` to use LDAPS. This is a non-standard way of using LDAP over SSL, supported by some LDAP server implementations. See also the `ldaptls` option for an alternative. | | `ldaptls` | 0 | Set to 1 to make the connection between PostgreSQL and the LDAP server use TLS encryption. | | `ldapbasedn` | (empty) | Specifies the base directory to begin the user name search | | `ldapbinddn` | (empty) | Specifies the username to perform the initial search when doing search + bind authentication | | `ldapbindpasswd` | (empty) | Password for username being used to perform the initial search when doing search + bind authentication | | `ldapsearchattribute` | `uid` | Attribute to match against the username in the search when doing search + bind authentication. If no attribute is specified, the uid attribute is used. | | `ldapsearchfilter` | (empty) | The search filter to use when doing search + bind authentication. | | `ldapurl` | (empty) | An RFC 4516 LDAP URL. This is an alternative way to write LDAP options in a more compact and standard form. | 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: Kubernetes expects secret data to be in base64 format. Run the following command in a shell to convert a password into base64 format: ```sh printf 'PASSWORD' | base64 ``` Replace PASSWORD with your password. Add the following contents to a YAML file: ```yaml apiVersion: v1 kind: Secret data: <KEYNAME>: <Base64password> metadata: annotations: name: <SECRET_NAME> type: Opaque ``` Replace `Base64 password` with the base64 password you generated. Provide a key name and secret name. Execute the following command to create the secret in the namespace running YugabyteDB: ```sh kubectl apply -n <namespace> -f <path-to-yaml-file> ``` Replace namespace with the namespace running

Replace `path-to-yaml-file` with the full path to the YAML file you created in the preceding step. To use the secret for LDAP in a universe in YugabyteDB Anywhere, and add the following override configuration: ```yml tserver: secretEnv: name: YSQLLDAPBINDPWDENV valueFrom: secretKeyRef: key: <KEY_NAME> name: <SECRET_NAME> ``` Where `YSQLLDAPBINDPWDENV` is the name of the environment variable assigned to the Kubernetes secret, and KEYNAME and SECRETNAME 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. To use LDAP password authentication on a new YugabyteDB cluster, follow these steps: Start the YugabyteDB cluster using the `--ysqlhbaconf_csv` configuration flag to enable LDAP authentication on YB-TServer. Use the following configuration to start the cluster: ```sh --ysqlhbaconf_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 title="Note" >}} This sample configuration uses an to set up the LDAP authentication with YugabyteDB. {{< /note >}} For convenience, the configuration uses two 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`). Start the YSQL shell (ysqlsh) specifying the `yugabyte` user, and enter the password (default is `yugabyte`) when prompted. ```sh $ ./ysqlsh -U yugabyte -W ``` ```output ysqlsh (11.2-YB-2.3.3.0-b0) Type "help" for help. yugabyte=# ``` To display the current values in the `ysql_hba.conf` file, run the following `SHOW` statement to get the file location: ```sql yugabyte=# SHOW hba_file; ``` ```output hba_file /Users/yugabyte/yugabyte-data/node-1/disk-1/pgdata/ysqlhba.conf (1 row) ``` View the file. The `ysql_hba.conf` file should have the following configuration: ```output 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 ``` Configure database role(s) for the LDAP user(s). The following commands create a `ROLE` for user `riemann` supported by the test LDAP server: ```sql yugabyte=# CREATE ROLE riemann WITH LOGIN; yugabyte=# GRANT ALL ON DATABASE yugabyte TO riemann; ``` Connect using LDAP authentication. Connect via ysqlsh using the `riemann` LDAP user and password specified in the page. ```sh $ ./ysqlsh -U riemann -W ``` You can confirm the current user by running the following command: ```sql yugabyte=# SELECT current_user; ``` ```output current_user -- riemann (1 row) ```