Multi-factor (MFA)

Multi-factor authentication (MFA) adds a second proof of identity on top of the user’s password. In Taranac, MFA is not bolted on at one entry point — it applies uniformly across the web admin UI, TACACS+ device administration, RADIUS AAA, and 802.1X / captive-portal network access. The same provider configuration drives every context, so a user who has enrolled MFA is challenged consistently wherever they authenticate.

Taranac supports both push factors (the user approves a login on a separate device — “bouncer” style) and OTP factors (the user types a time-based code). Push is what makes MFA usable on a network terminal: at a TACACS+ or RADIUS prompt the user enters only their password, the session waits, and an approval notification arrives on their phone — no awkward concatenation of password and code.

mfa · push challenge

tacacs+ · login

User noc-op

Pass ••••••••

waiting for approval…

access granted

Taranac MFA

Approve login?

noc-op · core-sw

Deny Approve

A push challenge: the user enters only their password at a TACACS+ login, the session waits, and an approval on their phone grants access.

Key concepts

Provider — the mechanism that delivers and verifies the second factor (TOTP, Telegram, Multifactor, Email push, or Taranac MFA). Each user has exactly one active provider, which the user chooses from the list you allow.
Mode — how a provider verifies: totp (user types a code), push (user approves/denies on a device), or combined (push with a TOTP fallback behind a single QR).
Enrollment — the one-time linking of a user to a provider. Every enrollment requires an activation step (the user confirms one push or types one code) before it becomes active.
Challenge — a single pending push request during login. It has a short TTL (120 s by default) and ends as approved, denied, or expired.
mfa_required (group flag) — MFA is made mandatory through group membership, not per user. Any group a user belongs to that has mfa_required set forces that user to have MFA. Providers themselves are not pinned to groups — the user always picks their own provider.

Supported providers

These are the five providers shipped in Taranac. Do not expect others.

Provider	Category	Modes	What the user needs
TOTP	Local	`totp`	Any authenticator app (Google Authenticator, Aegis, etc.)
Telegram	External	`push`	A Telegram account, linked to a bot you run
Multifactor	External	`push`, `totp`	A Multifactor (RADIUS) account
Email push	Hybrid	`push`	A working email address (uses your existing SMTP)
Taranac MFA	External	`combined`, `totp`	The Taranac MFA mobile app (push via FCM, TOTP fallback)

Categories:

Local (TOTP) runs entirely on the server with no external dependency. Codes are generated and verified locally. This is the most resilient option — if the backend’s outbound network or an external service is down, TOTP users still authenticate.
External providers reach an outside service: Telegram via the Bot API, Multifactor over the RADIUS protocol, Taranac MFA over its own REST API.
Hybrid (Email push) sends an approve/deny link through your SMTP server; the link points back to Taranac.

The Taranac MFA provider talks to a separate Taranac MFA Server — an API-only push/OTP engine running as its own container with its own database, reached over HTTPS. Because it is fully decoupled, you can detach it and place it in a DMZ when you want the push/OTP engine isolated from the core platform. It works push/poll: Taranac opens a challenge, the user approves in the Taranac MFA mobile app (delivered via Firebase Cloud Messaging), and the login polls until the result lands. TOTP is the built-in fallback — in combined mode the same enrollment QR backs both, so a user whose phone has no connectivity for the push can still read an offline code from the app. This self-hosted push-with-OTP-fallback design is what makes it the most seamless second factor for terminal logins.

Default verification mode per provider

When a user enrolls, the provider starts in its default mode:

Provider	Default mode
TOTP	`totp`
Telegram	`push`
Multifactor	`push`
Email push	`push`
Taranac MFA	`combined`

Context	TOTP (code)	Push (Telegram / Multifactor / Email / Taranac MFA)
Web admin UI	Code entered in the login form	Browser shows a “waiting for approval” screen and polls until approved
TACACS+ (device CLI)	Code appended to the end of the password	Session waits; push lands on the user’s device; on approval, access is granted
RADIUS (AAA)	Code appended to the end of the password	RADIUS challenge waits for the push result
802.1X / captive portal	Code in the captive-portal form	Browser/portal polls until approved

Enrolling a user

Enrollment is self-service: a user opens their MFA settings, picks an allowed provider, and confirms it once.

The user opens MFA setup in the web UI and selects a provider from the list of those you’ve enabled.
Taranac starts the enrollment and returns whatever the provider needs — a QR code and secret (TOTP, Taranac MFA), a Telegram deep link / QR, or a test push / email.
The user completes the activation step:
- TOTP / Taranac MFA (totp): scan the QR in an authenticator app, then type the first code.
- Telegram: open the deep link, press Start in the bot to link the account.
- Push providers: approve the test push (or type the fallback code).
On success the enrollment becomes active and (for TOTP) backup codes are shown once.

Helping users get started: setup links

You do not have to walk each user through enrollment. From the admin UI you can send a setup link to a single user or to an entire group at once. The link lets the recipient configure MFA without a full login, and is single-use and time-limited (default 60 minutes). This is the practical way to roll MFA out to a team after you flip mfa_required on their group.

Making MFA mandatory

Mandatory MFA is driven entirely by groups:

Edit the group whose members must use MFA and enable mfa_required.
From then on, any member who has not enrolled is forced to set up MFA before they can complete login. In the web UI they are sent to enrollment; in TACACS+/RADIUS the login fails until enrollment is done (typically via a setup link).

Users not in any mfa_required group may still enroll voluntarily — Taranac honours their second factor without forcing it.

Administering existing users

Action	Where	Effect
View a user’s MFA status	User detail	Shows the active provider and mode
Reset a user’s MFA	User detail	Removes their enrollment — use when a device is lost
Regenerate backup codes	User detail (TOTP)	Issues a fresh set of one-time recovery codes
Send setup link	User / group	Emails a one-time enrollment link
Enable/disable a provider	System settings	Controls which providers users may choose

When to use which provider

If you need…	Choose	Why
Maximum resilience, no external dependency	TOTP	Works offline; survives a backend outage; nothing to operate
Smooth approvals for network logins, self-hosted	Taranac MFA	Push via your own MFA server + FCM, with TOTP fallback in one enrollment
Push without running a mobile backend	Telegram	Uses a Telegram bot you create; familiar to most users
To reuse an existing Multifactor deployment	Multifactor	Speaks RADIUS to your Multifactor service; push or TOTP
A zero-install fallback for occasional users	Email push	Approve/deny by email link; uses your existing SMTP

General guidance:

Always keep TOTP enabled. It is the only provider with no external dependency and is the safe last line of defence if push delivery fails.
For device administrators logging in over TACACS+/RADIUS, prefer a push provider (Taranac MFA or Telegram) so they never have to append codes.
Email push is convenient but only as strong as the user’s mailbox — treat it as a fallback rather than the primary factor for privileged accounts.

Provider health

Taranac actively checks that each enabled provider can do its job, so you can spot a broken second factor before users are locked out:

Provider	Health check
TOTP	Always healthy (local, no dependencies)
Email push	SMTP server reachable (EHLO)
Telegram	Bot API reachable and token valid (`getMe`)
Taranac MFA	MFA server, its database and crypto reachable (`/healthz`)
Multifactor	RADIUS Status-Server responds

A failing provider raises a system alert and is treated as unavailable during login (502-style error to the user), so they aren’t silently stranded.

Reference

Key system settings (`mfa.*`)

Setting	Default	Purpose
`mfa.mode`	`enabled`	Global on/off switch for MFA
`mfa.challenge.ttl`	`120` s	How long a push challenge stays valid
`mfa.backup_codes.enabled`	`true`	Generate TOTP backup codes
`mfa.backup_codes.count`	`10`	Number of backup codes per TOTP enrollment
`mfa.<provider>.enabled`	see note	Whether users may choose a given provider

What MFA records in the audit log

Every MFA action is audited: enrollment and activation, removal, each verification success or failure, push approved / denied / expired, admin reset, backup-code use, and Telegram link/unlink. Use these events (under the authentication log) to investigate suspicious approvals or repeated failures.

Users & groups — reset MFA, regenerate backup codes, send setup links, and set mfa_required on a group
RBAC — the mfa.view / mfa.edit permissions that gate MFA administration
LDAP directories — directory-backed users can also enroll a second factor
AAA logging — where MFA audit events surface
Deployment bundle & full specs: github.com/TaranacLabs/taranac