Repository navigation
Migrating from twofactor_totp
Tip
TL;DR With both apps enabled, import the accounts from the banner, then run occ app:disable twofactor_totp and occ twofactorauth:cleanup totp.
While the bundled twofactor_totp app is enabled and has accounts that are not yet set up in OATH, a banner offers to import them. Because both apps store secrets the same way, the import is lossless: each account becomes an enabled OATH TOTP token with the same secret, so the user keeps getting the same codes and is never locked out. Accounts whose user already has an OATH token are not offered, and existing OATH tokens are never overwritten.
As part of the import, each migrated user is switched off twofactor_totp: its secret for that user is removed and the provider is deregistered for them (Nextcloud tracks the configured second factor in the provider registry, not in the secret, so removing the secret alone would not be enough). This is why disabling twofactor_totp afterwards causes no "could not load" errors for imported users.
The import reads the source algorithm column when present (twofactor_totp 17.1.0 and newer); older versions are SHA-1, 6 digits, 30 seconds.
Import is only available while twofactor_totp is enabled, so both apps have to be active at the same time for the migration. The two apps can run side by side, but OATH does everything twofactor_totp does and more, so the recommended path is to import every account and then retire twofactor_totp:
occ app:disable twofactor_totp
occ twofactorauth:cleanup totpThe second command belongs with the first: after disabling, the stale provider associations remain and would otherwise cause a "could not load" error at login; twofactorauth:cleanup removes them. (cleanup only removes the associations, not secrets, but the import already deleted the twofactor_totp secret of every account it migrated.)
A user who set up OATH on their own (for example an administrator testing the app) and still has a twofactor_totp account is registered with both providers. Such a user is not offered for import (they already have OATH), so the import never cleans up their twofactor_totp registration, and disabling twofactor_totp would break their login. When this happens, a banner lists how many users are affected.
Because twofactor_totp is a separate app, the default is to show you the commands to run yourself, one per user:
occ twofactorauth:disable <uid> totpAlternatively, confirm the banner's let twofactor_oath remove them now button to have this app perform the same operation (deregister the provider and delete the twofactor_totp secret) for those users. Because this deletes data of a separate app, it asks for confirmation first:
Either way nothing is left behind, so twofactor_totp can then be disabled cleanly.
