From 96c8c6d4721c10930075fc4b72f5a48fa81100a7 Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Mon, 6 Apr 2026 16:30:45 -0400 Subject: [PATCH 1/9] MFA enforcement for Cloud Console --- .../_includes/cockroachcloud/prefer-sso.md | 2 +- .../v25.4/sidebar-data/cloud-deployments.json | 6 ++ .../v26.1/sidebar-data/cloud-deployments.json | 6 ++ .../v26.2/sidebar-data/cloud-deployments.json | 6 ++ src/current/cockroachcloud/cloud-org-sso.md | 3 + .../multi-factor-authentication.md | 66 +++++++++++++++++++ 6 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 src/current/cockroachcloud/multi-factor-authentication.md diff --git a/src/current/_includes/cockroachcloud/prefer-sso.md b/src/current/_includes/cockroachcloud/prefer-sso.md index a8d3825d6a0..0a343e7d6f6 100644 --- a/src/current/_includes/cockroachcloud/prefer-sso.md +++ b/src/current/_includes/cockroachcloud/prefer-sso.md @@ -1,5 +1,5 @@ {{site.data.alerts.callout_info}} - We recommend that CockroachDB {{ site.data.products.cloud }} Console users log in with [Single Sign-On (SSO)]({% link cockroachcloud/cloud-org-sso.md %}), optionally with two-factor authentication (2FA) enabled for the SSO provider. This prevents potential attackers from using stolen credentials to access or tamper with your critical data. + We recommend that CockroachDB {{ site.data.products.cloud }} Console users log in with [Single Sign-On (SSO)]({% link cockroachcloud/cloud-org-sso.md %}), optionally with [multi-factor authentication (MFA)]({% link cockroachcloud/multi-factor-authentication.md %}) enabled for the SSO provider. This prevents potential attackers from using stolen credentials to access or tamper with your critical data. CockroachDB {{ site.data.products.cloud }} [Basic SSO]({% link cockroachcloud/cloud-org-sso.md %}#basic-sso) supports SSO with GitHub, Google, and Microsoft. [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso) provides additional configuration and flexibility, and includes support for OIDC or SAML protocols, autoprovisioning, and limiting the email domains that can use a given authentication method. diff --git a/src/current/_includes/v25.4/sidebar-data/cloud-deployments.json b/src/current/_includes/v25.4/sidebar-data/cloud-deployments.json index cc6da870650..a5cf6de9604 100644 --- a/src/current/_includes/v25.4/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v25.4/sidebar-data/cloud-deployments.json @@ -273,6 +273,12 @@ "/cockroachcloud/cloud-sso-sql.html" ] }, + { + "title": "Multi-Factor Authentication for the Cloud Console", + "urls": [ + "/cockroachcloud/multi-factor-authentication.html" + ] + }, { "title": "SQL Client Certificate Authentication for Advanced Clusters", "urls": [ diff --git a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json index 3114b07c714..aea682694e6 100644 --- a/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.1/sidebar-data/cloud-deployments.json @@ -285,6 +285,12 @@ "/cockroachcloud/cloud-sso-sql.html" ] }, + { + "title": "Multi-Factor Authentication for the Cloud Console", + "urls": [ + "/cockroachcloud/multi-factor-authentication.html" + ] + }, { "title": "SQL Client Certificate Authentication for Advanced Clusters", "urls": [ diff --git a/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json b/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json index 6ae5a968ddd..1c69637a09e 100644 --- a/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json +++ b/src/current/_includes/v26.2/sidebar-data/cloud-deployments.json @@ -285,6 +285,12 @@ "/cockroachcloud/cloud-sso-sql.html" ] }, + { + "title": "Multi-Factor Authentication for the Cloud Console", + "urls": [ + "/cockroachcloud/multi-factor-authentication.html" + ] + }, { "title": "SQL Client Certificate Authentication for Advanced Clusters", "urls": [ diff --git a/src/current/cockroachcloud/cloud-org-sso.md b/src/current/cockroachcloud/cloud-org-sso.md index 186b8524fa1..31d7aa8c9a6 100644 --- a/src/current/cockroachcloud/cloud-org-sso.md +++ b/src/current/cockroachcloud/cloud-org-sso.md @@ -32,6 +32,7 @@ Cloud Organization SSO allows you to customize your SSO configuration to meet yo - Members can sign in using any enabled authentication method, to help reduce the impact of an IdP outage. If a member signs in using a new method for the first time, they are prompted to optionally update their default method. **This is possible only as long as the members are using the same email address to sign in through each method**. - You can [enable multiple authentication methods]({% link cockroachcloud/configure-cloud-org-sso.md %}#enable-or-disable-an-authentication-method) simultaneously. You can even add custom authentication methods that connect to IdPs such as Okta or ActiveDirectory through the [Security Access Markup Language (SAML)](https://wikipedia.org/wiki/Security_Assertion_Markup_Language) and [OpenID Connect (OIDC)](https://openid.net/connect/) identity protocols. If you use Okta, you can use the official [Cockroach Labs Okta app integration]({% link cockroachcloud/configure-cloud-org-sso.md %}#add-a-custom-authentication-method) to ease setup of custom SAML or OIDC authentication methods. - You can disable any authentication method. To enforce a requirement to use SSO, you can enable only SSO authentication methods and disable password authentication. If you disable password authentication, passwords are not retained. +- You can enforce the use of [multi-factor authentication to access the Cloud Console]({% link cockroachcloud/multi-factor-authentication.md %}) for any non-SSO users. This uses the Console's native multi-factor authentication feature. - You can [restrict the email domains]({% link cockroachcloud/configure-cloud-org-sso.md %}#allowed-email-domains) that are allowed to sign in using an SSO authentication method. By default, any email domain is allowed. - [Autoprovisioning](#autoprovisioning) can be enabled for SSO authentication methods, and automatically creates a CockroachDB {{ site.data.products.cloud }} organization account when a member successfully authenticates using an SSO authentication method for the first time, with no invitation required. - [SCIM Provisioning]({% link cockroachcloud/configure-scim-provisioning.md %}) automatically creates a CockroachDB {{ site.data.products.cloud }} organization account when a user is assigned to the SCIM application in your IdP that is connected to your CockroachDB {{ site.data.products.cloud }} organization. @@ -108,6 +109,8 @@ To remove a user's access to CockroachDB {{ site.data.products.cloud }} manually Yes. When Cloud Organization SSO is enabled for your CockroachDB {{ site.data.products.cloud }} organization, only the [authentication methods you have enabled]({% link cockroachcloud/configure-cloud-org-sso.md %}#enable-or-disable-an-authentication-method) are displayed to your users. +It's also possible to require non-SSO users to access the CockroachDB {{ site.data.products.cloud }} Console via the [Console's native multi-factor authentication feature]({% link cockroachcloud/multi-factor-authentication.md %}). + #### Which SAML-based authentication flows are supported with Cloud Organization SSO? After SAML is configured, your users can sign in to the CockroachDB {{ site.data.products.cloud }} Console in two different ways: diff --git a/src/current/cockroachcloud/multi-factor-authentication.md b/src/current/cockroachcloud/multi-factor-authentication.md new file mode 100644 index 00000000000..abfe425e42e --- /dev/null +++ b/src/current/cockroachcloud/multi-factor-authentication.md @@ -0,0 +1,66 @@ +--- +title: Multi-Factor Authentication for the Cloud Console +summary: Secure CockroachDB Cloud Console access with multi-factor authentication +toc: true +docs_area: manage.security +cloud: true +--- + +{{site.data.alerts.callout_info}} +{% include feature-phases/preview.md %} +{{site.data.alerts.end}} + +Multi-Factor Authentication (MFA) adds an additional layer of security to CockroachDB Cloud Console access by requiring users to provide a second form of verification beyond their password. + +## Overview + +CockroachDB Cloud Console supports MFA through different mechanisms depending on how your organization authenticates users: + +### MFA at the Identity Provider (Recommended) + +When you configure [Single Sign-On (SSO)](cloud-org-sso.html) for your organization, MFA is enforced at your Identity Provider (IdP) level—Okta, Microsoft Entra ID, Ping Identity, etc. This is the **recommended approach** for the majority of users in your organization. + +With this approach: +- Your IdP manages MFA policies and enrollment for all SSO users +- Users authenticate through your IdP's MFA flow (push notifications, TOTP codes, biometrics, etc.) +- CockroachDB Cloud Console inherits the MFA protection from your IdP + +Refer to your Identity Provider's documentation for configuring MFA. + +### Native CockroachDB Cloud MFA for non-SSO users + +{% include_cached new-in.html version="v26.2" %} Organizations that have SSO enabled can also enforce MFA for their remaining password-based accounts. This is primarily used for **break-glass accounts**—local admin accounts that exist outside the SSO provider as a failsafe when the SSO provider is unavailable. + +When you enable the "Require MFA for non-SSO/Social users" setting: + +- All users who authenticate with a password (rather than SSO) must enroll in Time-based One-Time Password (TOTP) authentication +- Users scan a QR code with a standard authenticator app (Google Authenticator, Authy, 1Password, Microsoft Authenticator, etc.) +- At each login, password users must enter their TOTP code in addition to their password +- Users receive recovery codes for account recovery if they lose access to their authenticator app + +{{site.data.alerts.callout_info}} +**Prerequisite:** Native MFA enforcement is only available for organizations that have SSO configured. Organizations without SSO enabled cannot use this feature. +{{site.data.alerts.end}} + +#### Enable native MFA enforcement + +To enable native MFA enforcement for non-SSO users: + +1. Navigate to your organization's **Authentication** settings in the CockroachDB Cloud Console. +1. Verify that SSO is configured for your organization. +1. Toggle **Require MFA for non-SSO/Social users** to **On**. +1. Complete your own MFA enrollment by scanning the QR code with your authenticator app and saving your recovery codes. + +Once enabled, all non-SSO users will be required to enroll in MFA at their next login. + +### Organizations without SSO + +Organizations that have not configured SSO must rely on alternative methods for MFA: + +- **Social login**: Users who authenticate with Google, GitHub, or Microsoft can enable MFA through their social provider's account settings. +- **Password-only accounts**: Users who authenticate with a password alone do not have MFA protection in CockroachDB Cloud. We strongly recommend configuring SSO to enable MFA for your organization. + +## See also + +- [Cloud Organization SSO](cloud-org-sso.html) +- [Authentication](authentication.html) From bebc18f750637cf8c3bada4e9a1b2b51a9bd5850 Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Tue, 7 Apr 2026 16:29:30 -0400 Subject: [PATCH 2/9] first draft of mfa page minus one section --- .../_includes/cockroachcloud/sso-intro.md | 2 +- src/current/cockroachcloud/authentication.md | 1 + src/current/cockroachcloud/cloud-org-sso.md | 2 +- .../cockroachcloud/configure-cloud-org-sso.md | 4 + .../multi-factor-authentication.md | 112 ++++++++++++------ 5 files changed, 86 insertions(+), 35 deletions(-) diff --git a/src/current/_includes/cockroachcloud/sso-intro.md b/src/current/_includes/cockroachcloud/sso-intro.md index bc3bf7cc0dc..50275cec47b 100644 --- a/src/current/_includes/cockroachcloud/sso-intro.md +++ b/src/current/_includes/cockroachcloud/sso-intro.md @@ -1,6 +1,6 @@ Single Sign-On (SSO) allows members of your CockroachDB {{ site.data.products.cloud }} organization to authenticate using an identity from an identity provider (IdP) instead of using an email address and password. -[Basic SSO]({% link cockroachcloud/cloud-org-sso.md %}#basic-sso) is enabled by default for each CockroachDB {{ site.data.products.cloud }} organization. members can authenticate to [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud) with any GitHub, Google, or Microsoft identity or with a password. +[Basic SSO]({% link cockroachcloud/cloud-org-sso.md %}#basic-sso) is enabled by default for each CockroachDB {{ site.data.products.cloud }} organization. Members can authenticate to [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud) with any GitHub, Google, or Microsoft identity or with a password. [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso) lets users sign in at a custom login page unique to your organization, and provides additional customization and capabilities to help your organization meet its security and compliance requirements. diff --git a/src/current/cockroachcloud/authentication.md b/src/current/cockroachcloud/authentication.md index 358c11bd5d0..67209177557 100644 --- a/src/current/cockroachcloud/authentication.md +++ b/src/current/cockroachcloud/authentication.md @@ -120,5 +120,6 @@ The table below lists the `sslmode` settings you can use to [connect to your clu - [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}) - [Configure Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}) +- [Multi-Factor Authentication for the CockroachDB Cloud Console]({% link cockroachcloud/multi-factor-authentication.md %}) - [Client Connection Parameters]({% link {{site.current_cloud_version}}/connection-parameters.md %}) - [Connect to Your CockroachDB {{ site.data.products.standard }} Cluster]({% link cockroachcloud/connect-to-your-cluster.md %}) diff --git a/src/current/cockroachcloud/cloud-org-sso.md b/src/current/cockroachcloud/cloud-org-sso.md index 31d7aa8c9a6..dc7cd8b0580 100644 --- a/src/current/cockroachcloud/cloud-org-sso.md +++ b/src/current/cockroachcloud/cloud-org-sso.md @@ -32,7 +32,7 @@ Cloud Organization SSO allows you to customize your SSO configuration to meet yo - Members can sign in using any enabled authentication method, to help reduce the impact of an IdP outage. If a member signs in using a new method for the first time, they are prompted to optionally update their default method. **This is possible only as long as the members are using the same email address to sign in through each method**. - You can [enable multiple authentication methods]({% link cockroachcloud/configure-cloud-org-sso.md %}#enable-or-disable-an-authentication-method) simultaneously. You can even add custom authentication methods that connect to IdPs such as Okta or ActiveDirectory through the [Security Access Markup Language (SAML)](https://wikipedia.org/wiki/Security_Assertion_Markup_Language) and [OpenID Connect (OIDC)](https://openid.net/connect/) identity protocols. If you use Okta, you can use the official [Cockroach Labs Okta app integration]({% link cockroachcloud/configure-cloud-org-sso.md %}#add-a-custom-authentication-method) to ease setup of custom SAML or OIDC authentication methods. - You can disable any authentication method. To enforce a requirement to use SSO, you can enable only SSO authentication methods and disable password authentication. If you disable password authentication, passwords are not retained. -- You can enforce the use of [multi-factor authentication to access the Cloud Console]({% link cockroachcloud/multi-factor-authentication.md %}) for any non-SSO users. This uses the Console's native multi-factor authentication feature. +- You can enable and enforce the use of [multi-factor authentication to access the Cloud Console]({% link cockroachcloud/multi-factor-authentication.md %}) for any non-SSO users. This uses the Console's native multi-factor authentication feature. - You can [restrict the email domains]({% link cockroachcloud/configure-cloud-org-sso.md %}#allowed-email-domains) that are allowed to sign in using an SSO authentication method. By default, any email domain is allowed. - [Autoprovisioning](#autoprovisioning) can be enabled for SSO authentication methods, and automatically creates a CockroachDB {{ site.data.products.cloud }} organization account when a member successfully authenticates using an SSO authentication method for the first time, with no invitation required. - [SCIM Provisioning]({% link cockroachcloud/configure-scim-provisioning.md %}) automatically creates a CockroachDB {{ site.data.products.cloud }} organization account when a user is assigned to the SCIM application in your IdP that is connected to your CockroachDB {{ site.data.products.cloud }} organization. diff --git a/src/current/cockroachcloud/configure-cloud-org-sso.md b/src/current/cockroachcloud/configure-cloud-org-sso.md index 819a977bb27..febe932ec99 100644 --- a/src/current/cockroachcloud/configure-cloud-org-sso.md +++ b/src/current/cockroachcloud/configure-cloud-org-sso.md @@ -295,6 +295,10 @@ After Cloud Organization SSO is enabled, it cannot be disabled. To emulate the b Members must still sign in using your organization's custom URL. +## Enable MFA enforcement for non-SSO access + +While Cockroach Labs recommends SSO for CockroachDB Cloud Console access, organizations commonly retain password-based accounts as a failsafe when SSO is unavailable. To ensure that these remaining password-based accounts are well-protected, [enable Cockroach Cloud's native MFA feature]({% link cockroachcloud/multi-factor-authentication.md %}#native-cockroachdb-cloud-mfa-for-password-based-access) for password-based access. + ## What next? - [Cloud Organization SSO Frequently Asked Questions]({% link cockroachcloud/cloud-org-sso.md %}#frequently-asked-questions-faq). diff --git a/src/current/cockroachcloud/multi-factor-authentication.md b/src/current/cockroachcloud/multi-factor-authentication.md index abfe425e42e..233157db084 100644 --- a/src/current/cockroachcloud/multi-factor-authentication.md +++ b/src/current/cockroachcloud/multi-factor-authentication.md @@ -1,66 +1,112 @@ --- -title: Multi-Factor Authentication for the Cloud Console +title: Multi-Factor Authentication for the CockroachDB Cloud Console summary: Secure CockroachDB Cloud Console access with multi-factor authentication toc: true docs_area: manage.security cloud: true --- -{{site.data.alerts.callout_info}} -{% include feature-phases/preview.md %} -{{site.data.alerts.end}} - -Multi-Factor Authentication (MFA) adds an additional layer of security to CockroachDB Cloud Console access by requiring users to provide a second form of verification beyond their password. +Multi-Factor Authentication (MFA) adds an additional layer of security to CockroachDB {{ site.data.products.cloud }} Console access by requiring users to provide a second form of verification to log in. -## Overview +CockroachDB {{ site.data.products.cloud }} Console supports MFA through different mechanisms depending on how your organization authenticates users: -CockroachDB Cloud Console supports MFA through different mechanisms depending on how your organization authenticates users: +## MFA through an identity provider (recommended) -### MFA at the Identity Provider (Recommended) - -When you configure [Single Sign-On (SSO)](cloud-org-sso.html) for your organization, MFA is enforced at your Identity Provider (IdP) level—Okta, Microsoft Entra ID, Ping Identity, etc. This is the **recommended approach** for the majority of users in your organization. +When accessing the CockroachDB {{ site.data.products.cloud }} Console through Google, Microsoft, GitHub, or a custom [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso) authentication method, MFA is managed at the identity provider (IdP) level. This is the **recommended approach** for the majority of users in your organization. With this approach: -- Your IdP manages MFA policies and enrollment for all SSO users + +- The IdP manages MFA policies and enrollment for all SSO users - Users authenticate through your IdP's MFA flow (push notifications, TOTP codes, biometrics, etc.) -- CockroachDB Cloud Console inherits the MFA protection from your IdP +- CockroachDB {{ site.data.products.cloud }} Console inherits the MFA protection from your IdP -Refer to your Identity Provider's documentation for configuring MFA. +Refer to your IdP's documentation for configuring MFA. -### Native CockroachDB Cloud MFA for non-SSO users +## Native CockroachDB Cloud MFA for password-based access -{% include_cached new-in.html version="v26.2" %} Organizations that have SSO enabled can also enforce MFA for their remaining password-based accounts. This is primarily used for **break-glass accounts**—local admin accounts that exist outside the SSO provider as a failsafe when the SSO provider is unavailable. +{{site.data.alerts.callout_info}} +{% include feature-phases/preview.md %} +{{site.data.alerts.end}} -When you enable the "Require MFA for non-SSO/Social users" setting: +{% include_cached new-in.html version="v26.2" %} While Cockroach Labs recommends SSO for CockroachDB {{ site.data.products.cloud }} Console access, organizations commonly retain password-based accounts as a failsafe when SSO is unavailable. To ensure that these remaining password-based accounts are well-protected, you can enable Cockroach {{ site.data.products.cloud }}'s native MFA feature for password-based access: - All users who authenticate with a password (rather than SSO) must enroll in Time-based One-Time Password (TOTP) authentication - Users scan a QR code with a standard authenticator app (Google Authenticator, Authy, 1Password, Microsoft Authenticator, etc.) - At each login, password users must enter their TOTP code in addition to their password - Users receive recovery codes for account recovery if they lose access to their authenticator app -{{site.data.alerts.callout_info}} -**Prerequisite:** Native MFA enforcement is only available for organizations that have SSO configured. Organizations without SSO enabled cannot use this feature. -{{site.data.alerts.end}} +Only organizations that have [enabled Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#enable-cloud-organization-sso) can set up MFA for these password-based accounts. + +Organization Admins can [enforce MFA usage for all password-based accounts](#enable-mfa-enforcement-for-all-password-based-accounts), which ensures account security across the organization. + +### Set up MFA for a password-based account + +You can increase the security of password-based access to the CockroachDB {{ site.data.products.cloud }} Console by setting up MFA for your account. This feature is specific to password-based access. MFA for [SSO users]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso) is managed directly by the identity provider. + +Organization Admins can initiate MFA setup for their own accounts when they [enable MFA enforcement](#enable-mfa-enforcement-for-all-password-based-accounts). All users will be required to initiate MFA setup upon attempting to log in after MFA enforcement has been enabled by an Organization Admin: + +1. A 6-digit verification code will be sent to the email associated with the account. Enter the code then click **Verify & Continue**. +1. Scan the QR code using an authenticator app. You will receive another 6-digit code via the app. Enter the code then click **Verify & Continue**. +1. You will be given several recovery codes, to use [in case you lose access to your authenticator app](#recover-your-account). Store them in a safe place, as the codes will not be shown again. Check the box indicating that you have saved the codes, then click **Complete setup**. + +The account associated with this email address will now need to [use MFA when logging in](#log-in-using-mfa-for-a-password-based-account) with username and password. + +For organizations that have enabled [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso), Organization Admins can [enforce MFA usage for all password-based accounts](#enable-mfa-enforcement-for-all-password-based-accounts). + +### Log in using MFA for a password-based account + +Users who have [set up MFA](#set-up-mfa-for-a-password-based-account) must provide a second authentication factor every time they log in to the CockroachDB {{ site.data.products.cloud }} Console with a password. + +To log in with MFA enabled: + +1. Go to the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud). +1. Enter your email address and password, then click **Continue**. +1. When prompted for MFA verification, enter the 6-digit TOTP code from your authenticator app, then click **Verify**. + + Alternatively, if you don't have access to your authenticator app, click **Use a recovery code instead** and enter one of the recovery codes that you stored during [MFA setup](#set-up-mfa-for-a-password-based-account). If you've lost access to your recovery codes, refer to [Recover your account](#recover-your-account). + +MFA verification is required once per session. You won't be prompted again until your session expires or you log out. + +### Enable MFA enforcement for all password-based accounts + +Organization Admins can require password-based users to use MFA to access the CockroachDB {{ site.data.products.cloud }} Console. + +Before you can enforce MFA, you must have [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso) enabled for your organization. First make a [plan to enable Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#plan-to-enable-cloud-organization-sso), then [enable Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#enable-cloud-organization-sso). + +1. Log in to the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud) as a user with the [Organization Admin]({% link cockroachcloud/authorization.md %}#organization-admin) role. +1. Go to **Organization** > **Authentication**. +1. Under **Authentication Methods**, click on the **Username and Password** method. +1. If you have not yet enabled [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso), you will be prompted to do so. +1. At least one Organization Admin must enable MFA on their own account before MFA enforcement can be enabled for all users. If no Organization Admins have enabled MFA, you will be prompted to do so: + 1. Click **Set up Multi-Factor Authentication on your account**. + 1. Read the information on the **Enable MFA enforcement** modal, then click **Set up MFA**. + 1. [Set up MFA for your account](#set-up-mfa-for-a-password-based-account). +1. The **Multi-Factor Authentication Enforcement** toggle will switch on once you've set up MFA for your own account. An Organization Admin can toggle this setting on and off. + +Once enabled, all password-based users will be required to [enroll in MFA](#set-up-mfa-for-a-password-based-account) at their next login. + +Note that this does not enforce MFA for users who log in via SSO or social credentials. MFA enforcement for those users is handled by the respective SSO or social platform. + +### Reset a user's MFA -#### Enable native MFA enforcement +TODO -To enable native MFA enforcement for non-SSO users: +### Recover your account -1. Navigate to your organization's **Authentication** settings in the CockroachDB Cloud Console. -1. Verify that SSO is configured for your organization. -1. Toggle **Require MFA for non-SSO/Social users** to **On**. -1. Complete your own MFA enrollment by scanning the QR code with your authenticator app and saving your recovery codes. +During [MFA setup](#set-up-mfa-for-a-password-based-account), the user receives several recovery codes that they should store in a safe place. If the user loses access to their authenticator app, they can instead [log in using one of those codes](#log-in-using-mfa-for-a-password-based-account). -Once enabled, all non-SSO users will be required to enroll in MFA at their next login. +A user might lose access to both their authenticator app and recovery codes. The account recovery process depends on their [role]({% link cockroachcloud/authorization.md %}): -### Organizations without SSO +- **Regular users**: Contact an [Organization Admin]({% link cockroachcloud/authorization.md %}#organization-admin). The Admin can [reset your MFA](#reset-a-users-mfa) via the dashboard, which will require you to re-enroll at your next login. -Organizations that have not configured SSO must rely on alternative methods for MFA: +- **Organization Admin**: Contact another Organization Admin in your organization. The other Admin can [reset your MFA](#reset-a-users-mfa) via the dashboard, which will require you to re-enroll at your next login. -- **Social login**: Users who authenticate with Google, GitHub, or Microsoft can enable MFA through their social provider's account settings. -- **Password-only accounts**: Users who authenticate with a password alone do not have MFA protection in CockroachDB Cloud. We strongly recommend configuring SSO to enable MFA for your organization. +If every Organization Admin has been locked out, contact [CockroachDB Support](https://support.cockroachlabs.com). Support will perform a multi-signal identity verification process before manually resetting your MFA. You will be required to re-enroll at your next login. ## See also -- [Cloud Organization SSO](cloud-org-sso.html) -- [Authentication](authentication.html) +- [Single Sign-On (SSO) for CockroachDB Cloud organizations]({% link cockroachcloud/cloud-org-sso.md %}) +- [Configure Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}) +- [Require SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#require-sso) +- [Manage Users, Roles, and Service Accounts]({% link cockroachcloud/managing-access.md %}) +- [Authentication on CockroachDB Cloud]({% link cockroachcloud/authentication.md %}) From f6d64d132d2f7e8d5b6a21b9d7357953e111aaa1 Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Thu, 9 Apr 2026 15:12:42 -0400 Subject: [PATCH 3/9] added cloud api docs --- src/current/cockroachcloud/cloud-api.md | 86 ++++++++++++++++++- .../cockroachcloud/configure-cloud-org-sso.md | 2 +- .../multi-factor-authentication.md | 29 +++++-- 3 files changed, 107 insertions(+), 10 deletions(-) diff --git a/src/current/cockroachcloud/cloud-api.md b/src/current/cockroachcloud/cloud-api.md index fab1da8fa1a..e53b43cdc58 100644 --- a/src/current/cockroachcloud/cloud-api.md +++ b/src/current/cockroachcloud/cloud-api.md @@ -1188,4 +1188,88 @@ curl --request GET \ "deferral_policy": "DEFERRAL_60_DAYS", "deferred_until": "2025-12-15T00:00:00Z" } -~~~ \ No newline at end of file +~~~ + +## Manage multi-factor authentication (MFA) enrollment + +Password-based CockroachDB {{ site.data.products.cloud }} Console access can be secured with multi-factor authentication. Learn more about [Multi-Factor Authentication for the CockroachDB {{ site.data.products.cloud }} Console]({% link cockroachcloud/multi-factor-authentication.md %}#native-cockroachdb-cloud-mfa-for-password-based-access). + +### Get the organization's MFA enforcement policy + +To get the organization's MFA enforcement policy, send a `GET` request to the `v1/org-settings/mfa-enforcement` endpoint. + +{{site.data.alerts.callout_success}} +The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). +{{site.data.alerts.end}} + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/org-settings/mfa-enforcement \ + --header "Authorization: Bearer {secret_key}" +~~~ + +If the request is successful, the client receives a response with... + +**TODO: What does the JSON response look like?** + +### Toggle the organization's MFA enforcement policy + +To enable or disable the organization's MFA enforcement policy, send a `PUT` request to the `v1/org-settings/mfa-enforcement` endpoint. + +{{site.data.alerts.callout_success}} +The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). The service account owner must have completed the [initial MFA setup via the UI]({% link cockroachcloud/multi-factor-authentication.md %}#set-up-mfa-for-a-password-based-account) before they will be able to enable or disable the enforcement policy. +{{site.data.alerts.end}} + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request PUT \ + --url https://cockroachlabs.cloud/api/v1/org-settings/mfa-enforcement \ + --header "Authorization: Bearer {secret_key}" +~~~ + +If the request is successful, the client receives a response with... + +**TODO: What does the JSON response look like?** + +### Get MFA enrollment status for all users + +To get the MFA enrollment status (`enrolled`,`not_enrolled`, or `pending`) of all users in the organization, send a `GET` request to the `v1/org-settings/mfa-enrollment-status` endpoint. + +{{site.data.alerts.callout_success}} +The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). +{{site.data.alerts.end}} + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/org-settings/mfa-enrollment-status \ + --header "Authorization: Bearer {secret_key}" +~~~ + +If the request is successful, the client receives a response with... + +**TODO: What does the JSON response look like?** + +### Reset MFA for a user + +To reset the MFA for a specific user in the organization, send a `POST` request to the `v1/users/{user_id}/mfa-reset` endpoint. This action invalidates the user's Time-based One-Time Password (TOTP) bindings and will force the user to re-enroll in MFA. + +{{site.data.alerts.callout_success}} +The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). +{{site.data.alerts.end}} + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request GET \ + --url https://cockroachlabs.cloud/api/v1/users/{user_id}/mfa-reset \ + --header "Authorization: Bearer {secret_key}" +~~~ + +Where `{user_id}` is the user ID of the user whose MFA you want to reset. + +If the request is successful, the client receives a response with... + +**TODO: What does the JSON response look like?** + +Organization Admins cannot reset their own MFA using the CockroachDB {{ site.data.products.cloud }} API. Contact [CockroachDB Support](https://support.cockroachlabs.com) to self-reset MFA. diff --git a/src/current/cockroachcloud/configure-cloud-org-sso.md b/src/current/cockroachcloud/configure-cloud-org-sso.md index febe932ec99..848a921a985 100644 --- a/src/current/cockroachcloud/configure-cloud-org-sso.md +++ b/src/current/cockroachcloud/configure-cloud-org-sso.md @@ -297,7 +297,7 @@ Members must still sign in using your organization's custom URL. ## Enable MFA enforcement for non-SSO access -While Cockroach Labs recommends SSO for CockroachDB Cloud Console access, organizations commonly retain password-based accounts as a failsafe when SSO is unavailable. To ensure that these remaining password-based accounts are well-protected, [enable Cockroach Cloud's native MFA feature]({% link cockroachcloud/multi-factor-authentication.md %}#native-cockroachdb-cloud-mfa-for-password-based-access) for password-based access. +While Cockroach Labs recommends SSO for CockroachDB {{ site.data.products.cloud }} Console access, organizations commonly retain password-based accounts as a failsafe when SSO is unavailable. To ensure that these remaining password-based accounts are well-protected, [enable CockroachDB {{ site.data.products.cloud }}'s native MFA feature]({% link cockroachcloud/multi-factor-authentication.md %}#native-cockroachdb-cloud-mfa-for-password-based-access) for password-based access. ## What next? diff --git a/src/current/cockroachcloud/multi-factor-authentication.md b/src/current/cockroachcloud/multi-factor-authentication.md index 233157db084..4e521d94e60 100644 --- a/src/current/cockroachcloud/multi-factor-authentication.md +++ b/src/current/cockroachcloud/multi-factor-authentication.md @@ -17,7 +17,7 @@ When accessing the CockroachDB {{ site.data.products.cloud }} Console through Go With this approach: - The IdP manages MFA policies and enrollment for all SSO users -- Users authenticate through your IdP's MFA flow (push notifications, TOTP codes, biometrics, etc.) +- Users authenticate through your IdP's MFA flow - CockroachDB {{ site.data.products.cloud }} Console inherits the MFA protection from your IdP Refer to your IdP's documentation for configuring MFA. @@ -28,7 +28,7 @@ Refer to your IdP's documentation for configuring MFA. {% include feature-phases/preview.md %} {{site.data.alerts.end}} -{% include_cached new-in.html version="v26.2" %} While Cockroach Labs recommends SSO for CockroachDB {{ site.data.products.cloud }} Console access, organizations commonly retain password-based accounts as a failsafe when SSO is unavailable. To ensure that these remaining password-based accounts are well-protected, you can enable Cockroach {{ site.data.products.cloud }}'s native MFA feature for password-based access: +{% include_cached new-in.html version="v26.2" %} While Cockroach Labs recommends SSO for CockroachDB {{ site.data.products.cloud }} Console access, organizations commonly retain password-based accounts as a failsafe when SSO is unavailable. To ensure that these remaining password-based accounts are well-protected, you can enable CockroachDB {{ site.data.products.cloud }}'s native MFA feature for password-based access: - All users who authenticate with a password (rather than SSO) must enroll in Time-based One-Time Password (TOTP) authentication - Users scan a QR code with a standard authenticator app (Google Authenticator, Authy, 1Password, Microsoft Authenticator, etc.) @@ -37,13 +37,13 @@ Refer to your IdP's documentation for configuring MFA. Only organizations that have [enabled Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#enable-cloud-organization-sso) can set up MFA for these password-based accounts. -Organization Admins can [enforce MFA usage for all password-based accounts](#enable-mfa-enforcement-for-all-password-based-accounts), which ensures account security across the organization. +[Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) can [enforce MFA usage for all password-based accounts](#enable-mfa-enforcement-for-all-password-based-accounts), which ensures account security across the organization. ### Set up MFA for a password-based account You can increase the security of password-based access to the CockroachDB {{ site.data.products.cloud }} Console by setting up MFA for your account. This feature is specific to password-based access. MFA for [SSO users]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso) is managed directly by the identity provider. -Organization Admins can initiate MFA setup for their own accounts when they [enable MFA enforcement](#enable-mfa-enforcement-for-all-password-based-accounts). All users will be required to initiate MFA setup upon attempting to log in after MFA enforcement has been enabled by an Organization Admin: +[Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) can initiate MFA setup for their own accounts when they [enable MFA enforcement](#enable-mfa-enforcement-for-all-password-based-accounts). All users will be required to initiate MFA setup upon attempting to log in after MFA enforcement has been enabled by an Organization Admin: 1. A 6-digit verification code will be sent to the email associated with the account. Enter the code then click **Verify & Continue**. 1. Scan the QR code using an authenticator app. You will receive another 6-digit code via the app. Enter the code then click **Verify & Continue**. @@ -69,13 +69,13 @@ MFA verification is required once per session. You won't be prompted again until ### Enable MFA enforcement for all password-based accounts -Organization Admins can require password-based users to use MFA to access the CockroachDB {{ site.data.products.cloud }} Console. +[Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) can require password-based users to use MFA when accessing the CockroachDB {{ site.data.products.cloud }} Console. Before you can enforce MFA, you must have [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso) enabled for your organization. First make a [plan to enable Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#plan-to-enable-cloud-organization-sso), then [enable Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#enable-cloud-organization-sso). 1. Log in to the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud) as a user with the [Organization Admin]({% link cockroachcloud/authorization.md %}#organization-admin) role. 1. Go to **Organization** > **Authentication**. -1. Under **Authentication Methods**, click on the **Username and Password** method. +1. Under **Authentication Methods**, click **Username and Password**. 1. If you have not yet enabled [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso), you will be prompted to do so. 1. At least one Organization Admin must enable MFA on their own account before MFA enforcement can be enabled for all users. If no Organization Admins have enabled MFA, you will be prompted to do so: 1. Click **Set up Multi-Factor Authentication on your account**. @@ -85,11 +85,23 @@ Before you can enforce MFA, you must have [Cloud Organization SSO]({% link cockr Once enabled, all password-based users will be required to [enroll in MFA](#set-up-mfa-for-a-password-based-account) at their next login. -Note that this does not enforce MFA for users who log in via SSO or social credentials. MFA enforcement for those users is handled by the respective SSO or social platform. +Organization admins can enable MFA enforcement using the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}#toggle-the-organizations-mfa-enforcement-policy). + +{{site.data.alerts.callout_info}} +This does not enforce MFA for users who log in via SSO or social credentials. MFA enforcement for those users is handled by the respective SSO or social platform. +{{site.data.alerts.end}} ### Reset a user's MFA -TODO +[Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) can reset the MFA of any users who have [set up MFA](#set-up-mfa-for-a-password-based-account) for their password-based access. Resetting the MFA will invalidate the user's existing TOTP binding and recovery codes, and it will force the user to go through the enrollment process upon their next login. To reset a user's MFA: + +1. Log in to the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud) as a user with the [Organization Admin]({% link cockroachcloud/authorization.md %}#organization-admin) role. +1. Go to **Organization** > **Authentication**. +1. Under **Authentication Methods**, click **Username and Password**. +1. If [MFA enforcement has already been enabled](#enable-mfa-enforcement-for-all-password-based-accounts), this **Method Details** page will state that **MFA enforcement is active**. Click **View enrollment status**. +1. A table containing the organization's MFA-enrolled users will appear. Under the **Action** column, you may choose to **Reconfigure MFA** for Organization Admins, or **Reset MFA** for other users. Click on the action to reset the user's MFA. + +Organization admins can also reset a user's MFA using the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}#reset-mfa-for-a-user). ### Recover your account @@ -105,6 +117,7 @@ If every Organization Admin has been locked out, contact [CockroachDB Support](h ## See also +- [Use the CockroachDB Cloud API: Manage multi-factor authentication (MFA) enrollment]({% link cockroachcloud/cloud-api.md %}#manage-multi-factor-authentication-mfa-enrollment) - [Single Sign-On (SSO) for CockroachDB Cloud organizations]({% link cockroachcloud/cloud-org-sso.md %}) - [Configure Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}) - [Require SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#require-sso) From 3dbff1d474085766a5bdf2278469622c940e2c4c Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Mon, 20 Apr 2026 16:39:52 -0400 Subject: [PATCH 4/9] added MFA to the feature availability page --- src/current/v26.2/cockroachdb-feature-availability.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/current/v26.2/cockroachdb-feature-availability.md b/src/current/v26.2/cockroachdb-feature-availability.md index 41e060a5705..367c148fe8b 100644 --- a/src/current/v26.2/cockroachdb-feature-availability.md +++ b/src/current/v26.2/cockroachdb-feature-availability.md @@ -281,6 +281,10 @@ Buffered Writes enhance transaction throughput and reduce operational cost by mi For more information, refer to [Buffered writes]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#buffered-writes). +### Multi-factor authentication enforcement for the CockroachDB {{ site.data.products.cloud }} Console + +[Multi-factor authentication (MFA) enforcement]({% link cockroachcloud/multi-factor-authentication.md %}) for password-based access to the CockroachDB {{ site.data.products.cloud }} Console is in preview. This feature allows [Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) to require all users who authenticate with a password (rather than SSO) to enroll in Time-based One-Time Password (TOTP) authentication. This ensures that password-based accounts, which are commonly retained as a failsafe when SSO is unavailable, are well-protected. + ## See Also - [`SHOW {session variable}`]({% link {{ page.version.version }}/show-vars.md %}) From dc84af0dfe6aba04612007e9d51056b1146437d8 Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Tue, 21 Apr 2026 14:12:55 -0400 Subject: [PATCH 5/9] Remove API documentation (moved to DOC-16025-api-for-later branch) --- src/current/cockroachcloud/cloud-api.md | 84 ------------------- .../multi-factor-authentication.md | 7 +- 2 files changed, 1 insertion(+), 90 deletions(-) diff --git a/src/current/cockroachcloud/cloud-api.md b/src/current/cockroachcloud/cloud-api.md index e53b43cdc58..9a157b84e0c 100644 --- a/src/current/cockroachcloud/cloud-api.md +++ b/src/current/cockroachcloud/cloud-api.md @@ -1189,87 +1189,3 @@ curl --request GET \ "deferred_until": "2025-12-15T00:00:00Z" } ~~~ - -## Manage multi-factor authentication (MFA) enrollment - -Password-based CockroachDB {{ site.data.products.cloud }} Console access can be secured with multi-factor authentication. Learn more about [Multi-Factor Authentication for the CockroachDB {{ site.data.products.cloud }} Console]({% link cockroachcloud/multi-factor-authentication.md %}#native-cockroachdb-cloud-mfa-for-password-based-access). - -### Get the organization's MFA enforcement policy - -To get the organization's MFA enforcement policy, send a `GET` request to the `v1/org-settings/mfa-enforcement` endpoint. - -{{site.data.alerts.callout_success}} -The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). -{{site.data.alerts.end}} - -{% include_cached copy-clipboard.html %} -~~~ shell -curl --request GET \ - --url https://cockroachlabs.cloud/api/v1/org-settings/mfa-enforcement \ - --header "Authorization: Bearer {secret_key}" -~~~ - -If the request is successful, the client receives a response with... - -**TODO: What does the JSON response look like?** - -### Toggle the organization's MFA enforcement policy - -To enable or disable the organization's MFA enforcement policy, send a `PUT` request to the `v1/org-settings/mfa-enforcement` endpoint. - -{{site.data.alerts.callout_success}} -The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). The service account owner must have completed the [initial MFA setup via the UI]({% link cockroachcloud/multi-factor-authentication.md %}#set-up-mfa-for-a-password-based-account) before they will be able to enable or disable the enforcement policy. -{{site.data.alerts.end}} - -{% include_cached copy-clipboard.html %} -~~~ shell -curl --request PUT \ - --url https://cockroachlabs.cloud/api/v1/org-settings/mfa-enforcement \ - --header "Authorization: Bearer {secret_key}" -~~~ - -If the request is successful, the client receives a response with... - -**TODO: What does the JSON response look like?** - -### Get MFA enrollment status for all users - -To get the MFA enrollment status (`enrolled`,`not_enrolled`, or `pending`) of all users in the organization, send a `GET` request to the `v1/org-settings/mfa-enrollment-status` endpoint. - -{{site.data.alerts.callout_success}} -The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). -{{site.data.alerts.end}} - -{% include_cached copy-clipboard.html %} -~~~ shell -curl --request GET \ - --url https://cockroachlabs.cloud/api/v1/org-settings/mfa-enrollment-status \ - --header "Authorization: Bearer {secret_key}" -~~~ - -If the request is successful, the client receives a response with... - -**TODO: What does the JSON response look like?** - -### Reset MFA for a user - -To reset the MFA for a specific user in the organization, send a `POST` request to the `v1/users/{user_id}/mfa-reset` endpoint. This action invalidates the user's Time-based One-Time Password (TOTP) bindings and will force the user to re-enroll in MFA. - -{{site.data.alerts.callout_success}} -The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). -{{site.data.alerts.end}} - -{% include_cached copy-clipboard.html %} -~~~ shell -curl --request GET \ - --url https://cockroachlabs.cloud/api/v1/users/{user_id}/mfa-reset \ - --header "Authorization: Bearer {secret_key}" -~~~ - -Where `{user_id}` is the user ID of the user whose MFA you want to reset. - -If the request is successful, the client receives a response with... - -**TODO: What does the JSON response look like?** - -Organization Admins cannot reset their own MFA using the CockroachDB {{ site.data.products.cloud }} API. Contact [CockroachDB Support](https://support.cockroachlabs.com) to self-reset MFA. diff --git a/src/current/cockroachcloud/multi-factor-authentication.md b/src/current/cockroachcloud/multi-factor-authentication.md index 4e521d94e60..a9bf941e747 100644 --- a/src/current/cockroachcloud/multi-factor-authentication.md +++ b/src/current/cockroachcloud/multi-factor-authentication.md @@ -83,9 +83,7 @@ Before you can enforce MFA, you must have [Cloud Organization SSO]({% link cockr 1. [Set up MFA for your account](#set-up-mfa-for-a-password-based-account). 1. The **Multi-Factor Authentication Enforcement** toggle will switch on once you've set up MFA for your own account. An Organization Admin can toggle this setting on and off. -Once enabled, all password-based users will be required to [enroll in MFA](#set-up-mfa-for-a-password-based-account) at their next login. - -Organization admins can enable MFA enforcement using the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}#toggle-the-organizations-mfa-enforcement-policy). +Once enabled, all password-based users will be required to [enroll in MFA](#set-up-mfa-for-a-password-based-account) at their next login. {{site.data.alerts.callout_info}} This does not enforce MFA for users who log in via SSO or social credentials. MFA enforcement for those users is handled by the respective SSO or social platform. @@ -101,8 +99,6 @@ This does not enforce MFA for users who log in via SSO or social credentials. MF 1. If [MFA enforcement has already been enabled](#enable-mfa-enforcement-for-all-password-based-accounts), this **Method Details** page will state that **MFA enforcement is active**. Click **View enrollment status**. 1. A table containing the organization's MFA-enrolled users will appear. Under the **Action** column, you may choose to **Reconfigure MFA** for Organization Admins, or **Reset MFA** for other users. Click on the action to reset the user's MFA. -Organization admins can also reset a user's MFA using the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}#reset-mfa-for-a-user). - ### Recover your account During [MFA setup](#set-up-mfa-for-a-password-based-account), the user receives several recovery codes that they should store in a safe place. If the user loses access to their authenticator app, they can instead [log in using one of those codes](#log-in-using-mfa-for-a-password-based-account). @@ -117,7 +113,6 @@ If every Organization Admin has been locked out, contact [CockroachDB Support](h ## See also -- [Use the CockroachDB Cloud API: Manage multi-factor authentication (MFA) enrollment]({% link cockroachcloud/cloud-api.md %}#manage-multi-factor-authentication-mfa-enrollment) - [Single Sign-On (SSO) for CockroachDB Cloud organizations]({% link cockroachcloud/cloud-org-sso.md %}) - [Configure Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}) - [Require SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#require-sso) From e517f6fa9ca1659ec2dcb32bdcea8a176cbcb999 Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Tue, 21 Apr 2026 14:12:55 -0400 Subject: [PATCH 6/9] Remove API documentation (moved to DOC-16025-api-for-later branch) --- src/current/cockroachcloud/cloud-api.md | 86 +------------------ .../multi-factor-authentication.md | 7 +- 2 files changed, 2 insertions(+), 91 deletions(-) diff --git a/src/current/cockroachcloud/cloud-api.md b/src/current/cockroachcloud/cloud-api.md index e53b43cdc58..fab1da8fa1a 100644 --- a/src/current/cockroachcloud/cloud-api.md +++ b/src/current/cockroachcloud/cloud-api.md @@ -1188,88 +1188,4 @@ curl --request GET \ "deferral_policy": "DEFERRAL_60_DAYS", "deferred_until": "2025-12-15T00:00:00Z" } -~~~ - -## Manage multi-factor authentication (MFA) enrollment - -Password-based CockroachDB {{ site.data.products.cloud }} Console access can be secured with multi-factor authentication. Learn more about [Multi-Factor Authentication for the CockroachDB {{ site.data.products.cloud }} Console]({% link cockroachcloud/multi-factor-authentication.md %}#native-cockroachdb-cloud-mfa-for-password-based-access). - -### Get the organization's MFA enforcement policy - -To get the organization's MFA enforcement policy, send a `GET` request to the `v1/org-settings/mfa-enforcement` endpoint. - -{{site.data.alerts.callout_success}} -The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). -{{site.data.alerts.end}} - -{% include_cached copy-clipboard.html %} -~~~ shell -curl --request GET \ - --url https://cockroachlabs.cloud/api/v1/org-settings/mfa-enforcement \ - --header "Authorization: Bearer {secret_key}" -~~~ - -If the request is successful, the client receives a response with... - -**TODO: What does the JSON response look like?** - -### Toggle the organization's MFA enforcement policy - -To enable or disable the organization's MFA enforcement policy, send a `PUT` request to the `v1/org-settings/mfa-enforcement` endpoint. - -{{site.data.alerts.callout_success}} -The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). The service account owner must have completed the [initial MFA setup via the UI]({% link cockroachcloud/multi-factor-authentication.md %}#set-up-mfa-for-a-password-based-account) before they will be able to enable or disable the enforcement policy. -{{site.data.alerts.end}} - -{% include_cached copy-clipboard.html %} -~~~ shell -curl --request PUT \ - --url https://cockroachlabs.cloud/api/v1/org-settings/mfa-enforcement \ - --header "Authorization: Bearer {secret_key}" -~~~ - -If the request is successful, the client receives a response with... - -**TODO: What does the JSON response look like?** - -### Get MFA enrollment status for all users - -To get the MFA enrollment status (`enrolled`,`not_enrolled`, or `pending`) of all users in the organization, send a `GET` request to the `v1/org-settings/mfa-enrollment-status` endpoint. - -{{site.data.alerts.callout_success}} -The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). -{{site.data.alerts.end}} - -{% include_cached copy-clipboard.html %} -~~~ shell -curl --request GET \ - --url https://cockroachlabs.cloud/api/v1/org-settings/mfa-enrollment-status \ - --header "Authorization: Bearer {secret_key}" -~~~ - -If the request is successful, the client receives a response with... - -**TODO: What does the JSON response look like?** - -### Reset MFA for a user - -To reset the MFA for a specific user in the organization, send a `POST` request to the `v1/users/{user_id}/mfa-reset` endpoint. This action invalidates the user's Time-based One-Time Password (TOTP) bindings and will force the user to re-enroll in MFA. - -{{site.data.alerts.callout_success}} -The service account associated with the secret key must have the Org Admin [role]({% link cockroachcloud/authorization.md %}#organization-user-roles). -{{site.data.alerts.end}} - -{% include_cached copy-clipboard.html %} -~~~ shell -curl --request GET \ - --url https://cockroachlabs.cloud/api/v1/users/{user_id}/mfa-reset \ - --header "Authorization: Bearer {secret_key}" -~~~ - -Where `{user_id}` is the user ID of the user whose MFA you want to reset. - -If the request is successful, the client receives a response with... - -**TODO: What does the JSON response look like?** - -Organization Admins cannot reset their own MFA using the CockroachDB {{ site.data.products.cloud }} API. Contact [CockroachDB Support](https://support.cockroachlabs.com) to self-reset MFA. +~~~ \ No newline at end of file diff --git a/src/current/cockroachcloud/multi-factor-authentication.md b/src/current/cockroachcloud/multi-factor-authentication.md index 4e521d94e60..a9bf941e747 100644 --- a/src/current/cockroachcloud/multi-factor-authentication.md +++ b/src/current/cockroachcloud/multi-factor-authentication.md @@ -83,9 +83,7 @@ Before you can enforce MFA, you must have [Cloud Organization SSO]({% link cockr 1. [Set up MFA for your account](#set-up-mfa-for-a-password-based-account). 1. The **Multi-Factor Authentication Enforcement** toggle will switch on once you've set up MFA for your own account. An Organization Admin can toggle this setting on and off. -Once enabled, all password-based users will be required to [enroll in MFA](#set-up-mfa-for-a-password-based-account) at their next login. - -Organization admins can enable MFA enforcement using the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}#toggle-the-organizations-mfa-enforcement-policy). +Once enabled, all password-based users will be required to [enroll in MFA](#set-up-mfa-for-a-password-based-account) at their next login. {{site.data.alerts.callout_info}} This does not enforce MFA for users who log in via SSO or social credentials. MFA enforcement for those users is handled by the respective SSO or social platform. @@ -101,8 +99,6 @@ This does not enforce MFA for users who log in via SSO or social credentials. MF 1. If [MFA enforcement has already been enabled](#enable-mfa-enforcement-for-all-password-based-accounts), this **Method Details** page will state that **MFA enforcement is active**. Click **View enrollment status**. 1. A table containing the organization's MFA-enrolled users will appear. Under the **Action** column, you may choose to **Reconfigure MFA** for Organization Admins, or **Reset MFA** for other users. Click on the action to reset the user's MFA. -Organization admins can also reset a user's MFA using the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}#reset-mfa-for-a-user). - ### Recover your account During [MFA setup](#set-up-mfa-for-a-password-based-account), the user receives several recovery codes that they should store in a safe place. If the user loses access to their authenticator app, they can instead [log in using one of those codes](#log-in-using-mfa-for-a-password-based-account). @@ -117,7 +113,6 @@ If every Organization Admin has been locked out, contact [CockroachDB Support](h ## See also -- [Use the CockroachDB Cloud API: Manage multi-factor authentication (MFA) enrollment]({% link cockroachcloud/cloud-api.md %}#manage-multi-factor-authentication-mfa-enrollment) - [Single Sign-On (SSO) for CockroachDB Cloud organizations]({% link cockroachcloud/cloud-org-sso.md %}) - [Configure Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}) - [Require SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#require-sso) From d3cbba9970f4278f02c17af77e8f985271862285 Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Tue, 21 Apr 2026 14:21:30 -0400 Subject: [PATCH 7/9] removed new line --- src/current/cockroachcloud/cloud-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/cockroachcloud/cloud-api.md b/src/current/cockroachcloud/cloud-api.md index 9a157b84e0c..fab1da8fa1a 100644 --- a/src/current/cockroachcloud/cloud-api.md +++ b/src/current/cockroachcloud/cloud-api.md @@ -1188,4 +1188,4 @@ curl --request GET \ "deferral_policy": "DEFERRAL_60_DAYS", "deferred_until": "2025-12-15T00:00:00Z" } -~~~ +~~~ \ No newline at end of file From fc307af8f69cc8213a970bfe3319b83c91328c5b Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Wed, 22 Apr 2026 11:33:08 -0400 Subject: [PATCH 8/9] Changes from Abhishek's feedback --- .../multi-factor-authentication.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/current/cockroachcloud/multi-factor-authentication.md b/src/current/cockroachcloud/multi-factor-authentication.md index a9bf941e747..106a34e9921 100644 --- a/src/current/cockroachcloud/multi-factor-authentication.md +++ b/src/current/cockroachcloud/multi-factor-authentication.md @@ -33,7 +33,7 @@ Refer to your IdP's documentation for configuring MFA. - All users who authenticate with a password (rather than SSO) must enroll in Time-based One-Time Password (TOTP) authentication - Users scan a QR code with a standard authenticator app (Google Authenticator, Authy, 1Password, Microsoft Authenticator, etc.) - At each login, password users must enter their TOTP code in addition to their password -- Users receive recovery codes for account recovery if they lose access to their authenticator app +- During setup, users receive recovery codes for account recovery if they lose access to their authenticator app Only organizations that have [enabled Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#enable-cloud-organization-sso) can set up MFA for these password-based accounts. @@ -43,11 +43,11 @@ Only organizations that have [enabled Cloud Organization SSO]({% link cockroachc You can increase the security of password-based access to the CockroachDB {{ site.data.products.cloud }} Console by setting up MFA for your account. This feature is specific to password-based access. MFA for [SSO users]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso) is managed directly by the identity provider. -[Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) can initiate MFA setup for their own accounts when they [enable MFA enforcement](#enable-mfa-enforcement-for-all-password-based-accounts). All users will be required to initiate MFA setup upon attempting to log in after MFA enforcement has been enabled by an Organization Admin: +[Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) who log in via password (not through SSO) must set up MFA for their own accounts before they can [enable MFA enforcement](#enable-mfa-enforcement-for-all-password-based-accounts). All other password-based users will be required to initiate MFA setup upon attempting to log in after MFA enforcement has been enabled by an Organization Admin: 1. A 6-digit verification code will be sent to the email associated with the account. Enter the code then click **Verify & Continue**. 1. Scan the QR code using an authenticator app. You will receive another 6-digit code via the app. Enter the code then click **Verify & Continue**. -1. You will be given several recovery codes, to use [in case you lose access to your authenticator app](#recover-your-account). Store them in a safe place, as the codes will not be shown again. Check the box indicating that you have saved the codes, then click **Complete setup**. +1. You will be given several recovery codes, to use [in case you lose access to your authenticator app](#recover-your-account). Each code can be used once. Store them in a safe place, as the codes will not be shown again. Check the box indicating that you have saved the codes, then click **Complete setup**. The account associated with this email address will now need to [use MFA when logging in](#log-in-using-mfa-for-a-password-based-account) with username and password. @@ -59,11 +59,11 @@ Users who have [set up MFA](#set-up-mfa-for-a-password-based-account) must provi To log in with MFA enabled: -1. Go to the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud). +1. Go to your organization's CockroachDB {{ site.data.products.cloud }} Console. 1. Enter your email address and password, then click **Continue**. 1. When prompted for MFA verification, enter the 6-digit TOTP code from your authenticator app, then click **Verify**. - Alternatively, if you don't have access to your authenticator app, click **Use a recovery code instead** and enter one of the recovery codes that you stored during [MFA setup](#set-up-mfa-for-a-password-based-account). If you've lost access to your recovery codes, refer to [Recover your account](#recover-your-account). + Alternatively, if you don't have access to your authenticator app, click **Use a recovery code instead** and enter one of the recovery codes that you stored during [MFA setup](#set-up-mfa-for-a-password-based-account). A single recovery code can only be used once. If you've lost access to your recovery codes, refer to [Recover your account](#recover-your-account). MFA verification is required once per session. You won't be prompted again until your session expires or you log out. @@ -73,7 +73,7 @@ MFA verification is required once per session. You won't be prompted again until Before you can enforce MFA, you must have [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso) enabled for your organization. First make a [plan to enable Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#plan-to-enable-cloud-organization-sso), then [enable Cloud Organization SSO]({% link cockroachcloud/configure-cloud-org-sso.md %}#enable-cloud-organization-sso). -1. Log in to the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud) as a user with the [Organization Admin]({% link cockroachcloud/authorization.md %}#organization-admin) role. +1. Log in to your organization's CockroachDB {{ site.data.products.cloud }} Console as a user with the [Organization Admin]({% link cockroachcloud/authorization.md %}#organization-admin) role. 1. Go to **Organization** > **Authentication**. 1. Under **Authentication Methods**, click **Username and Password**. 1. If you have not yet enabled [Cloud Organization SSO]({% link cockroachcloud/cloud-org-sso.md %}#cloud-organization-sso), you will be prompted to do so. @@ -81,9 +81,9 @@ Before you can enforce MFA, you must have [Cloud Organization SSO]({% link cockr 1. Click **Set up Multi-Factor Authentication on your account**. 1. Read the information on the **Enable MFA enforcement** modal, then click **Set up MFA**. 1. [Set up MFA for your account](#set-up-mfa-for-a-password-based-account). -1. The **Multi-Factor Authentication Enforcement** toggle will switch on once you've set up MFA for your own account. An Organization Admin can toggle this setting on and off. +1. An Organization Admin will now be able to enable or disable the **Multi-Factor Authentication Enforcement** toggle. It is switched on by default. -Once enabled, all password-based users will be required to [enroll in MFA](#set-up-mfa-for-a-password-based-account) at their next login. +Once enabled, all password-based users will be logged out immediately. These users will be required to [enroll in MFA](#set-up-mfa-for-a-password-based-account) at their next login. {{site.data.alerts.callout_info}} This does not enforce MFA for users who log in via SSO or social credentials. MFA enforcement for those users is handled by the respective SSO or social platform. @@ -93,11 +93,11 @@ This does not enforce MFA for users who log in via SSO or social credentials. MF [Organization Admins]({% link cockroachcloud/authorization.md %}#organization-admin) can reset the MFA of any users who have [set up MFA](#set-up-mfa-for-a-password-based-account) for their password-based access. Resetting the MFA will invalidate the user's existing TOTP binding and recovery codes, and it will force the user to go through the enrollment process upon their next login. To reset a user's MFA: -1. Log in to the [CockroachDB {{ site.data.products.cloud }} Console](https://cockroachlabs.cloud) as a user with the [Organization Admin]({% link cockroachcloud/authorization.md %}#organization-admin) role. +1. Log in to your organization's CockroachDB {{ site.data.products.cloud }} Console as a user with the [Organization Admin]({% link cockroachcloud/authorization.md %}#organization-admin) role. 1. Go to **Organization** > **Authentication**. 1. Under **Authentication Methods**, click **Username and Password**. 1. If [MFA enforcement has already been enabled](#enable-mfa-enforcement-for-all-password-based-accounts), this **Method Details** page will state that **MFA enforcement is active**. Click **View enrollment status**. -1. A table containing the organization's MFA-enrolled users will appear. Under the **Action** column, you may choose to **Reconfigure MFA** for Organization Admins, or **Reset MFA** for other users. Click on the action to reset the user's MFA. +1. A table containing the organization's MFA-enrolled users will appear. Under the **Action** column, you may choose to **Reset MFA** for other users or **Reconfigure MFA** for yourself. Click on the action to reset or reconfigure the user's MFA. ### Recover your account From 86b4ee0ebcf5f7024ec1214d4cbc80ab1d28cecd Mon Sep 17 00:00:00 2001 From: Brandon Sanchez Date: Thu, 23 Apr 2026 15:08:57 -0400 Subject: [PATCH 9/9] trigger build