KB
Access & VPN

Resetting Nextcloud TOTP

3 min read657 words5 code blocks

At a glance#

  • Purpose: Restore access for a Nextcloud user who has lost their two-factor authentication device.
  • Applies to: Nextcloud 20 and later — snap, native and Docker installations.
  • Risk: Medium — temporarily removes a security control from a live account.
  • Time: About 5 minutes.

Overview#

Nextcloud can require a time-based one-time password (TOTP) as a second authentication factor. The code is generated by an authenticator app on the user's phone.

If the user loses that phone, reinstalls the app, or wipes the device, the shared secret is gone. Their password alone will no longer get them in, and Nextcloud offers no self-service recovery for this. An administrator has to disable the TOTP provider on that account from the server command line. The user can then log in with their password and enrol a new device.

Warning: This removes a security control from a live account. Confirm the requester really is who they say they are, using a different channel from the one the request arrived on — a phone call or a face-to-face check, not a reply to the same email. "I have lost my phone, please reset my 2FA" is one of the most common account-takeover scripts there is.

Before you start#

You will need:

  • Root or sudo access on the Nextcloud server.
  • The user's exact Nextcloud username — not their display name and not their email address.
  • Verified confirmation of the user's identity, as described above.

Nextcloud's command-line tool is called occ. How you invoke it depends on how Nextcloud was installed:

Installation typeCommand prefix
Snap packagenextcloud.occ
Native (Apache + PHP)sudo -u www-data php /var/www/nextcloud/occ
Dockerdocker exec -u www-data <container-name> php occ

The examples below use the snap form. Substitute the prefix that matches this server.

Procedure#

1. Check the user's current two-factor state#

This confirms the account exists and shows which 2FA providers are active on it.

bash
nextcloud.occ twofactorauth:state username

Expected output looks like this:

text
Two-factor authentication is enabled for user username

Enabled providers:
- totp
Disabled providers:
- backup_codes

The value you need is the provider ID shown in the enabled list. For the standard authenticator-app method this is totp.

Note: If backup_codes appears as enabled, ask the user to try one of their backup codes first. That restores their own access without an administrator having to remove anything.

2. Disable the TOTP provider for that user#

bash
nextcloud.occ twofactorauth:disable username totp

A successful run prints:

text
Two-factor provider totp disabled for user username

3. Have the user log in and re-enrol#

Ask the user to sign in with their username and password. They should then go to Settings → Personal → Security and set up two-factor authentication again with their new device.

Do not close the ticket until they confirm the new device works.

Verification#

Re-run the state command. The totp provider should now appear under disabled providers:

bash
nextcloud.occ twofactorauth:state username

After the user re-enrols, run it once more. totp should be back in the enabled list. That second check is the one that matters — it confirms the account is protected again rather than left open indefinitely.

Troubleshooting#

SymptomCause and fix
User username does not existYou used the display name or email instead of the username. List accounts with nextcloud.occ user:list.
command not found: nextcloud.occThis is not a snap installation. Use the native or Docker prefix from the table above.
Cannot write into "config" directoryThe command ran as the wrong user. Native installations must run occ as the web server user, usually www-data.
User is still prompted for a codeTheir browser session is cached. Ask them to open a private window or clear cookies for the site.
  • Resetting Guacamole TOTP — the same problem in Apache Guacamole, which stores TOTP state in MySQL and has no equivalent CLI.