Account Security

Multi-Factor Authentication

Soracom provides an additional layer of security for root account 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 account password or SAM User password in order to access the Soracom User Console, or to generate API keys and tokens.

Soracom Multi-Factor Authentication mechanism uses the RFC 6238 specification.

Enabling MFA

Root Account

  1. Login to the User Console.

  2. Click your account menu, then select Security.

    https://console.soracom.io

    Account security

  3. Click the Multi-factor Authentication tab.

  4. Click the Enable MFA button.

    https://console.soracom.io

    Enable MFA

  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 or Google Play Store).

    Scan QR Code and confirm MFA

    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.

For your security, MFA will not be enabled if an incorrect code is applied.

If you are enabling Multi-Factor Authentication for your root account, 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

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 log in to your Soracom account.

Current SAM User

If you are logged 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 Enable MFA button.

    https://console.soracom.io

    Enable MFA for the current SAM User

  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 logged in using your root account, or when logged 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. Click the Multi-factor Authentication panel, then click the Enable button.

    https://console.soracom.io

    Enable MFA for another SAM User

  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.

Logging In with MFA Enabled

User Console

  1. Open the User Console.

  2. Login as normal using your root account Email address and Password, or Operator ID, SAM Username, and Password.

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

    https://console.soracom.io

    MFA Verification Code

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 passing in a mfaOTPCode parameter as part of the authentication request payload.

To authenticate using your root account, make an HTTP POST request to the /auth endpoint with the following body:

{
  "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:

{
  "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 account:

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

To authenticate as a SAM User:

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.

When setting up Soracom CLI for the first time, you can use the soracom configure command to save authentication credentials (root account, 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.

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 Account

  1. Login to the User Console.

  2. Click your account menu, then select Security.

    https://console.soracom.io

    Account menu

  3. Click the Multi-factor Authentication tab.

  4. Click the Disable MFA button.

    https://console.soracom.io

    Disable MFA

Current SAM User

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

Other SAM Users

When logged in using your root account or as another SAM User with suffucient 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.

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

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, please contact Soracom for assistance.

  1. Open the User Console.

  2. Login as normal using your root account email address and password.

  3. When prompted to enter your MFA verification code, click the Trouble finding your MFA verification code? link.

    https://console.soracom.io

    Revoke MFA link

  4. Enter your root account email address and password again to confirm that you want to begin the MFA revocation process.

    https://console.soracom.io

    Start MFA revocation

  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

  6. Finally, enter your root account E-mail Address, Password, and your MFA Backup Codes to confirm revocation.

    https://console.soracom.io

    Confirm revoking MFA

Once the MFA setting has been revoked, you will be able to login to your root account without using an MFA verification code.