diff --git a/src/current/_includes/releases/v25.3/v25.3.0-rc.1.md b/src/current/_includes/releases/v25.3/v25.3.0-rc.1.md index a43e59d4082..07a26fe51d2 100644 --- a/src/current/_includes/releases/v25.3/v25.3.0-rc.1.md +++ b/src/current/_includes/releases/v25.3/v25.3.0-rc.1.md @@ -12,6 +12,10 @@ Release Date: July 23, 2025 [#150366][#150366] - The session setting `optimizer_min_row_count`, which sets a lower bound on row count estimates for relational expressions during query planning, is now set to `1` by default. [#150376][#150376] +- The `options` column in the output of `SHOW ROLES` and `SHOW USERS` is now returned as an array of strings (e.g., `{NOLOGIN,CREATEDB}`) rather than as a single comma-separated string. This enables more efficient querying of role options using array functions like `unnest()`. For example: `SELECT * FROM [SHOW ROLES] AS r WHERE EXISTS (SELECT 1 FROM unnest(r.options) AS m(option) WHERE option LIKE 'SUBJECT=cn%');` + [#149537][#149537] +- The `SHOW ROLES` and `SHOW USERS` commands now include an `estimated_last_login_time` column that displays the estimated timestamp of when each user last authenticated to the database. This column shows `NULL` for users who have never logged in, and for existing users after upgrading to v25.3 until their next login. The tracking is performed on a best-effort basis and may not capture every login event. + [#149537][#149537]

Operational changes

@@ -50,3 +54,4 @@ Release Date: July 23, 2025 [#149920]: https://github.com/cockroachdb/cockroach/pull/149920 [#150296]: https://github.com/cockroachdb/cockroach/pull/150296 [#150016]: https://github.com/cockroachdb/cockroach/pull/150016 +[#149537]: https://github.com/cockroachdb/cockroach/pull/149537 diff --git a/src/current/v24.3/ldap-authentication.md b/src/current/v24.3/ldap-authentication.md index 019a23fbfb1..8e5dee6c95e 100644 --- a/src/current/v24.3/ldap-authentication.md +++ b/src/current/v24.3/ldap-authentication.md @@ -4,9 +4,13 @@ summary: Learn how to configure CockroachDB for user authentication using LDAP-c toc: true --- -CockroachDB supports authentication and authorization using LDAP-compatible directory services, such as Active Directory and Microsoft Entra ID. This allows you to integrate your cluster with your organization's existing identity infrastructure for centralized user management and access control. +{{site.data.alerts.callout_info}} +{% include feature-phases/preview.md %} +{{site.data.alerts.end}} + +CockroachDB supports authentication and authorization using systems compatible with the Lightweight Directory Access Protocol (LDAP), such as Active Directory and Microsoft Entra ID. This allows you to integrate your cluster with your organization's existing identity infrastructure for centralized user management and access control. -This page describes how to configure CockroachDB user authentication using LDAP. You can additionally configure CockroachDB to use the same directory service for user [authorization]({% link v24.3/ldap-authorization.md %}) (role-based access control), which assigns CockroachDB roles to users based on their group memberships in the directory. +This page describes how to configure CockroachDB user authentication using LDAP. You can additionally configure CockroachDB to use the same directory service for user [authorization]({% link {{ page.version.version }}/ldap-authorization.md %}) (role-based access control), which assigns CockroachDB roles to users based on their group memberships in the directory. ## Overview @@ -21,12 +25,16 @@ While LDAP configuration is cluster-specific, each request to authenticate a use - If a matching record was found, the cluster attempts to verify the user's identity through another LDAP request, this time using the credentials (username and password) provided by that user. - If this LDAP bind operation succeeds, the user is authenticated to the CockroachDB cluster. 1. Authorize the user (optional) - - If [LDAP authorization]({% link v24.3/ldap-authorization.md %}) is also enabled, an additional request is sent to retrieve the groups to which the user is assigned, using configurable criteria. + - If [LDAP authorization]({% link {{ page.version.version }}/ldap-authorization.md %}) is also enabled, the cluster sends an additional request to retrieve the groups to which the user is assigned, using configurable criteria. - If group memberships are found, any existing CockroachDB roles that match these group names are assigned to the user. These requests use a node's existing connection to the LDAP server, if one is open. Otherwise, the node establishes a new connection. The connection remains open for handling additional LDAP requests until it is closed by the LDAP server, based on its timeout setting. -Because CockroachDB maintains no more than one LDAP connection per node, for a cluster with `n` nodes, you can expect up to `n` concurrent LDAP connections. +Because CockroachDB maintains no more than one LDAP connection per node, for a cluster with `n` nodes, you can expect up to `n` concurrent LDAP connections. + +{{site.data.alerts.callout_info}} +LDAP authentication cannot be used for the `root` user or other [reserved identities]({% link {{ page.version.version }}/security-reference/authorization.md %}#reserved-identities). You must manage credentials for `root` separately using password authentication to ensure continuous administrative access regardless of LDAP availability. +{{site.data.alerts.end}} ## Configuration @@ -96,17 +104,15 @@ SET CLUSTER SETTING server.ldap_authentication.client.tls_key = ' SHOW USERS; ~~~ ~~~ - username | options | member_of --------------+---------+------------ -admin | | {} -no_options | | {} -root | | {admin} + username | options | member_of | estimated_last_login_time +-----------+---------+-----------+------------------------------ +admin | {} | {} | NULL +no_options | {} | {} | NULL +root | {} | {admin} | NULL (3 rows) ~~~ @@ -121,12 +121,12 @@ root@:26257/defaultdb> SHOW USERS; ~~~ ~~~ - username | options | member_of ---------------+---------------------------------------+------------ -admin | | {} -no_options | | {} -root | | {admin} -with_password | VALID UNTIL=2021-10-10 00:00:00+00:00 | {} + username | options | member_of | estimated_last_login_time +--------------+-------------------------------------------+-----------+------------------------------ +admin | {} | {} | NULL +no_options | {} | {} | NULL +root | {} | {admin} | NULL +with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} | NULL (4 rows) ~~~ @@ -144,13 +144,13 @@ root@:26257/defaultdb> SHOW USERS; ~~~ ~~~ - username | options | member_of ---------------+---------------------------------------+------------ -admin | | {} -no_options | | {} -no_password | | {} -root | | {admin} -with_password | VALID UNTIL=2021-10-10 00:00:00+00:00 | {} + username | options | member_of | estimated_last_login_time +--------------+-------------------------------------------+-----------+------------------------------ +admin | {} | {} | NULL +no_options | {} | {} | NULL +no_password | {} | {} | NULL +root | {} | {admin} | NULL +with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} | NULL (5 rows) ~~~ @@ -167,14 +167,14 @@ root@:26257/defaultdb> SHOW USERS; ~~~ ~~~ - username | options | member_of ------------------+---------------------------------------+------------ -admin | | {} -can_create_users | CREATELOGIN, CREATEROLE | {} -no_options | | {} -no_password | | {} -root | | {admin} -with_password | VALID UNTIL=2021-10-10 00:00:00+00:00 | {} + username | options | member_of | estimated_last_login_time +-----------------+-------------------------------------------+-----------+------------------------------ +admin | {} | {} | NULL +can_create_users | {CREATELOGIN,CREATEROLE} | {} | NULL +no_options | {} | {} | NULL +no_password | {} | {} | NULL +root | {} | {admin} | NULL +with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} | NULL (6 rows) ~~~ @@ -191,15 +191,15 @@ root@:26257/defaultdb> SHOW USERS; ~~~ ~~~ - username | options | member_of -----------------------+---------------------------------------+------------ -admin | | {} -can_create_db | CREATEDB | {} -can_create_users | CREATELOGIN, CREATEROLE | {} -no_options | | {} -no_password | | {} -root | | {admin} -with_password | VALID UNTIL=2021-10-10 00:00:00+00:00 | {} + username | options | member_of | estimated_last_login_time +----------------------+-------------------------------------------+-----------+------------------------------ +admin | {} | {} | NULL +can_create_db | {CREATEDB} | {} | NULL +can_create_users | {CREATELOGIN,CREATEROLE} | {} | NULL +no_options | {} | {} | NULL +no_password | {} | {} | NULL +root | {} | {admin} | NULL +with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} | NULL (7 rows) ~~~ @@ -216,16 +216,16 @@ root@:26257/defaultdb> SHOW USERS; ~~~ ~~~ - username | options | member_of -----------------------+---------------------------------------+------------ -admin | | {} -can_control_job | CONTROLJOB | {} -can_create_db | CREATEDB | {} -can_create_users | CREATELOGIN, CREATEROLE | {} -no_options | | {} -no_password | | {} -root | | {admin} -with_password | VALID UNTIL=2021-10-10 00:00:00+00:00 | {} + username | options | member_of | estimated_last_login_time +----------------------+-------------------------------------------+-----------+------------------------------ +admin | {} | {} | NULL +can_control_job | {CONTROLJOB} | {} | NULL +can_create_db | {CREATEDB} | {} | NULL +can_create_users | {CREATELOGIN,CREATEROLE} | {} | NULL +no_options | {} | {} | NULL +no_password | {} | {} | NULL +root | {} | {admin} | NULL +with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} | NULL (8 rows) ~~~ @@ -242,17 +242,17 @@ root@:26257/defaultdb> SHOW USERS; ~~~ ~~~ - username | options | member_of -----------------------+---------------------------------------+------------ -admin | | {} -can_control_job | CONTROLJOB | {} -can_create_db | CREATEDB | {} -can_create_users | CREATELOGIN, CREATEROLE | {} -can_manage_queries | CANCELQUERY, VIEWACTIVITY | {} -no_options | | {} -no_password | | {} -root | | {admin} -with_password | VALID UNTIL=2021-10-10 00:00:00+00:00 | {} + username | options | member_of | estimated_last_login_time +----------------------+-------------------------------------------+-----------+------------------------------ +admin | {} | {} | NULL +can_control_job | {CONTROLJOB} | {} | NULL +can_create_db | {CREATEDB} | {} | NULL +can_create_users | {CREATELOGIN,CREATEROLE} | {} | NULL +can_manage_queries | {CANCELQUERY,VIEWACTIVITY} | {} | NULL +no_options | {} | {} | NULL +no_password | {} | {} | NULL +root | {} | {admin} | NULL +with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} | NULL (9 rows) ~~~ @@ -269,18 +269,18 @@ root@:26257/defaultdb> SHOW USERS; ~~~ ~~~ - username | options | member_of ------------------------+---------------------------------------+------------ -admin | | {} -can_control_changefeed | CONTROLCHANGEFEED | {} -can_control_job | CONTROLJOB | {} -can_create_db | CREATEDB | {} -can_create_users | CREATELOGIN, CREATEROLE | {} -can_manage_queries | CANCELQUERY, VIEWACTIVITY | {} -no_options | | {} -no_password | | {} -root | | {admin} -with_password | VALID UNTIL=2021-10-10 00:00:00+00:00 | {} + username | options | member_of | estimated_last_login_time +-----------------------+-------------------------------------------+-----------+------------------------------ +admin | {} | {} | NULL +can_control_changefeed | {CONTROLCHANGEFEED} | {} | NULL +can_control_job | {CONTROLJOB} | {} | NULL +can_create_db | {CREATEDB} | {} | NULL +can_create_users | {CREATELOGIN,CREATEROLE} | {} | NULL +can_manage_queries | {CANCELQUERY,VIEWACTIVITY} | {} | NULL +no_options | {} | {} | NULL +no_password | {} | {} | NULL +root | {} | {admin} | NULL +with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} | NULL (10 rows) ~~~ @@ -297,19 +297,19 @@ root@:26257/defaultdb> SHOW USERS; ~~~ ~~~ - username | options | member_of ----------------------------+---------------------------------------+------------ -admin | | {} -can_control_changefeed | CONTROLCHANGEFEED | {} -can_control_job | CONTROLJOB | {} -can_create_db | CREATEDB | {} -can_create_users | CREATELOGIN, CREATEROLE | {} -can_manage_queries | CANCELQUERY, VIEWACTIVITY | {} -can_modify_cluster_setting | MODIFYCLUSTERSETTING | {} -no_options | | {} -no_password | | {} -root | | {admin} -with_password | VALID UNTIL=2021-10-10 00:00:00+00:00 | {} + username | options | member_of | estimated_last_login_time +---------------------------+-------------------------------------------+-----------+------------------------------ +admin | {} | {} | NULL +can_control_changefeed | {CONTROLCHANGEFEED} | {} | NULL +can_control_job | {CONTROLJOB} | {} | NULL +can_create_db | {CREATEDB} | {} | NULL +can_create_users | {CREATELOGIN,CREATEROLE} | {} | NULL +can_manage_queries | {CANCELQUERY,VIEWACTIVITY} | {} | NULL +can_modify_cluster_setting | {MODIFYCLUSTERSETTING} | {} | NULL +no_options | {} | {} | NULL +no_password | {} | {} | NULL +root | {} | {admin} | NULL +with_password | {VALID UNTIL=2025-10-10 00:00:00+00:00} | {} | NULL (11 rows) ~~~ diff --git a/src/current/v25.3/ldap-authentication.md b/src/current/v25.3/ldap-authentication.md index 019a23fbfb1..dabf06d9482 100644 --- a/src/current/v25.3/ldap-authentication.md +++ b/src/current/v25.3/ldap-authentication.md @@ -4,15 +4,19 @@ summary: Learn how to configure CockroachDB for user authentication using LDAP-c toc: true --- -CockroachDB supports authentication and authorization using LDAP-compatible directory services, such as Active Directory and Microsoft Entra ID. This allows you to integrate your cluster with your organization's existing identity infrastructure for centralized user management and access control. +{{site.data.alerts.callout_info}} +{% include feature-phases/preview.md %} +{{site.data.alerts.end}} + +CockroachDB supports authentication and authorization using systems compatible with the Lightweight Directory Access Protocol (LDAP), such as Active Directory and Microsoft Entra ID. This allows you to integrate your cluster with your organization's existing identity infrastructure for centralized user management and access control. -This page describes how to configure CockroachDB user authentication using LDAP. You can additionally configure CockroachDB to use the same directory service for user [authorization]({% link v24.3/ldap-authorization.md %}) (role-based access control), which assigns CockroachDB roles to users based on their group memberships in the directory. +This page describes how to configure CockroachDB user authentication using LDAP. You can additionally configure CockroachDB to use the same directory service for user [authorization]({% link {{ page.version.version }}/ldap-authorization.md %}) (role-based access control), which assigns CockroachDB roles to users based on their group memberships in the directory. ## Overview LDAP authentication in CockroachDB works with LDAP-compatible directory services, including Microsoft Entra ID, Active Directory, and OpenLDAP. Secure LDAPS connectivity over TLS is required. -While LDAP configuration is cluster-specific, each request to authenticate a user in CockroachDB is handled by the node that receives it. When LDAP is enabled, the node handles each authentication request using a "search and bind" approach: +While LDAP configuration is cluster-specific, each request to authenticate a user in CockroachDB is handled by the node that receives it. When LDAP is enabled, the node handles each authentication request using a "search and bind" approach: 1. Find the user record - The node connects to the LDAP server using a dedicated directory access account. @@ -21,12 +25,16 @@ While LDAP configuration is cluster-specific, each request to authenticate a use - If a matching record was found, the cluster attempts to verify the user's identity through another LDAP request, this time using the credentials (username and password) provided by that user. - If this LDAP bind operation succeeds, the user is authenticated to the CockroachDB cluster. 1. Authorize the user (optional) - - If [LDAP authorization]({% link v24.3/ldap-authorization.md %}) is also enabled, an additional request is sent to retrieve the groups to which the user is assigned, using configurable criteria. + - If [LDAP authorization]({% link {{ page.version.version }}/ldap-authorization.md %}) is also enabled, an additional request is sent to retrieve the groups to which the user is assigned, using configurable criteria. - If group memberships are found, any existing CockroachDB roles that match these group names are assigned to the user. These requests use a node's existing connection to the LDAP server, if one is open. Otherwise, the node establishes a new connection. The connection remains open for handling additional LDAP requests until it is closed by the LDAP server, based on its timeout setting. -Because CockroachDB maintains no more than one LDAP connection per node, for a cluster with `n` nodes, you can expect up to `n` concurrent LDAP connections. +Because CockroachDB maintains no more than one LDAP connection per node, for a cluster with `n` nodes, you can expect up to `n` concurrent LDAP connections. + +{{site.data.alerts.callout_info}} +LDAP authentication cannot be used for the `root` user or other [reserved identities]({% link {{ page.version.version }}/security-reference/authorization.md %}#reserved-identities). Credentials for `root` must be managed separately using password authentication to ensure continuous administrative access regardless of LDAP availability. +{{site.data.alerts.end}} ## Configuration @@ -36,18 +44,19 @@ Because CockroachDB maintains no more than one LDAP connection per node, for a c - Network connectivity on port 636 for LDAPS. - A service account (bind DN) with permissions to search the directory for basic information about users and groups. For example, in Microsoft Entra ID, a [service principal](https://learn.microsoft.com/entra/architecture/secure-service-accounts) with the Directory Readers role. - The LDAP server's CA certificate, if using a custom CA not already trusted by the CockroachDB host. +- Verification that the attribute values that will become CockroachDB usernames meet the CockroachDB [requirements for usernames]({% link {{ page.version.version }}/create-user.md %}#user-names). Before you begin, it may be useful to enable authentication logging, which can help you confirm successful configuration or troubleshoot issues. For details, refer to [Troubleshooting](#troubleshooting). ### Step 1: Enable redaction of sensitive cluster settings -You will set LDAP bind credentials for the service account that enables this integration using the cluster setting `server.host_based_authentication.configuration`. You will also configure the mapping of external identities to CockroachDB SQL users using the cluster settings `server.identity_map.configuration`. +For this integration, you will need to store LDAP bind credentials for the service account that enables the integration in the [cluster setting `server.host_based_authentication.configuration`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-host-based-authentication-configuration). You will also configure the mapping of external identities to CockroachDB SQL users with the [cluster setting `server.identity_map.configuration`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-identity-map-configuration). In addition, for a custom CA configuration, you may need to store certificate and key details in the cluster settings specified in the optional [Step 3: Configure TLS](#step-3-configure-tls-optional). -To redact these two settings, refer to [Sensitive settings]({% link {{ page.version.version }}/cluster-settings.md %}#sensitive-settings). +It is highly recommended that you redact these settings, so that only authorized users, such as members of the `admin` role, can view them. To enable this redaction and learn about its permission scheme, refer to [Sensitive settings]({% link {{ page.version.version }}/cluster-settings.md %}#sensitive-settings). ### Step 2: Configure Host-Based Authentication (HBA) -To enable LDAP, you will need to update the [host-based authentication (HBA)]({% link {{ page.version.version }}/security-reference/authentication.md %}#authentication-configuration) configuration specified in the cluster setting `server.host_based_authentication.configuration`. +To enable LDAP, you will need to update the [host-based authentication (HBA)]({% link {{ page.version.version }}/security-reference/authentication.md %}#authentication-configuration) configuration specified in the [cluster setting `server.host_based_authentication.configuration`]({% link {{ page.version.version }}/cluster-settings.md %}#setting-server-host-based-authentication-configuration). Set the authentication method for all users and databases to `ldap` and include the LDAP-specific option parameters: @@ -79,14 +88,14 @@ If you also intend to configure LDAP Authorization, you will need to include an If, for LDAPS, you are using a certificate signed by a custom Certificate Authority (CA) that is not in the system's trusted CA store, you will need to configure the CA certificate. This step is only necessary when using certificates signed by your organization's private CA or other untrusted CA. -Set the custom CA certificate: +**Set the custom CA certificate:** {% include_cached copy-clipboard.html %} ~~~ sql -SET CLUSTER SETTING server.ldap_authentication.domain_ca = ''; +SET CLUSTER SETTING server.ldap_authentication.domain.custom_ca = ''; ~~~ -Configure a client certificate for mTLS if required: +**Configure a client certificate for mTLS if required:** {% include_cached copy-clipboard.html %} ~~~ sql @@ -94,20 +103,40 @@ SET CLUSTER SETTING server.ldap_authentication.client.tls_certificate = '