Multi-factor | Rehive documentation

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

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 by administrators to configure when MFA challenges should be issued to users. All rules can be configured on the global “company” level or alterntaively on specific user groups. A group-specific rule will always take precedence over a non-group rule when evaluating challenges.

Types

There are three types of authenticator rules:

Authentication: These rules are evaluated when authenticating a user (such as on login). When a user login occurs, a challenge will be issued and the user will be required to verify their access to proceed. By default, all companies start with a single authentication type rule.
Authorization: These rules are evaluated when checking a user’s permission to access a resource. If a user accesses a resource that requires MFA then they will be challenged to verify their access. No authorization rules are configured by default.
Setup: These rules are evaluated when checking what authenticators a user has enabled. If a user does not have the correct authenticators configured they will be challenged to setup an authenticator to proceed. No setup rules are configured by default.

When configuring authorization rules, a list of permissions must be supplied. If a resource is accessed via the API and it has matching permission requirements to an authenticator rule then it will immediately trigger a challenge that the user will be required to complete before proceeding.

Durability

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.

Only authorization type rules can be configured to be ephemeral. Setup rules must always be configured as permanent.

Authenticators

Authenticators are the resource used to 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. Challenges issued by authorization and authentication rules will block access to all authenticated endpoints. However, challenges issued by setup rules will still allow a user to access the endpoints for creating, listing and viewing authenticators.

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 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 Platform API Reference for the list of multi-factor endpoints.

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

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

Similarly, when accessing any other user-authenticated endpoint and a multi-factor challenge is issued 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 "Authorization: Token {token}" \
  -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.

When dealing with ephemeral challenges you will need to store the challenge ID after it is verified and then on the next request (to the resource that triggered the challenge) include it in an HTTP header Verified-Challenge: {challenge_id}. This will allow the user to access the resource once. All subsequent requests to the same resource will need to be multi-factored separately.

Some authenticator types (for instance, the sms type) support token delivery. On login, when possible, the token will be delivered automatically. However, if a user needs to request re-delivery of a token, they can do so via the the MFA deliver endpoint:

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

When requesting delivery of a token in order to verify an authenticator, ensure that the challenge in the above code-sample is replaced with the authenticator and its corresponding id.