Multi-Factor Authentication for the CockroachDB Cloud Console

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 to log in.

CockroachDB Cloud Console supports MFA through different mechanisms depending on how your organization authenticates users:

MFA through an identity provider (recommended)

When accessing the CockroachDB Cloud Console through Google, Microsoft, GitHub, or a custom 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:

• The IdP manages MFA policies and enrollment for all SSO users
• Users authenticate through your IdP's MFA flow
• CockroachDB Cloud Console inherits the MFA protection from your IdP

Refer to your IdP's documentation for configuring MFA.

Native CockroachDB Cloud MFA for password-based access

New in v26.2: 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, you can enable CockroachDB 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

Only organizations that have enabled Cloud Organization SSO can set up MFA for these password-based accounts.

Organization Admins can enforce MFA usage 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 Cloud Console by setting up MFA for your account. This feature is specific to password-based access. MFA for SSO users is managed directly by the identity provider.

Organization Admins can initiate MFA setup for their own accounts when they enable MFA enforcement. 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.
2. 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.
3. You will be given several recovery codes, to use in case you lose access to your authenticator app. 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 with username and password.

For organizations that have enabled Cloud Organization SSO, Organization Admins can enforce MFA usage for all password-based accounts.

Log in using MFA for a password-based account

Users who have set up MFA must provide a second authentication factor every time they log in to the CockroachDB Cloud Console with a password.

To log in with MFA enabled:

1. Go to the CockroachDB Cloud Console.
2. Enter your email address and password, then click Continue.

3. 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. If you've lost access to your recovery codes, refer to 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 when accessing the CockroachDB Cloud Console.

Before you can enforce MFA, you must have Cloud Organization SSO enabled for your organization. First make a plan to enable Cloud Organization SSO, then enable Cloud Organization SSO.

1. Log in to the CockroachDB Cloud Console as a user with the Organization Admin role.
2. Go to Organization > Authentication.
3. Under Authentication Methods, click Username and Password.
4. If you have not yet enabled Cloud Organization SSO, you will be prompted to do so.
5. 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.
   2. Read the information on the Enable MFA enforcement modal, then click Set up MFA.
   3. Set up MFA for your account.
6. 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 at their next login.

Organization admins can enable MFA enforcement using the CockroachDB Cloud API.

Reset a user's MFA

Organization Admins can reset the MFA of any users who have set up MFA 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 Cloud Console as a user with the Organization Admin role.
2. Go to Organization > Authentication.
3. Under Authentication Methods, click Username and Password.
4. If MFA enforcement has already been enabled, this Method Details page will state that MFA enforcement is active. Click View enrollment status.
5. 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.

Recover your account

During MFA setup, 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.

A user might lose access to both their authenticator app and recovery codes. The account recovery process depends on their role:

• Regular users: Contact an Organization Admin. The Admin can reset your MFA via the dashboard, which will require you to re-enroll at your next login.

• Organization Admin: Contact another Organization Admin in your organization. The other Admin can reset your MFA via the dashboard, which will require you to re-enroll at your next login.

If every Organization Admin has been locked out, contact CockroachDB Support. 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

• Use the CockroachDB Cloud API: Manage multi-factor authentication (MFA) enrollment
• Single Sign-On (SSO) for CockroachDB Cloud organizations
• Configure Cloud Organization SSO
• Require SSO
• Manage Users, Roles, and Service Accounts
• Authentication on CockroachDB Cloud