× Docs Platform Dashboard Extensions Applications Building Merchants Sign in

Multi-factor

The platform supports multi-factor for ensuring users are authenticated and/or authorized to access their account and associated resources.

Multi factor can be configured to trigger in a wide variety of situations, which means any integration with Rehive should be designed to expect challenges at any point and deal with them when they occur.

Resources

There are three resources you should be aware of when interacting with multi-factor authentication and authorization in the platform.

Authenticator rules

Authenticator rules are used to configure rules that should trigger when certain conditions are matched on a user accessing the platform.

There are two types of authenticator rules:

  • Authentication: These rules are evaluated when authenticating a user (such as on login). Every company automatically includes a single authentication type rule. This rule is used to perform the most basic multi-factor authentication, eg. when a user login occurs, a challenge is issues and must be completed to access the API.
  • Authorization: These rules are evaluated when checking a user’s permission to access a resource. No authorization rules are configured by default.

In addition to the authenticator types above, multi-factor rules can be configured to have different durabilities:

  • Permanent: A challenge issued by a permanent rule must only be completed once per login/session.
  • Durable: A challenge issued by a durable rule will last a set amount of time (configured in the duration field on a authenticator rule).
  • Ephemeral: A challenge issued by an ephemeral rule must be completed each time a resources is accessed that matches the configured permissions. The completed challenge must be submitted (and subsequently consumed) in the HTTP headers on the next request to that resource.

All rules can be configured to only trigger once the user’s session reaches a certain age.

When configuring authorization rules, a list of permissions is supplied. If authorization type multi-factor rules are configured and a user accesses a resource that requires one or more permissions configured on those rules a error response will be returned challenging them to complete a multi-factor challenge before proceeding.

Authenticators

The authenticator resource is used by users to add and manage the authenticators they can use to complete/verify multi-factor challenges.

There are currently three MFA authenticar types supported:

  • TOTP: Can be used with a compatible authenticator apps like Authy, Google Authenticator or 1Password.
  • SMS: Can be used with a valid mobile number. We encourage clients to use totp instead of sms if possible.
  • Static: Generates a list of one time passwords that can be used as secondary codes for recovery should a user lose access to their primary authenticator.

After creating an authenticator, it must be verified via the MFA verify endpoint. This is simply done by submitting an authenticator and the verification token for the specific authenticator. Only verified authenticators will be used for multi factor authenticator rules.

Authenticator challenges

Authentication challenges are issued when an authenticator rule is triggered. Multiple challenges can be issued on a single session and all the challenges will have to be completed if the user wants to continue to access the platform.

Each challenge is associated with a single session and a single rule. A challenge will also include a list of authenticator_types that can be used to complete/verify the challenge. This list is generated by getting the list of authenticators a user has configured and removing any that the specific authenticator rule does not support.

Usage

Take a look at the API Reference for the list of multi-factor endpoints.

All endpoints that contain /mfa/ in their URL path are used to handle multi-factor functionality.

When logging in and a challenge is issued, the login response will include a list of challenges like:

{
  "status": "success",
  "data": {
    "token": "{token}",
    "user": {

    },
    "challenges": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "authentication",
        "durability": "permanent",
        "authenticator_types": [
          "totp"
        ],
        "created": 1646233368264
      }
    ]
  }
}

When accessing an endpoint and a multi-factor challenge is required the response will look like:

{
  "status": "error",
  "message": "Multi-factor authentication required.",
  "data": {
    "challenges": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "type": "authorization",
        "durability": "permanent",
        "authenticator_types": [
          "totp"
        ],
        "created": 1646233368264
      }
    ]
  }
}

If a request returns a list of MFA challenges you should get the user to complete the challenges. This can be done by POSTing a token and the challenge ID to the MFA verify endpoint:

curl https://api.rehive.com/3/auth/mfa/verify/ \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"challenge": "00000000-0000-0000-0000-000000000000", "token": "XXXXXX"}'

The token must originate from one of the authenticator_types listed in the challenge response. And the challenge should be the ID returned on the challenge.