User Two-Factor Authentication

Introduction

With two-factor authentication (2FA), users can access their ownCloud web accounts only by using an additional trusted device like their mobile phone. When users want to sign in, they need to provide two pieces of information (factors):

  • the password,

  • the six-digit verification code that’s automatically displayed on the trusted device or sent to the phone number.

Setting Up 2FA

To provide 2FA functionality, the 2-Factor Authentication app needs to be installed and enabled. Though there are other apps available, the description and screenshots refer to the named one.

If the two-factor provider app is enabled:

  • It is enabled for all users by default but a user has to opt in.

  • It can be enforced for all users as default.

  • Groups of users can be excluded from using 2FA.

Setup Two-Factor Authentication

Note that when users are forced to use 2FA, they are not able to do the setup process the same way as when using opt-in. For this case on first login after enforcing 2FA, the user is shown a special login screen where the QR code to finalize the 2FA process is displayed.

Login Screen with QR Code for Two-Factor Authentication
For the opt-in and login with enforced 2FA to work, ImageMagick and php-imagick are required to create the QR code. Depending on your operating system, these packages may need to be installed manually.

Using 2FA with ownCloud Desktop and Mobile Apps

ownCloud Desktop and Mobile Apps support 2FA login with browser-based login flows.

OAuth 2.0 is the recommended authentication method for clients.

Enable OAuth 2.0 App

When using the OAuth 2.0 App, the ownCloud Desktop client will open the login page in the system web browser and ownCloud Mobile Apps will open the login page in an embedded web view. After entering the regular credentials, users will see a second page, where they need to enter the second factor.

For more information see the User Auth Open Authentication (OAuth2) documentation.

App Passwords / Tokens

Without the OAuth 2.0 App, users need to log in to their ownCloud account in a regular web browser first, then create an app password or tokens, which can be used in the ownCloud Desktop and Mobile apps.

For more information see the App Passwords / Tokens documentation.

Troubleshooting

Tasks for the User

Because the user has to opt in, see the Security section in Personal Settings for tasks on the user side.

Second Factor is Inaccessible

In case a user loses access to the second factor, e.g. by breaking or losing the phone with two-factor SMS/app verification, the user is locked out. To give the user access to the account again, an admin can temporarily disable the two-factor check for that user via the occ commands for Two-Factor Authentication. After the issue has been fixed, the admin can enable two-factor authentication for that user again.

Manage Secrets

If owncloud’s 2-Factor Authentication is used, the admin can manage the secrets via Two-Factor TOTP occ commands.