Skip to main content
API7.ai Logo
Version: 3.10.x

Two-Factor Authentication

Built-in Dashboard users can protect their accounts with two-factor authentication (2FA), using time-based codes from an authenticator app. Administrators can also require 2FA for all built-in users. The requirement is off by default.

Enable 2FA for Your Account​

Available in API7 Enterprise from version 3.10.3.

  1. In the API7 Dashboard, open your user profile.
  2. For Two-Factor Authentication, click Enable.
  3. Scan the QR code with your authenticator app, or enter the setup key manually.
  4. Enter the generated code and click Verify and enable.
  5. Store the recovery codes somewhere safe, then click Done.

You receive 10 recovery codes, and they are shown only once. From then on, each login asks for your password, then for a code from the app or a recovery code.

HTTP Basic Auth cannot carry a second factor, so requests that use it for your account are rejected with status 401 once 2FA is on. Use a token for automation instead.

Require 2FA for Built-In Users​

Available in API7 Enterprise from version 3.10.10.

The requirement applies to built-in users, who log in with a username and password, including the default admin account. SSO logins are not subject to it, whether they use LDAP, OIDC, CAS, or SAML.

Requests authenticated with a token or a gateway group admin key are also unaffected, even when the token's owner has not enabled 2FA.

Before You Turn It On​

The requirement takes effect immediately, with no grace period. Prepare for it in this order:

  1. Move scripts and integrations that use HTTP Basic Auth to tokens. With the requirement on, Basic Auth returns 401 for every built-in user, including those with 2FA.
  2. Enable 2FA on your own account. If you are a built-in user without 2FA, turning the requirement on fails with status 409 and the error enable two-factor authentication for your own account before requiring it. The same applies to a token you own.
  3. Tell built-in users that the next thing they do in the Dashboard will be to enroll.

Configure the Requirement​

To turn on the requirement in the Dashboard:

  1. In the API7 Dashboard, navigate to Organization > Settings.
  2. On the Login Options tab, find Require Two-Factor Authentication and turn on the switch.
  3. Review the consequences in the dialog and click Enable.

Turning the switch off takes effect at once and asks for no confirmation.

To configure the same setting through the Admin API, send a PUT request. A GET request to the same path returns the current value.

curl -k "https://localhost:7443/api/system_settings/two_factor_policy" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "require_two_factor": true
  }'
FieldTypeRequiredDefaultDescription
require_two_factorBooleanYesfalseWhether built-in users must enable 2FA.

Required Permissions​

The following actions apply to the arn:api7:iam:organization/* resource. In the permission policy editor, they appear under the Two-Factor Policy resource type.

ActionAllows
iam:GetTwoFactorPolicyViewing the setting. Users without this action do not see the Require Two-Factor Authentication card.
iam:UpdateTwoFactorPolicyChanging the setting.

Each update is recorded in the audit logs with the UpdateSystemSettings event type.

What Users Without 2FA See​

A built-in user without 2FA can only enroll or log out, and this includes users who already have a session open. The Dashboard takes them to a page that offers only these two actions. After enrolling and saving their recovery codes, they carry on where they were.

If a password change is also due, it comes first. The user changes the password, logs in with the new one, and then enrolls.

API clients see the same order. POST /api/login still returns status 200 and creates a session, with the warning_msg value two factor enrollment required. Later requests return status 401 with the same warning_msg, except for the following:

  • GET /api/me
  • POST /api/me/2fa/setup
  • POST /api/me/2fa/enable
  • POST /api/logout

A user who later disables their own 2FA, or whose 2FA an administrator resets, is held back in the same way until they enroll again.

Limits on Verification Codes​

Available in API7 Enterprise from version 3.10.10.

The following limits always apply to built-in users with 2FA, with or without the requirement. They are fixed values.

Lockout after Wrong Codes​

Five consecutive wrong codes lock the user's second factor for 15 minutes. Authenticator codes and recovery codes count alike, and so do attempts at login and when disabling 2FA.

During the lock, every code is refused, including correct ones, and recovery codes are not consumed. The request returns status 400 with the error too many failed login attempts, this account is temporarily locked; please try again in about N minute(s). The fifth wrong code itself still returns invalid verification code.

The count returns to zero after a correct code or when the lock expires. To end a lock early, reset the user's 2FA.

Entering the lock writes one entry to the audit logs with the UserLoginBanned event type. Too many failed passwords write the same event, and the entry does not say which of the two caused it.

Single-Use Codes​

Each code works once. A replayed authenticator code counts as a wrong code toward the lockout, and so does an earlier code from the same app. Each recovery code is removed once it is used.

As a result, if you log in and then disable 2FA, wait for the app to show a new code. The code that confirms a new 2FA setup is an exception: you can use it to log in straight away.

Reset 2FA​

Resetting clears the user's second factor, along with their recovery codes and any lock. The user can then log in with only a password, and the requirement, if it is on, sends them back to enrollment.

Reset Another User's 2FA​

Available in API7 Enterprise from version 3.10.3.

Users with the iam:ResetTwoFactor action can navigate to Organization > Users and choose Reset 2FA for that user. The same reset is available as PUT /api/users/{user_id}/2fa_reset. It does not end the user's existing sessions.

This reset does not work on the default admin account. Use the recovery command below for that account.

Recover Access with the Reset Command​

Available in API7 Enterprise from version 3.10.10.

The recovery command works without logging in, so it is the way back when the admin account has lost its authenticator app and recovery codes. It clears the second factor of any user you name and also ends that user's sessions, effective immediately.

The command is part of the Dashboard binary. Run it with exec inside the running Dashboard container. The image has no shell, so call the binary directly.

On Helm and Kubernetes, the command reads the default configuration path. Adjust the namespace and the Deployment name to match your release:

kubectl -n api7 exec deploy/api7ee3-dashboard -- \
  /usr/local/api7/api7-ee-dashboard two-factor reset --username admin

On Docker Compose, run the command from the directory that contains docker-compose.yaml and pass the configuration path that the Compose file mounts. The quickstart script and the offline bundle name the Dashboard service api7-ee-dashboard, as below. If you followed the manual deployment in Deploy with Docker Compose, the service is named dashboard instead:

docker compose exec api7-ee-dashboard \
  /usr/local/api7/api7-ee-dashboard two-factor reset --username admin \
  -c /usr/local/api7/conf/conf.yaml

A successful run prints the following:

two-factor authentication reset for user "admin", sessions expired
caution

The command connects straight to the database and does not write an audit log entry. Restrict who can exec into the Dashboard container.

Next Steps​