User Two-Factor Authentication

Introduction

With two-factor authentication (2FA), users can access their ownCloud web accounts only by using a 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, an app like the 2-Factor Authentication needs to be installed and enabled.

If a two-factor provider app is enabled, it is enabled for all users by default but a user has to opt in, though the provider can decide whether or not the user has to pass the challenge.

For the opt-in function 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 reenable two-factor authentication for that user.

Manage Secrets

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