Multi-factor authentication

Multi-factor authentication (MFA) uses additional verification method, beside the standard credentials as login, password, and accountId. MFA in Xively uses a time-based one-time password (TOTP) generated by the LastPass Authenticator app or sent via text message. For higher security, it is recommended to enable MFA for some user roles, for example for a firmware manager. A user with MFA enabled, is asked for a time-based one-time password in order to proceed with their actions in Xively.

To enable the MFA feature, contact Xively. Consider which groups of users should have this feature active, for example: firmware managers, users with read-only access, or all admins. MFA can also be enabled for end-users.

Admins with MFA enabled are asked to set it up at the time of their first login since the feature has been enabled (see: Setting up MFA in the Xively management app). After the setup, they are required to provide the additional verification code when logging in and before crucial operations, for example when deploying a firmware package (this relates only to admins who are firmware managers).

Setting up MFA in the Xively management app

If MFA has been enabled for you by Xively, there are a few steps for you to follow to set it up:

Prerequisite: Before you log in to the Xively management app with MFA, have your phone at hand to install the LastPass Authenticator app and to receive a text message with one-time generated code.

  1. Log in to the Xively management app with your credentials.
    Result: You are redirected to a page with basic information about two-step verification.

  2. Click Continue.
    Tip: Make sure your browser allows pop-ups from app.xively.com.

  3. Follow on-screen instructions to set up the authentication method:

    • Set up the LastPass Authenticator app and pair it with your Xively account.
    • Set up a backup authentication method via text messages.
      Result: When done, you see green check marks:
  1. Click Activate.

  2. On the confirmation page, click Done.
    Result: You are logged in to Xively, your MFA is activated and set up.

Editing MFA settings

  1. In the Xively management app, click on the cogwheel in the top right-hand corner of the page and select My profile.
  1. Scroll to the bottom of the "User settings" page.
  1. Click Edit Settings to pair LastPass Authenticator with another mobile device or modify your telephone number.
    Tip: Make sure your browser allows pop-ups from app.xively.com.

Logging in to the Xively management app with MFA

After you set up MFA, Xively asks you to enter the verification code at every login.
Enter the code from LastPass Authenticator or use the backup option to receive the code as a text message on your phone.

Deploying a firmware package with MFA

This case relates only to admins with proper privileges to manage firmware deployments.

When deploying a firmware or a file package from test to production, you are asked to enter the code from LastPass Authenticator or use the backup option to receive the code as a text message on your phone. For the details, see Firmware updates (admin side).

MFA for end-users and applications

End-users and applications also can use MFA when logging in to Xively. With MFA enabled, behavior of the login API endpoint differs from its standard operation. If you plan to enable MFA for your end-users and applications, take into account that you will need to handle the special way API responses to login calls.

See the following examples of calls to IDM login endpoints for an end-user with MFA. Look at the response code and response body, and make sure your application can handle these calls.

Logging an end-user with MFA

  1. Log in the end-user.
    Call POST to the IDM /auth/login-user endpoint, see Log in.
// Request example:
{
    url: "https://id.xively.com/api/v1/auth/login-user",
    method: "post",
    body: {
        "emailAddress": "<end-user's email address>",
        "password": "<end-user's password>",
        "accountId": "<your accountID>"
    }
}

// Response:
HTTP/1.1 202 Accepted
{
    body: {
        "mfaToken": "<end-user's mfa token>",
        "csrfToken": "<end-user's csrf token>"
  }
}

The response code 202 means that the request has been accepted for processing, but the processing has not been completed. Further verification is needed.
Result: The end-user's multi-factor authentication (MFA) token is returned that will be used in the next steps. The user is not yet logged in.

  1. Let the end-user decide if he wants to log in with the LastPass Authenticator or a text message code.
  2. If the end-user logs in with a text message code, call POST to the IDM auth/mfa-trigger-auth endpoint. See Multi-factor authentication trigger.
    If the end-user logs in with LastPass Authenticator, go to the next step.
// Request example:
{
    url: "https://id.xively.com/api/v1/auth/mfa-trigger-auth",
    method: "post",
    body: {
        "mfaMethod": "sms"
    },
    headers: {
        "xively-mfa-token": "<end-user's mfa token>"
    }
}

// Response:
HTTP/1.1 202 Accepted
{
    body: {
        "status": "poll"
    }
}

Result: The end-user gets a text message with the code.

  1. Provide the end-user's verification code from LastPass Authenticator or from the text message.
    Call POST to the IDM /auth/mfa-login-user endpoint, see Log in with MFA code:
    • To use the LastPass Authenticator code, set: "mfaMethod": "totp".
    • To use the code from the text message, set: "mfaMethod": "sms".
// Request example:
{
    url: "https://id.xively.com/api/v1/auth/mfa-login-user",
    method: "post",
    body: {
        "mfaMethod": "<set to totp or sms depending on the verification method>",
        "code": "<end-user's verification code generated by LastPass Authenticator or received in a text message>"
    },
    headers: {
        "xively-mfa-token": "<end-user's mfa token>"
    }
}

// Response:
HTTP/1.1 200 OK
{
    "status": "allowed",
    "jwt": "<end-user's JWT starting with: eyJ0e...>",
    "csrfToken": "<end-user's new csrf token>"
}

Result: The status is returned. If it is "allowed", the user is logged in and his JWT is returned.

  1. Use the end-user's JWT for authorization during the current session.
    Use authorization header when calling API endpoints.
headers: {
        "authorization": "Bearer <JWT of the end-user>"
}

Multi-factor authentication