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

​

Built-in CockroachDB Cloud MFA for password-based access

Cockroach Labs recommends SSO for CockroachDB Cloud Console access. However, you may retain password-based accounts as a failsafe when SSO is unavailable. To ensure that any remaining password-based accounts are well-protected, you can enable CockroachDB Cloud’s built-in 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.
• During setup, users receive recovery codes for account recovery if they lose access to their authenticator app.

Only organizations that have can set up MFA for these password-based accounts. can enforce MFA usage for all password-based accounts to ensure 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 is managed directly by the identity provider. who log in via password (not through SSO) must set up MFA for their own accounts when enabling MFA enforcement. 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.
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. 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 is now required to use MFA when logging in with username and password. For organizations that have enabled , 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 your organization’s 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. A single recovery code can only be used once. If you have 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

can require password-based users to use MFA when accessing the CockroachDB Cloud Console. Before you can enforce MFA, you must have enabled for your organization. First make a , then .

1. Log in to your organization’s CockroachDB Cloud Console as a user with the role.
2. Go to Organization > Authentication.
3. Under Authentication Methods, click Username and Password.
4. If you have not yet enabled , you will be prompted to do so.
5. If you are a password-based user and you have not yet set up MFA for your own account, you will be prompted to do so before you can enforce MFA across the organization:
   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. An Organization Admin can now enable or disable the Multi-Factor Authentication Enforcement toggle.

Once enabled, all password-based users are logged out immediately. These users will be required to enroll in MFA at their next login.

​

Reset a user’s MFA

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 your organization’s CockroachDB Cloud Console as a user with the 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 can choose to Reset MFA for other users. Click on the action to reset the user’s MFA. To reset your own MFA, contact another Admin or contact CockroachDB Support.

​

Recover your account

During MFA setup, you receive several recovery codes. Store these codes in a safe place. If you lose access to your authenticator app, you can instead log in using one of those codes. If you lose access to both your authenticator app and recovery codes, you can recover your account. The account recovery process depends on your :

• Regular users: Contact an . 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.

​

Regenerate recovery codes

You can regenerate recovery codes after you have enabled MFA on your account. While logged in to the CockroachDB Cloud Console:

1. Click My Account.
2. Click Account Settings.
3. On the account settings page, click Regenerate Recovery Codes.

Store these new codes in a safe place. They can now be used to recover an account. Your old codes will no longer be valid.

​

See also