# Multi-Factor Authentication

MFA configuration for improved user access security.

Soracom provides an additional layer of security for Root user access as well as SAM user access with Multi-Factor Authentication (MFA), also known as Two-Factor Authentication (2FA). When enabled, a secure key will be generated which can then be registered to a device that you physically control, such as a smartphone with a compatible MFA application. Once the secure key is registered, the MFA application will generate a temporary 6-digit code, which will be required in addition to your Root user password or SAM user password in order to access the Soracom User Console, or to generate API keys and tokens.

Soracom's Multi-Factor Authentication uses the RFC 6238 specification.

## Enabling MFA

### Root User

1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**.

2. Click your **account menu**, then select **Security**.

   ![Account security](https://docs.soracom.io/_astro/security.DBJpDk05_uB409.webp)

3. Click the **Multi-factor Authentication** tab.

4. Click the **Enable MFA** button.

   ![Enable MFA](https://docs.soracom.io/_astro/enable-mfa.CJPnA-Ki_2ldyra.webp)

5. A QR code containing a secure key will appear. Scan the QR code using an MFA application such as **Google Authenticator** (available on [Apple App Store](https://apps.apple.com/us/app/google-authenticator/id388497605) or [Google Play Store](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2\&hl=en\&noprocess=id)).

   ![Scan QR Code and confirm MFA](https://docs.soracom.io/_astro/confirm-mfa.DLPP0W8O_Z22BEDV.webp)

   The MFA application will automatically register the secret key to your device. Once registered, you should see that the MFA application is generating temporary 6-digit verification codes.

6. Enter the 6-digit verification code that appears in the MFA application in order to confirm that the secret key has been correctly registered.

> [!NOTE]
>
> For your security, MFA will not be enabled if an incorrect code is applied.

If you are enabling Multi-Factor Authentication for your Root user, several backup codes will be displayed. These codes are used to revoke the Multi-Factor Authentication setting in case you lose access to your MFA device. When revoking MFA, you will be asked to enter one of these codes.

![MFA backup codes](https://docs.soracom.io/_astro/backup-codes.Irmqirp2_Z1iaajz.webp)

> [!NOTE]
>
> It is imperative that you keep a copy of your backup codes in a secure location. If your MFA device is lost or damaged and you do not have any of your backup codes, you will no longer be able to sign in to your Soracom account.

### Current SAM User

If you are signed in as a SAM user, you can enable MFA for your SAM user account.

1. Click your **account menu**, then select **Security**.

2. Click the **SAM User Multi-factor Authentication** tab.

3. Click the + button.

   ![Enable MFA for the current SAM User](https://docs.soracom.io/_astro/current-sam-user-enable-mfa.B6enDUdh_M7brR.webp)

4. Follow the instructions above for registering the secret key to your MFA device and confirming that the secret key has been correctly registered.

No backup codes will be displayed when enabling MFA for a SAM user.

### Other SAM Users

You can also enable MFA for other SAM users in your account. This can be done either when signed in using your Root user, or when signed in as another SAM user with sufficient privileges.

1. Click your **account menu**, then select **Security**.

2. Click the **Users** tab.

3. Click the **Name** of the SAM user you want to manage.

4. Click the **Authentication** tab.

5. Expand the **User Authentication** section, then click the + button.

   ![Enable MFA for another SAM User](https://docs.soracom.io/_astro/other-sam-user-enable-mfa.DqkqMGdz_iyzuj.webp)

6. Follow the instructions above for registering the secret key to your MFA device and confirming that the secret key has been correctly registered.

No backup codes will be displayed when enabling MFA for a SAM user.

## Signing in with MFA Enabled

### User Console

1. Open the [User Console](https://console.soracom.io/?coverage_type=g).

2. Sign in as normal using your Root user **Email address** and **Password**, or **Operator ID**, SAM **Username**, and **Password**.

3. You will be prompted to enter your **OTP Code**. Open your MFA application and enter the 6-digit verification code.

   ![MFA Verification Code](https://docs.soracom.io/_astro/login-mfa.xGj16oah_12iB3z.webp)

> [!NOTE]
>
> If the date and time of the device with your MFA application deviates significantly from the actual current date and time, the MFA verification codes will be out of sync. Ensure that your device date and time is updated appropriately.

### Soracom API

When using the Soracom API, you must perform authorization using the **auth** API endpoint and pass a `mfaOTPCode` parameter as part of the authentication request payload.

To authenticate using your Root user, make an HTTP `POST` request to the `/auth` endpoint with the following body:

```json
{
  "email": "sora@soracom.io",
  "password": "myP@assw0rd",
  "mfaOTPCode": "123456"
}
```

To authenticate as a SAM user, make an HTTP `POST` request to the `/auth` endpoint with the following body:

```json
{
  "operatorId": "OP0012345678",
  "userName": "myuser",
  "password": "myP@ssw0rd",
  "mfaOTPCode": "123456"
}
```

If authentication is successful, you will receive a `200` HTTP response with JSON response that contains `apiKey` and `token` parameters. You can then use these **API key** and **token** values to call other API endpoints.

### Soracom CLI

When using the Soracom CLI, you must perform authentication using the `soracom auth` command and passing in the MFA verification code using the `--mfa-otpcode` option.

To authenticate using your Root user:

```bash
soracom auth --email sora@soracom.io --password myP@ssw0rd --mfa-otpcode 123456
```

To authenticate as a SAM user:

```bash
soracom auth --operator-id OP0012345678 --user-name myuser --password myP@ssw0rd --mfa-otpcode 123456
```

If authentication is successful, the command will return a response that contains `apiKey` and `token` parameters. You can then use these **API key** and **token** with other Soracom CLI commands by specifying the `--api-key` and `--api-token` flags, respectively.

> [!WARNING]
>
> When setting up Soracom CLI for the first time, you can use the `soracom configure` command to save authentication credentials (Root user, SAM user, or AuthKeys) so that they are used with each command. However, the credentials stored using this configuration command cannot be used together with MFA. As a result, you must run the `soracom auth` command above in order to generate an **API key** and **token**, and then perform subsequent commands using the `--api-key` and `--api-token` flags.

## Disabling MFA

If you no longer wish to use Multi-Factor Authentication, you can disable it from the User Console by simply reversing the steps above.

> [!NOTE]
>
> You must have access to your MFA application and verification codes. If you have lost your MFA device and cannot view your MFA verification codes:
>
> - For root accounts: Use the **Revoking MFA** instructions below instead.
> - For SAM Users: delete the SAM User and re-create it.

### Root User

1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**.

2. Click your **account menu**, then select **Security**.

   ![Account menu](https://docs.soracom.io/_astro/security.DBJpDk05_uB409.webp)

3. Click the **Multi-factor Authentication** tab.

4. Click the **Disable MFA** button.

   ![Disable MFA](https://docs.soracom.io/_astro/disable-mfa.Cj12J-TG_Z1LsMmx.webp)

### Current SAM User

When signed in as a SAM user, follow the instructions above, and click on the **SAM User Multi-factor Authentication** tab instead.

### Other SAM Users

When signed in using your Root user or as another SAM user with sufficient privileges:

1. Click your **account menu**, then select **Security**.

2. Click the **Users** tab.

3. Click the **name** of the SAM User you want to manage.

4. Click the **Authentication** tab.

5. Click the **Multi-factor Authentication** panel, then click the **Disable** button.

## Revoking MFA

If you have lost your MFA device and are unable to view your MFA verification codes, you can revoke the Multi-Factor Authentication setting. This process requires one of the **backup codes** that were generated when MFA was originally enabled.

> [!WARNING]
>
> The revocation process applies to the root account only. If you need to revoke the MFA setting for a SAM User, ask your root account administrator to delete and re-create your SAM User.

> [!NOTE]
>
> The **backup code** is mandatory in order to prevent unauthorized users from revoking your MFA setting without your permission. If you are unable to access your MFA verification codes _and_ you have lost your backup code, contact Soracom for assistance.

1. Open the [User Console](https://console.soracom.io/?coverage_type=g).

2. Sign in as normal using your Root user **email address** and **password**.

3. When prompted to enter your MFA verification code, click the **Trouble logging in with MFA?** link.

   ![Revoke MFA link](https://docs.soracom.io/_astro/initiate-revoke-mfa.D2GT3tT8_Z6f9fO.webp)

4. Enter your Root user **email address** and **password** again to confirm that you want to begin the MFA revocation process.

   ![Start MFA revocation](https://docs.soracom.io/_astro/revoke-mfa.CiCOqo-Q_EsBpx.webp)

5. An email containing a URL will be sent to you. Click the link in the email to continue the revocation process.

   ![MFA revocation email](https://docs.soracom.io/_astro/revoke-mfa-email.CxwC_4qg_24YG3f.webp)

6. Finally, enter your Root user **Email Address**, **Password**, and your MFA **Backup Codes**, then click **Revoke MFA** to confirm revocation.

   ![Confirm revoking MFA](https://docs.soracom.io/_astro/revoke-mfa-confirm.DokTctyg_szfDk.webp)

Once the MFA setting has been revoked, you will be able to sign in to your Root user without using an MFA verification code.