Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions src/current/v26.2/ldap-authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ toc: true

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 {{ page.version.version }}/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. For alternative SSO authentication methods, refer to [Single Sign-on (SSO) for DB Console]({% link {{ page.version.version }}/sso-db-console.md %}) (OIDC).

## Overview

Expand Down Expand Up @@ -109,7 +109,7 @@ CockroachDB supports two approaches for the creation of users who will authentic

#### Option 1: Automatic user provisioning (recommended)

With automatic user provisioning, CockroachDB creates users automatically during their first successful LDAP authentication. This eliminates the need for custom scripting to create user accounts.
With automatic user provisioning, CockroachDB creates users automatically during their first successful LDAP authentication, whether connecting via a SQL client or the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). This eliminates the need for custom scripting to create user accounts.

When enabled:

Expand Down Expand Up @@ -192,8 +192,8 @@ cockroach sql --url "postgresql://username:ldap_password@host:26257" --certs-dir

If LDAP authentication is configured, DB Console access will also use this configuration, allowing users to log in with their SQL username and LDAP password. During a login attempt, the system checks if LDAP authentication is configured for the user in the HBA configuration. If so, it validates the credentials against the LDAP server. If automatic user provisioning is enabled, users will be created automatically during their first successful login. If LDAP authentication fails or is not configured, the system falls back to password authentication.

{{site.data.alerts.callout_info}}
Authorization (role-based access control) is not applied when logging in to DB Console.
{{site.data.alerts.callout_success}}
When [LDAP authorization]({% link {{ page.version.version }}/ldap-authorization.md %}) is configured (with `ldapgrouplistfilter` in the HBA configuration), role-based access control is applied automatically upon login to both SQL clients and the DB Console. Users logging into the DB Console via LDAP will have their roles synchronized from LDAP groups, just as they are for SQL client connections.
{{site.data.alerts.end}}

## Manage auto-provisioned users
Expand Down Expand Up @@ -226,6 +226,8 @@ WHERE NOT EXISTS (

### Last-login tracking for usage and dormancy

When `security.provisioning.ldap.enabled` is set to `true`, the `estimated_last_login_time` column in the `SHOW USERS` output is updated for both SQL client connections and DB Console logins. This allows administrators to track user activity across all connection methods and identify dormant accounts.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing to note is estimated time is populated if authentication was successful even if the user was not able to access db console because of privileges. This was done because we want to track inactive users using their last login time.


The `estimated_last_login_time` column in the output of `SHOW USERS` tracks when users last authenticated. For example:

~~~
Expand Down
4 changes: 3 additions & 1 deletion src/current/v26.2/ldap-authorization.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,9 @@ toc: true
{% include feature-phases/preview.md %}
{{site.data.alerts.end}}

If you manage users through a service compatible with the Lightweight Directory Access Protocol (LDAP), such as Active Directory or Microsoft Entra ID, you can configure CockroachDB to automatically assign [roles]({% link {{ page.version.version }}/security-reference/authorization.md %}) to users based on LDAP group memberships, simplifying access control.
If you manage users through a service compatible with the Lightweight Directory Access Protocol (LDAP), such as Active Directory or Microsoft Entra ID, you can configure CockroachDB to automatically assign [roles]({% link {{ page.version.version }}/security-reference/authorization.md %}) to users based on LDAP group memberships, simplifying access control.

LDAP authorization applies to both SQL client connections and [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) logins. When a user authenticates via LDAP, their roles are automatically synchronized from LDAP groups, providing consistent role-based access control across all connection methods.

If LDAP authorization is enabled:

Expand Down
6 changes: 3 additions & 3 deletions src/current/v26.2/sso-db-console.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ key: sso.html
Single sign-on (SSO) for DB Console allows a CockroachDB user to access the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) in a secure cluster via an OpenID Connect (OIDC) client and an external identity provider. When SSO is configured and enabled, the [DB Console login page]({% link {{ page.version.version }}/ui-overview.md %}#db-console-access) will display an OAuth login button in addition to the password access option.

{{site.data.alerts.callout_info}}
This page covers SSO authentication to the DB Console. For SSO authentication to the SQL interface using JSON Web Tokens (JWT), refer to [Cluster Single Sign-on (SSO) using JWT]({% link {{ page.version.version }}/sso-sql.md %}).
This page covers OIDC-based SSO authentication to the DB Console. For SSO authentication to the SQL interface using JSON Web Tokens (JWT), refer to [Cluster Single Sign-on (SSO) using JWT]({% link {{ page.version.version }}/sso-sql.md %}). For LDAP-based authentication (which also supports DB Console login), refer to [LDAP Authentication]({% link {{ page.version.version }}/ldap-authentication.md %}).
{{site.data.alerts.end}}

CockroachDB's OIDC implementation for DB Console uses the [authorization code grant type](https://tools.ietf.org/html/rfc6749#section-4.1) to authenticate a user.
Expand Down Expand Up @@ -63,7 +63,7 @@ Cluster Setting | Description
`server.oidc_authentication.principal_regex` | Regex used to map the external identity key to a SQL user. If the identity key contains a list of identities instead of a single identity, each identity is evaluated serially until a match is found. The first match that is found is used, and the remaining identities are not evaluated. For example: `^([^@]+)@[^@]+$` matches any email address (defined as a string containing one `@` sign) and extracts a username from the string to the left of `@`, whereas `^(.+)$` maps the claim directly to a principal. The regex must contain exactly one capture group (set of parentheses); a regex with no capture groups or multiple capture groups will never find a match.
`server.oidc_authentication.autologin` | A Boolean that enables or disables automatic login with SSO when the DB Console is loaded. If set to `false` (the default), the user will have to click **Log in with your OIDC provider** (unless overriden with `server.oidc_authentication.button_text`) before they're authenticated.
`server.oidc_authentication.button_text` | Specifies the text to show on the button that launches authentication with the OIDC provider. This is set to `Log in with your OIDC provider` by default but can be customized to reference your specific provider by name.
`security.provisioning.oidc.enabled` | Enables automatic user creation on first OIDC login. Defaults to `false`. Refer to [Step 3: Configure user creation](#step-3-configure-user-creation).
`security.provisioning.oidc.enabled` | Enables automatic user creation on first OIDC login. When enabled, also updates the `estimated_last_login_time` column in the `SHOW USERS` output for DB Console logins, allowing administrators to track when OIDC users last accessed the cluster. Defaults to `false`. Refer to [Step 3: Configure user creation](#step-3-configure-user-creation).
`server.oidc_authentication.authorization.enabled` | Enables automatic role synchronization based on OIDC group claims. See [Configure OIDC Authorization for DB Console]({% link {{ page.version.version }}/oidc-authorization.md %}). Defaults to `false`.

#### Update your cluster settings
Expand Down Expand Up @@ -143,7 +143,7 @@ When enabled:

- Users are created automatically upon successful OIDC authentication.
- All auto-provisioned users receive a `PROVISIONSRC` role option set to `oidc:{provider_url}`.
- The `estimated_last_login_time` is tracked for auditing purposes.
- The `estimated_last_login_time` column in the `SHOW USERS` output is updated for DB Console logins, enabling tracking of user activity for auditing and identifying dormant accounts.
- Auto-provisioned users cannot change their own passwords (managed via OIDC only).

{{site.data.alerts.callout_info}}
Expand Down
Loading