Identity & access

Authenticator-app MFA (TOTP)

Closes the single-password risk on operator accounts by requiring a code from an authenticator app.

Available in previewEngine edition 5f8ea3af

What it does

Time-based one-time passwords for platform (operator) accounts. A user enrols an authenticator app, proves possession with a first code, receives ten single-use recovery codes, and from then on sign-in needs a code after the password. Administrators can require enrolment for every admin account, and sensitive administrative actions can require a fresh code.

How it works

Enrolment is two calls. POST /v1/auth/2fa/enroll returns a base32 secret and an otpauth URI for an authenticator app. POST /v1/auth/2fa/activate with the current six-digit code switches the factor on and returns ten recovery codes, shown once; their SHA-256 hashes are what is stored. Codes follow RFC 6238 with HMAC-SHA-1, a 30-second step, six digits, and one step of clock skew accepted on either side. Code generation is covered by tests that use the RFC 4226 and RFC 6238 test vectors.

When a platform account has TOTP enabled, a correct password returns mfa_required and a pending token valid for five minutes instead of session tokens. POST /v1/auth/2fa/verify with the pending token and a TOTP or recovery code completes sign-in. Ten wrong codes in a row lock the factor for five minutes. A recovery code works once, and using one sends a separate email notice.

Setting KYNETRA_REQUIRE_2FA_ADMIN to 1 makes admin and super_admin accounts without a factor receive an enrolment challenge at sign-in. They can reach just the enrol and activate steps, and a session is issued after, and not before, the recovery codes are acknowledged. Separately, POST /v1/auth/2fa/step-up exchanges a fresh code for a single-use step-up token valid for five minutes. An administrator who has a factor needs that token to change a role, set a password or reset another account's factor.

Activation, self-service disable, recovery-code use and administrator resets send an email notice that never contains the secret or a code. Activation and the administrator actions are also written to the audit trail.

POST /v1/auth/2fa/disable with a current code removes the factor, and an administrator can clear another account's factor, which needs a step-up token when the administrator has a factor of their own. GET /v1/auth/2fa reports whether the account is enrolled and enabled, and how many recovery codes remain.

Where you reach it

  • HTTPGET /v1/auth/2fa, POST /v1/auth/2fa/enroll, POST /v1/auth/2fa/activate
  • HTTPPOST /v1/auth/2fa/verify, POST /v1/auth/2fa/recovery/ack, POST /v1/auth/2fa/disable
  • HTTPPOST /v1/auth/2fa/step-up
  • CLIkynetra admin 2fa-status | 2fa-enroll | 2fa-disable --code <code> | 2fa-reset --email <email>
  • ConfigKYNETRA_REQUIRE_2FA_ADMIN, KYNETRA_2FA_ISSUER

Example

Enrol an authenticator appbash
# Signed in as a platform account: start enrolment
curl -s -X POST "$KYNETRA_URL/v1/auth/2fa/enroll" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" -d '{}'
# returns {"secret": "...", "otpauth_uri": "otpauth://totp/..."}; add it to an authenticator app

# Prove possession with the current code
curl -s -X POST "$KYNETRA_URL/v1/auth/2fa/activate" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'
# returns {"enabled": true, "recovery_codes": [ ... ]}; store them now, they are not shown again

Limits

  • TOTP covers platform (operator) accounts. Project end-user pools are not gated by it.
  • An authenticator app is the one second factor. SMS codes and passkeys are not available.
  • The enrolment secret is stored in the engine alongside other authentication records. Protect the data directory and its backups accordingly.
  • Recovery codes are shown once at activation. A lost factor is cleared by an administrator, and the reset is audited and notified.

Evidence

  • On this siteAPI reference: authentication endpoints
  • On this siteSecurity overview
  • Tests24 auth-crate tests (enrol, activate, verify; single-use recovery codes; lockout; step-up tokens; forced enrolment with recovery acknowledgement; concurrent attempts), 5 code-generation tests with the RFC vectors, and 8 server tests

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to try this against your own workload.