# Two-factor authentication

Source: https://cumulocity.com/docs/authentication/tfa/
Sector: Platform administration
Release: Latest
Description: Protect user logins with two-factor authentication, using either SMS or time-based one-time passwords (TOTP).

## Introduction

The two-factor authentication (TFA) is an extra layer of security that only completes authentication with a combination of two different factors: something the users know (username and password) and something they have (for example, smartphone) or something they are (for example, fingerprint).

There are two possible TFA strategies: Short Message Service (SMS) and Time-based One-Time Password (TOTP). Only one of them can be active at a time.

To check whether TFA is enabled for a certain user, go to the **Users** page and see the TFA status column right from the password strength column. A key icon indicates that TFA is enabled and by hovering over it you can see the strategy that is being used.

![TFA status](https://cumulocity.com/docs/images/users-guide/Administration/admin-tfa-sms.png)


> **Related topics:**
> - [Platform administration > Authentication > Basic settings](https://cumulocity.com/docs/authentication/basic-settings/) for information on how to configure basic authentication settings.
> - [Authentication](https://cumulocity.com/api/core/#section/Authentication) in the Cumulocity OpenAPI Specification for details on managing authentication via REST.

## SMS

> **Requirements:**
> When adding a user and TFA is enabled, a mobile phone number must be specified. Without a valid phone number a login is impossible.



### To enable a specific user {#to-enable-a-specific-user}

1. In the Administration application, navigate to **Accounts** > **Users** and select a user in the **Users** page.
2. Select the checkbox next to **Two-factor authentication (SMS)**.
3. Click **Save**.

![Enable TFA](https://cumulocity.com/docs/images/users-guide/Administration/admin-user-enable-tfa-sms.png)


> **Info:**
> This process can only be executed in the Administration application and is not available under **User settings**.

## TOTP

> **Requirements:**
> Users must install a TOTP application on their smartphone (Google Authenticator is recommended), freely available both on App Store and Play Store.



### To enable a specific user {#to-enable-a-specific-user}

1. In the Administration application, navigate to **Accounts** > **Users** and select a user in the **Users** page.
2. Select the checkbox next to **Two-factor authentication (TOTP)**. This option is available only if the user has TOTP configured. If this is not the case, select **Enforce TOTP setup for the user**.
3. Click **Save**.

![Enable TFA](https://cumulocity.com/docs/images/users-guide/Administration/admin-user-enable-tfa-1.png)

### To set up TOTP {#to-set-up-totp}

Opposed to the SMS strategy TOTP must be set up by each user. By opening **User settings** in the top right corner and then clicking **Set up two-factor authentication** they can start the setup process.

![Trigger TOTP setup](https://cumulocity.com/docs/images/users-guide/Administration/admin-user-enable-tfa-2.png)

IF TFA is enabled, the user will be presented a QR code at login, that must be scanned with the previously installed TOTP mobile application.

Alternatively, the secret can also be inserted manually in case scanning the QR code is not an option.

![TOTP setup process](https://cumulocity.com/docs/images/users-guide/Administration/admin-user-tfa-setup.png)

After this process the mobile application will generate a new code every 30 seconds that can be used to complete the authentication process.

### To revoke the secret {#to-revoke-the-secret}

If a user loses access to the TFA code, for example, if a user loses the phone or uninstalls the application, and needs to set it up again, the secret must be revoked.
TOTP must be set up by each user individually.


> **Requirements:**
> Users can not revoke their own TOTP secret. The secret of a user is only revoked by their respective parent user.
> See [Managing user hierarchies](https://cumulocity.com/docs/enterprise-tenant/managing-user-hierarchies/) for detailed information on user hierarchies.
>
> ROLES & PERMISSIONS:
>
> - To revoke a secret: ADMIN or CREATE permission for permission type "User management"



1. In the Administration application, navigate to **Accounts** > **Users** and select a user in the **Users** page.
2. Scroll down to **Login options**.
3. Click **Revoke TOTP secret**.
4. Confirm by clicking **Revoke**.

![TOTP secret revoke](https://cumulocity.com/docs/images/users-guide/Administration/admin-user-totp-revoke.png)

### To disable TOTP for a user {#to-disable-totp-for-a-user}

If a user wants to turn off the use of TOTP (and thus TFA) completely, the secret must be revoked and TOTP enforcement must be disabled.
TOTP must be set up by each user individually.


> **Requirements:**
> ROLES & PERMISSIONS:
>
> - To revoke a secret: ADMIN or CREATE permission for permission type "User management"
> - To disable TOTP enforcement: ADMIN permission for permission type "User management"



To disable TOTP for a user follow these steps:

1. In the Administration application, navigate to **Accounts** > **Users** and select the user in the **Users** page.
2. Scroll down to **Login options**.
3. Click **Revoke TOTP secret**.
4. Confirm by clicking **Revoke**.
5. Clear the **Enforce TOTP setup for the user** checkbox.
6. Click **Save** to save your changes.

![TOTP disable user](https://cumulocity.com/docs/images/users-guide/Administration/admin-user-totp-disable.png)