Two-factor authentication

Authentication

Medable employs session-based (using cookies) and signature-based authentication. Within each org, applications can be created which provide the necessary key and secret for API access.

For more information on Cortex authentication, see Authentication

As one of the many technical safeguards built into Medable, two-factor authentication helps ensure security and compliance so as a user you can be sure no one can gain access to your sensitive data and as a company, you can be sure that your users are who they say they are.

How does it work?

Two-factor authentication is automatic and always on. When Medable detects that a user is authenticating from a new location or device, a verification code is sent to the mobile number for that user. The user simply has to provide that authentication code to be authenticated and for the new location or device to be verified.

An example of this in use can be seen right from the login screen for your org's control panel. Here we'll attempt to login to the control panel from a new device.

As a developer, how do I enable 2FA in my app?

You don't have to do anything to enable 2FA in the API. It works automatically when a user authenticates. However, you do want to be sure to build in the right interface and user-experience in your app for 2FA exception handling.

When authenticating via the API, if 2FA is initiated, you will receive a kNewLocation fault in the response:

POST /accounts/login

Request Body:

{
  "email":"john@newhealthco.com",
  "password":"This is not the password!"
}

Response Body:

{
   "object":"fault",
   "name":"location",
   "code":"kNewLocation",
   "status":200,
   "message":"A new location has been added to the account. Please verify it"
}

At this point the user will be sent their verification code via SMS. You can use the kNewLocation fault to trigger your UI to present the user with the verification code field.

Then, the token will need to be passed in the second authentication request:

POST /accounts/login

Request Body:

{
  "email":"john@newhealthco.com",
  "password":"This is not the password!",
  "location": {
    "verificationToken": "638393"
  }
}

Response Body:

{
    "_id":"575f58281d0c03a53ccc3ac6",
    "object":"account",
    "created":"2016-06-14T01:04:40.888Z",
    "updated":"2016-06-14T01:08:06.647Z",
    "updater":{
       "_id":"575f58281d0c03a53ccc3ac6",
       "object":"account",
       "path":"/accounts/575f58281d0c03a53ccc3ac6"
    },
    "access":6,
    "favorite":false,
    "email":"john@newhealthco.com",
    "name":{
       "first":"John",
       "last":"Smith"
    },
    "mobile":"+15555555555",
    "locale":"en_US",
    "state":"verified",
    "locked":false,
    "key":{
       "fingerprint":"73ad85a0-31cc-11e6-ba07-3f24c7443557",
       "secret":"PXXvBvG86sJC2RVk4X6K4FV0OUH7ojzp"
    },
    "roles":[
       "000000000000000000000004",
       "000000000000000000000007",
       "000000000000000000000006"
    ],
    "shared":false
}

With location.verificationToken sent, the location is verified and authentication is successful. Future authentication attempts from this location will not require 2FA.

How does this impact user experience?

Two-factor authentication does require the user to take an extra step in order to authenticate. However, most users rarely run into it in day-to-day use. This is because when a user registers their account, the device they register from is automatically verified. So if the user typically uses the app on one device, 2FA will never be initiated. Only if the user logs in from a different device or deletes and re-installs the app will the 2FA process initiate.

It's also important to note that this extra step is there to help ensure that the user's data is secure. Often when this added level of security is explained to users, it is seen as a positive.

Typically the only users that are negatively impacted by 2FA are developers since developers often need to test apps from multiple accounts and devices. Because of this, we allow for bypassing 2FA by adding email address for developers to the Location Verification Bypass setting under Settings > Organization in the control panel (see Organization Settings for more info).

Last updated