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

# Multi-Factor Authentication

> Enable and manage TOTP-based multi-factor authentication for Xloud Identity user accounts.

## Overview

Xloud Identity supports TOTP-based (Time-based One-Time Password) multi-factor authentication
for user accounts. Enabling MFA adds a second verification step — a rotating 6-digit code
generated by an authenticator app — beyond the user's password. MFA significantly reduces
the risk of account compromise from credential theft.

<Note>
  **Prerequisites**

  * An active Xloud account with appropriate permissions
  * Access to the **Xloud Dashboard** or CLI configured with credentials
  * API credentials sourced (`source openrc.sh`)
</Note>

<Note>
  **Requirements**

  * A compatible authenticator application: Google Authenticator, Authy, 1Password, or any
    RFC 6238-compliant TOTP app
  * The user account must be active and have a valid password before enrolling MFA
</Note>

***

## Video Walkthrough

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/7BLwyAtKPjs" title="How to Set Up 2FA and User Center on Xloud" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

***

## Enroll a TOTP Device

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    The Dashboard has a self-service enrollment flow in **User Center → Security (2FA)**.
    Open the profile menu in the top-right, pick **Security (2FA)**, click
    **Enable 2FA**, scan the QR with any authenticator app, verify the 6-digit code,
    and save the recovery codes.

    For the full step-by-step walkthrough, see the
    [User Center guide](/services/dashboard/user-guide/user-center).
  </Tab>

  <Tab title="CLI" icon="terminal">
    <Steps titleSize="h3">
      <Step title="Authenticate" icon="key">
        Source your credentials file to authenticate with the Xloud platform:

        ```bash title="Load credentials" theme={null}
        source openrc.sh
        ```

        <Tip>
          Your administrator provides the RC (credentials) file for your project. See [CLI Setup](/cli-setup) for configuration details.
        </Tip>
      </Step>

      <Step title="Generate a TOTP seed" icon="plus">
        ```bash title="Create TOTP credential for the current user" theme={null}
        openstack credential create \
          --type totp \
          --user $(openstack token issue -f value -c user_id) \
          "{\"seed\": \"$(python3 -c 'import base64,os; print(base64.b32encode(os.urandom(20)).decode())')\"}"
        ```

        Note the `seed` value from the output.
      </Step>

      <Step title="Register seed in authenticator app" icon="smartphone">
        Import the base32-encoded seed into your authenticator app manually (use the
        "Enter setup key" option). The app begins generating 6-digit TOTP codes.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Authenticate with MFA

Once MFA is enabled, every login requires the TOTP code in addition to the password.

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    On the login page, enter your username and password as usual. A second prompt appears
    requesting the TOTP code from your authenticator app. Enter the current 6-digit code
    and click **Sign In**.

    <Warning>
      TOTP codes are valid for 30 seconds. If you enter an expired code, wait for the next
      code to appear in your authenticator app and try again.
    </Warning>
  </Tab>

  <Tab title="CLI" icon="terminal">
    When MFA is enabled, standard token issuance fails. Use the multi-factor auth method:

    ```bash title="Authenticate with password + TOTP" theme={null}
    openstack token issue \
      --os-auth-type v3multifactor \
      --os-auth-methods password,totp \
      --os-passcode <6-DIGIT-CODE>
    ```

    For automation with application credentials, MFA is **not** required — application
    credentials bypass the MFA requirement by design.
  </Tab>
</Tabs>

***

## Remove MFA Enrollment

<Tabs>
  <Tab title="Dashboard" icon="gauge">
    Open **User Center → Security (2FA)**, click **Disable 2FA**, and confirm with a
    current 6-digit code from your authenticator (or a recovery code if you have
    lost the authenticator). Full walkthrough in the
    [User Center guide](/services/dashboard/user-guide/user-center).

    <Warning>
      Removing MFA reduces account security — only do so when you are about to
      re-enroll with a new authenticator device.
    </Warning>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="List TOTP credentials for current user" theme={null}
    openstack credential list \
      --type totp \
      --user $(openstack token issue -f value -c user_id)
    ```

    ```bash title="Delete TOTP credential" theme={null}
    openstack credential delete <CREDENTIAL_ID>
    ```
  </Tab>
</Tabs>

***

## MFA Best Practices

<AccordionGroup>
  <Accordion title="Require MFA for administrative accounts" icon="shield" defaultOpen>
    All accounts with the `admin` role should have MFA enforced. Platform administrators
    can configure an MFA enforcement policy via the Identity service to block admin token
    issuance without a valid TOTP factor. See the
    [Identity Admin Guide](/services/identity/admin-guide) for policy configuration.
  </Accordion>

  <Accordion title="Use application credentials for automation" icon="terminal">
    Automation pipelines should never depend on interactive MFA. Use
    [application credentials](/services/identity/application-credentials) for CI/CD systems
    and service accounts — these bypass MFA by design and provide explicit expiry and
    access rule controls.
  </Accordion>

  <Accordion title="Plan for device loss" icon="life-buoy">
    Establish a recovery procedure before users lose access to their authenticator device:

    * Store backup codes in a password manager at enrollment time
    * Designate an administrator contact who can reset MFA enrollments
    * Document the reset process in your team's runbook
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Application Credentials" href="/services/identity/application-credentials" color="#197560">
    Generate automation credentials that bypass MFA for CI/CD pipelines.
  </Card>

  <Card title="Users" href="/services/identity/users" color="#197560">
    Manage the user accounts on which MFA is enrolled.
  </Card>

  <Card title="Identity Admin Guide — Security" href="/services/identity/security" color="#197560">
    Configure MFA enforcement policies and security hardening for the platform.
  </Card>

  <Card title="Troubleshooting" href="/services/identity/troubleshooting" color="#197560">
    Resolve MFA authentication failures and device enrollment issues.
  </Card>
</CardGroup>