Home > Administer Yugabyte Platform >

Enable Yugabyte Platform authentication via LDAP

LDAP provides means for querying directory services. A directory typically stores credentials and permissions assigned to a user, therefore allowing to maintain a single repository of user information for all applications across the organization. In addition, having a hierarchical structure, LDAP allows creation of user groups requiring the same credentials.

LDAP authentication is similar to a direct password authentication, except that it employs the LDAP protocol to verify the password. This means that only users who already exist in the database and have appropriate permissions can be authenticated via LDAP.

Yugabyte Platform's integration with LDAP enables you to use your LDAP server for authentication purposes instead of having to create user accounts on Yugabyte Platform.

Since Yugabyte Platform and the LDAP server are synchronized during login, Yugabyte Platform always uses the up-to-date credentials and roles information, such as role and password changes, as well as removal of users deleted in the LDAP server.

If configured by the LDAP server, Yugabyte Platform can prevent the user from being able to change their password.

Use the Yugabyte Platform API

To enable LDAP authentication for Yugabyte Platform login, you need to perform a number of runtime configurations to specify the following:

LDAP usage yb.security.ldap.use_ldap must be set to true, as follows:

curl --location --request PUT 'https://10.9.140.199/api/v1/customers/f3a63f07-e3d6-4475-96e4-57a6453072e1/runtime_config/00000000-0000-0000-0000-000000000000/key/yb.security.ldap.use_ldap' \
--header 'X-AUTH-YW-API-TOKEN: 5182724b-1891-4cde-bcd1-b8f7a3b7331e' \
--header 'Content-Type: text/plain' \
--header 'Cookie: csrfCookie=d5cdb2b36b00fcad1f4fdb24605aee412f8dfaa0-1641544510767-641be933bf684abcade3c592' \
--data-raw 'true'

Your LDAP server endpoint yb.security.ldap.ldap_url must be set using the 0.0.0.0 format, as follows:

curl --location --request PUT 'https://10.9.140.199/api/v1/customers/f3a63f07-e3d6-4475-96e4-57a6453072e1/runtime_config/00000000-0000-0000-0000-000000000000/key/yb.security.ldap.ldap_url' \
--header 'X-AUTH-YW-API-TOKEN: 5182724b-1891-4cde-bcd1-b8f7a3b7331e' \
--header 'Content-Type: text/plain' \
--data-raw '10.9.140.199'

The LDAP port yb.security.ldap.ldap_port must be set using the 000 format, as follows:

curl --location --request PUT 'https://10.9.140.199/api/v1/customers/f3a63f07-e3d6-4475-96e4-57a6453072e1/runtime_config/00000000-0000-0000-0000-000000000000/key/yb.security.ldap.ldap_port' \
--header 'X-AUTH-YW-API-TOKEN: 5182724b-1891-4cde-bcd1-b8f7a3b7331e' \
--header 'Content-Type: text/plain' \
--header 'Cookie: csrfCookie=d5cdb2b36b00fcad1f4fdb24605aee412f8dfaa0-1641544510767-641be933bf684abcade3c592' \
--data-raw '389'

The base distinguished name (DN) yb.security.ldap.ldap_basedn to enable restriction of users and user groups, as follows:

curl --location --request PUT 'https://10.9.140.199/api/v1/customers/f3a63f07-e3d6-4475-96e4-57a6453072e1/runtime_config/00000000-0000-0000-0000-000000000000/key/yb.security.ldap.ldap_basedn' \
--header 'X-AUTH-YW-API-TOKEN: 5182724b-1891-4cde-bcd1-b8f7a3b7331e' \
--header 'Content-Type: text/plain' \
--header 'Cookie: csrfCookie=d5cdb2b36b00fcad1f4fdb24605aee412f8dfaa0-1641544510767-641be933bf684abcade3c592' \
--data-raw '[LDAP DN]'

Replace [LDAP DN] with the actual value, as per the following example:

,DC=yugabyte,DC=com

Prefix to the common name (CN) of the user yb.security.ldap.ldap_dn_prefix, as follows:

curl --location --request PUT 'https://10.9.140.199/api/v1/customers/f3a63f07-e3d6-4475-96e4-57a6453072e1/runtime_config/00000000-0000-0000-0000-000000000000/key/yb.security.ldap.ldap_dn_prefix' \
--header 'X-AUTH-YW-API-TOKEN: 5182724b-1891-4cde-bcd1-b8f7a3b7331e' \
--header 'Content-Type: text/plain' \
--header 'Cookie: csrfCookie=d5cdb2b36b00fcad1f4fdb24605aee412f8dfaa0-1641544510767-641be933bf684abcade3c592' \
--data-raw '[LDAP DN PREFIX]'

Replace [LDAP DN PREFIX] with the actual value, as per the following example:

CN=

Note that Yugabyte Platform combines ldap_basedn and ldap_dn_prefix with the username provided during login to query the LDAP server. ldap_basedn and ldap_dn_prefix should be set accordingly.

The universally unique identifier (UUID) yb.security.ldap.ldap_customeruuid, if you have a multi-tenant setup, as follows:

curl --location --request PUT 'https://10.9.140.199/api/v1/customers/f3a63f07-e3d6-4475-96e4-57a6453072e1/runtime_config/00000000-0000-0000-0000-000000000000/key/yb.security.ldap.ldap_customeruuid' \
--header 'X-AUTH-YW-API-TOKEN: 5182724b-1891-4cde-bcd1-b8f7a3b7331e' \
--header 'Content-Type: text/plain' \
--header 'Cookie: csrfCookie=d5cdb2b36b00fcad1f4fdb24605aee412f8dfaa0-1641544510767-641be933bf684abcade3c592' \
--data-raw '[UUID]'

Replace [UUID] with the actual value.

If the UUID is not specified, then single-tenant is assumed by Yugabyte Platform.

When configured, Yugabyte Platform users are able to login by specifying the common name of the user and the password to bind to the LDAP server.

For additional information, see Update a configuration key.

Define the Yugabyte Platform Role

You need to define a Yugabyte Platform-specific role for each user on your LDAP server by setting the yugabytePlatformRole annotation. The value set for this annotation is read during the Yugabyte Platform login. Note that if the value is modified on the LDAP server, the change is propagated to Yugabyte Platform and automatically updated during login. Password updates are also automatically handled.

If the role is not specified, users are created with ReadOnly privileges by default, which can be modified by the local super admin.

When LDAP is set up on a Windows Active Directory (AD) server, the user is expected to have permissions to query the user's properties from that server. If the permissions have not been granted, Yugabyte Platform defaults its role to ReadOnly, which can later be modified by the local super admin.