LDAP automatic user provisioning #20033

mikeCRL · 2025-07-31T05:28:05Z

Documents the new LDAP automatic user provisioning feature in CockroachDB v25.3 and updates command reference pages to reflect changes to SHOW USERS/ROLES output format.

Key features documented

server.provisioning.ldap.enabled cluster setting
PROVISIONSRC role option format: ldap:<server>
Restrictions on auto-provisioned users (no password changes, immutable PROVISIONSRC role option)
CREATE/SHOW USER/ROLE output: new estimated_last_login_time tracking column, options output now as array: NOLOGIN, FOO → {NOLOGIN,FOO}
User cleanup workflows for AD-removed accounts with PowerShell example

Preview

Changes made

LDAP Documentation

Added preview callout that was needed across all pages

v25.3/ldap-authentication.md:

Added automatic user provisioning option with server.provisioning.ldap.enabled setting
Added recommendation to enable LDAP Authorization before auto-provisioning
Added "Managing auto-provisioned users" section with specific queries to filter by PROVISIONSRC
Added 3-step cleanup process for users removed from Active Directory
Added username validation requirements to prerequisites

v25.3/ldap-authorization.md:

Added advice to create CRDB roles before enabling auto-provisioning

v25.2 LDAP pages:

Added callout pointing to v25.3 for auto-provisioning capabilities
Fixed cross-version references

Release notes

Added 2 bullets to v25.3-rc.1 SQL language changes documenting options array format and new login time column

Command Reference Updates

Updated 21 example SHOW/CREATE USER/ROLE output tables across 6 files to use new array format for options column and add estimated_last_login_time column.

v25.3/create-role, v25.3/create-user, v25.3/show-roles, v25.3/show-users, v25.3/set-vars, v25.3/alter-default-privileges

TODOs

Backport v25.2 changes to v24.3 and v25.1. All three of these versions, which support LDAP functionality, did not receive the new 25.3 enhancements.
Enhancements suggested by Eng reviewer, which may be non-blocking if we need to merge, then iterate:
- Consider adding estimated_last_login_time auditing guidance to security documentation (either
  Security Overview or [Authorization Best Practices](https://www.
  cockroachlabs.com/docs/v22.2/security-reference/authorization#authorization-best-practices),
  and later expanding provisioning coverage further for future JWT support in v25.4
- Add query examples using estimated_last_login_time filtering for identifying dormant users in
  the cleanup/auditing section, since this column was primarily added to support deletion
  queries for inactive accounts

netlify · 2025-07-31T05:28:25Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`9cc0fc4`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/688c744cdbb05600099928c1

netlify · 2025-07-31T05:28:27Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`9cc0fc4`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/688c744cf2034700088b1a05

github-actions · 2025-07-31T05:28:32Z

Files changed:

netlify · 2025-07-31T05:37:18Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`9cc0fc4`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/688c744c95cdea00095213a2
😎 Deploy Preview	https://deploy-preview-20033--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

…er/role table output examples

souravcrl · 2025-08-01T10:20:04Z

src/current/v25.3/ldap-authentication.md

+
+- Users are created automatically upon successful LDAP authentication.
+- All auto-provisioned users receive a `PROVISIONSRC` role option set to `ldap:<ldap_server>`.
+- The `estimated_last_login_time` is tracked for auditing purposes.


The estimated_last_login_time is tracked for all users now, so not sure if we should additionally mention that the new audit is available in security overview here: https://www.cockroachlabs.com/docs/stable/security-reference/security-overview or as an aside for authorization best practices: https://www.cockroachlabs.com/docs/v22.2/security-reference/authorization#authorization-best-practices. The security overview can also include provisioning I feel because we plan to support JWT based provisioning also from 25.4 onwards. cc: @biplav-crl @pritesh-lahoti

souravcrl · 2025-08-01T10:20:08Z

src/current/v25.3/ldap-authentication.md

+SELECT * FROM [SHOW USERS] AS u 
+WHERE NOT EXISTS (
+  SELECT 1 FROM unnest(u.options) AS opt 
+  WHERE opt LIKE 'PROVISIONSRC=ldap:%'


Should we also include a filtering via the estimated_last_login_time option. The column was primarily added to be able to support deletion queries for dormant users and would be helpful to add to the auditing/deletion the statement clause

souravcrl

Approving this as some of the requested items may not make sense given the feature is under preview for 25.3.

taroface

Overall LGTM with some suggestions/comments. However, v25.2 has broken formatting on the LDAP Authentication page, so please fix before merging!

taroface · 2025-08-01T15:20:57Z

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` commands is now returned as an array of strings (for example `{NOLOGIN,CREATEDB}`) rather than as a single comma-separated string. This change 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%');`


Suggested change

- The `options` column in the output of `SHOW ROLES` and `SHOW USERS` commands is now returned as an array of strings (for example `{NOLOGIN,CREATEDB}`) rather than as a single comma-separated string. This change 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%');`

- 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%');`

taroface · 2025-08-01T15:22:08Z

src/current/v25.2/ldap-authentication.md

+{{site.data.alerts.callout_info}}
+{% include feature-phases/preview.md %}
+{{site.data.alerts.end}}
+
 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.


Might be useful to spell out "Lightweight Directory Access Protocol" and link https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol in the intro, unless you feel everyone knows it already.

taroface · 2025-08-01T15:22:50Z

src/current/v25.2/ldap-authentication.md

@@ -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.


Is this right?

Suggested change

- 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 [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.

taroface · 2025-08-01T15:24:31Z

src/current/v25.2/ldap-authentication.md

@@ -96,15 +104,14 @@ SET CLUSTER SETTING server.ldap_authentication.client.tls_key = '<PEM_ENCODED_KE

 ### Step 4: Sync database users

+Before LDAP authentication can be used for a user, the username must be created directly in CockroachDB. You will need to establish an automated method for keeping users in sync with the directory server, creating and dropping them as needed.


Suggested change

Before LDAP authentication can be used for a user, the username must be created directly in CockroachDB. You will need to establish an automated method for keeping users in sync with the directory server, creating and dropping them as needed.

Before LDAP authentication can be enabled for a user, you must create the username directly in CockroachDB. You will need to establish an automated method for keeping users in sync with the directory server, creating and dropping them as needed.

taroface · 2025-08-01T15:27:32Z

src/current/v25.2/ldap-authentication.md

+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.


Suggested change

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.

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.

taroface · 2025-08-01T15:36:27Z

src/current/v25.3/ldap-authorization.md


-When enabled:
+If LDAP authorization is enabled:


Elsewhere LDAP Authorization is capitalized. We should be consistent.

taroface · 2025-08-01T15:36:39Z

src/current/v25.3/ldap-authorization.md


 1. When a client connects to the cluster using LDAP, the cluster looks up the user's group membership in the LDAP service.
 1. Each LDAP group is mapped to a cluster role using the group's Common Name (CN) in the LDAP service.
 1. The user is granted each corresponding role, and roles that no longer match the user's groups are revoked.
+1. {% include_cached new-in.html version="v25.3" %}In conjunction with [automatic user provisioning]({% link {{ page.version.version }}/ldap-authentication.md %}#option-1-automatic-user-provisioning-recommended) if enabled, users are created automatically during their first authentication and simultaneously receive specified role memberships.


Suggested change

1. {% include_cached new-in.html version="v25.3" %}In conjunction with [automatic user provisioning]({% link {{ page.version.version }}/ldap-authentication.md %}#option-1-automatic-user-provisioning-recommended) if enabled, users are created automatically during their first authentication and simultaneously receive specified role memberships.

1. {% include_cached new-in.html version="v25.3" %} In conjunction with [automatic user provisioning]({% link {{ page.version.version }}/ldap-authentication.md %}#option-1-automatic-user-provisioning-recommended) if enabled, users are created automatically during their first authentication and simultaneously receive specified role memberships.

taroface · 2025-08-01T15:37:07Z

src/current/v25.3/ldap-authorization.md

+    If automatic user provisioning is enabled, users will be created automatically during their first login.
+
+1. Log in to CockroachDB as each test user (refer to [Connect to a cluster using LDAP]({% link {{ page.version.version }}/ldap-authentication.md %}#connect-to-a-cluster-using-ldap)).
+1. Using your admin credentials, log in to the CockroachDB SQL shell and run `SHOW USERS;` to view and verify users and their role assignments.


Suggested change

1. Using your admin credentials, log in to the CockroachDB SQL shell and run `SHOW USERS;` to view and verify users and their role assignments.

1. Using your `admin` credentials, log in to the CockroachDB SQL shell and run `SHOW USERS;` to view and verify users and their role assignments.

taroface · 2025-08-01T15:37:30Z

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


A few comments I had on v25.2 should also apply here.

taroface · 2025-08-01T15:39:17Z

src/current/v25.2/ldap-authentication.md

@@ -4,9 +4,13 @@ summary: Learn how to configure CockroachDB for user authentication using LDAP-c
 toc: true


This page is broken on preview. Not sure why but often has to do with a misformatted tag:

Initial updates for LDAP automatic user provisioning

61a8fb3

Additional edits

d3166fd

mikeCRL requested a review from souravcrl July 31, 2025 06:00

mikeCRL added 6 commits July 31, 2025 13:34

Add new options format and estimated_last_login_time column to all us…

fabdfa7

…er/role table output examples

Update release notes

ae1c4e2

Changes from PM/technical review

7e4940c

Fix link

3942aec

Remove code block from admonition to simplify

729b8b8

Fix code block

9cc0fc4

souravcrl reviewed Aug 1, 2025

View reviewed changes

mikeCRL requested a review from taroface August 1, 2025 15:22

souravcrl approved these changes Aug 1, 2025

View reviewed changes

taroface reviewed Aug 1, 2025

View reviewed changes

	- 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 [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.

		@@ -96,15 +104,14 @@ SET CLUSTER SETTING server.ldap_authentication.client.tls_key = '<PEM_ENCODED_KE

		### Step 4: Sync database users

		Before LDAP authentication can be used for a user, the username must be created directly in CockroachDB. You will need to establish an automated method for keeping users in sync with the directory server, creating and dropping them as needed.

	Before LDAP authentication can be used for a user, the username must be created directly in CockroachDB. You will need to establish an automated method for keeping users in sync with the directory server, creating and dropping them as needed.
	Before LDAP authentication can be enabled for a user, you must create the username directly in CockroachDB. You will need to establish an automated method for keeping users in sync with the directory server, creating and dropping them as needed.

	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.
	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.

	1. {% include_cached new-in.html version="v25.3" %}In conjunction with [automatic user provisioning]({% link {{ page.version.version }}/ldap-authentication.md %}#option-1-automatic-user-provisioning-recommended) if enabled, users are created automatically during their first authentication and simultaneously receive specified role memberships.
	1. {% include_cached new-in.html version="v25.3" %} In conjunction with [automatic user provisioning]({% link {{ page.version.version }}/ldap-authentication.md %}#option-1-automatic-user-provisioning-recommended) if enabled, users are created automatically during their first authentication and simultaneously receive specified role memberships.

	1. Using your admin credentials, log in to the CockroachDB SQL shell and run `SHOW USERS;` to view and verify users and their role assignments.
	1. Using your `admin` credentials, log in to the CockroachDB SQL shell and run `SHOW USERS;` to view and verify users and their role assignments.

		@@ -4,15 +4,19 @@ summary: Learn how to configure CockroachDB for user authentication using LDAP-c
		toc: true

		@@ -4,9 +4,13 @@ summary: Learn how to configure CockroachDB for user authentication using LDAP-c
		toc: true

LDAP automatic user provisioning #20033

Are you sure you want to change the base?

LDAP automatic user provisioning #20033

Uh oh!

Conversation

mikeCRL commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key features documented

Preview

Changes made

LDAP Documentation

Release notes

Command Reference Updates

TODOs

Uh oh!

netlify bot commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

netlify bot commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Uh oh!

github-actions bot commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files changed:

Uh oh!

netlify bot commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Netlify Preview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

souravcrl left a comment

Choose a reason for hiding this comment

Uh oh!

taroface left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mikeCRL commented Jul 31, 2025 •

edited

Loading

netlify bot commented Jul 31, 2025 •

edited

Loading

netlify bot commented Jul 31, 2025 •

edited

Loading

github-actions bot commented Jul 31, 2025 •

edited

Loading

netlify bot commented Jul 31, 2025 •

edited

Loading