> ## Documentation Index
> Fetch the complete documentation index at: https://www.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Factor Authentication for the CockroachDB Cloud Console

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

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 <InternalLink path="cloud-org-sso#cloud-organization-sso">Cloud Organization SSO</InternalLink> 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

<Note>
  **This feature is in <InternalLink path="cockroachdb-feature-availability">preview</InternalLink>** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com).
</Note>

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 <InternalLink path="configure-cloud-org-sso#enable-cloud-organization-sso">enabled Cloud Organization SSO</InternalLink> can set up MFA for these password-based accounts.

<InternalLink path="authorization#organization-admin">Organization Admins</InternalLink> can [enforce MFA usage for all password-based accounts](#enable-mfa-enforcement-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 <InternalLink path="cloud-org-sso#cloud-organization-sso">SSO users</InternalLink> is managed directly by the identity provider.

<InternalLink path="authorization#organization-admin">Organization Admins</InternalLink> who log in via password (not through SSO) must set up MFA for their own accounts when [enabling 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**.
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](#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 is now required to [use MFA when logging in](#log-in-using-mfa-for-a-password-based-account) with username and password.

For organizations that have enabled <InternalLink path="cloud-org-sso#cloud-organization-sso">Cloud Organization SSO</InternalLink>, 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 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](#set-up-mfa-for-a-password-based-account). A single recovery code can only be used **once**. If you have 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

<InternalLink path="authorization#organization-admin">Organization Admins</InternalLink> can require password-based users to use MFA when accessing the CockroachDB Cloud Console.

Before you can enforce MFA, you must have <InternalLink path="cloud-org-sso#cloud-organization-sso">Cloud Organization SSO</InternalLink> enabled for your organization. First make a <InternalLink path="configure-cloud-org-sso#plan-to-enable-cloud-organization-sso">plan to enable Cloud Organization SSO</InternalLink>, then <InternalLink path="configure-cloud-org-sso#enable-cloud-organization-sso">enable Cloud Organization SSO</InternalLink>.

1. Log in to your organization's CockroachDB Cloud Console as a user with the <InternalLink path="authorization#organization-admin">Organization Admin</InternalLink> role.
2. Go to **Organization** > **Authentication**.
3. Under **Authentication Methods**, click **Username and Password**.
4. If you have not yet enabled <InternalLink path="cloud-org-sso#cloud-organization-sso">Cloud Organization SSO</InternalLink>, 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](#set-up-mfa-for-a-password-based-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](#set-up-mfa-for-a-password-based-account) at their next login.

<Note>
  The preceding steps do 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.
</Note>

### Reset a user's MFA

<InternalLink path="authorization#organization-admin">Organization Admins</InternalLink> 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 your organization's CockroachDB Cloud Console as a user with the <InternalLink path="authorization#organization-admin">Organization Admin</InternalLink> role.
2. Go to **Organization** > **Authentication**.
3. Under **Authentication Methods**, click **Username and Password**.
4. 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**.
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](https://support.cockroachlabs.com).

### Recover your account

During [MFA setup](#set-up-mfa-for-a-password-based-account), 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](#log-in-using-mfa-for-a-password-based-account).

If you lose access to both your authenticator app and recovery codes, you can recover your account. The account recovery process depends on your <InternalLink path="authorization">role</InternalLink>:

* **Regular users**: Contact an <InternalLink path="authorization#organization-admin">Organization Admin</InternalLink>. The Admin can [reset your MFA](#reset-a-users-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](#reset-a-users-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](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.

#### 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](#recover-your-account). Your old codes will no longer be valid.

## See also

* <InternalLink path="cloud-org-sso">Single Sign-On (SSO) for CockroachDB Cloud organizations</InternalLink>
* <InternalLink path="configure-cloud-org-sso">Configure Cloud Organization SSO</InternalLink>
* <InternalLink path="configure-cloud-org-sso#require-sso">Require SSO</InternalLink>
* <InternalLink path="managing-access">Manage Users, Roles, and Service Accounts</InternalLink>
* <InternalLink path="authentication">Authentication on CockroachDB Cloud</InternalLink>