Skip to content

Multi-Factor Authentication

Raise the bar from "something you know" to "something you have" — and prove who's really signing in.

What it is

HelixIAM offers a broad, modern set of authentication factors that you compose into your sign-in flows. You decide which factors a realm or application accepts, whether they're required for everyone, and whether they're requested conditionally as a step-up only when the moment calls for it.

Available factors

Factor Description Learn more
TOTP Time-based one-time passcodes from an authenticator app OTP factors
SMS-OTP One-time passcode delivered by text message OTP factors
Email-OTP One-time passcode delivered by email OTP factors
HOTP Counter-based one-time passcodes OTP factors
WebAuthn passkeys (FIDO2) Phishing-resistant platform & roaming authenticators Passkeys
Recovery codes Single-use backup codes for account recovery OTP factors
Magic-link passwordless email Sign in by clicking a one-time link OTP factors
Mobile device push Approve sign-in on an enrolled phone Device push

Step-up authentication

A flow can require an additional factor conditionally rather than for every login. Helix carries step-up challenge state through the flow, so a journey can authenticate a user with a primary factor and then demand a second factor only when a condition is met — for example a sensitive application, a high-value transaction, or an elevated risk signal.

Conditional beats mandatory

Requiring a second factor on every action creates friction. Use step-up to ask for stronger proof only where it matters, and keep everyday sign-in fast.

How it works

  1. Choose which factors a realm/application accepts.
  2. Add the factor as a method in a stage of your sign-in journey, and set when the stage runs (Always, Any one of or Only when).
  3. Users enrol their factor — from the account console or via a Required Action at next login.
  4. At sign-in, the flow engine challenges for the factor and, where configured, applies step-up only when the condition fires.

Watch: add a second factor

44 seconds, no sound. Add a factor to a flow, choose when it runs, then open the Require MFA switch in the realm settings (not saved). Recorded on the current release.

In the console

There is no separate MFA screen. Factors are placed in a flow on the Authentication page; whether MFA is mandatory realm-wide is a realm setting. The Authenticator app has its own page, Authenticator app (see Device push).

  1. Open Authentication, pick the flow and add the factor with + method in a stage (or add a stage with + stage).
  2. Set the stage's When it runs: Always for everyone, or Only when to challenge only as a step-up.
  3. To require MFA across the whole realm, turn on Require MFA under Realm settings → Login → Login security (the requireMfa realm setting). Days a new account may skip MFA setup sets a grace period for new accounts.
  4. To force enrolment for one user, open the user and, in the Required actions section of the Details tab, tick the matching action (for example Configure OTP (authenticator)) and click Save required actions.

Always offer a recovery path

Pair any "have" factor with recovery codes or a second enrolled device so a lost phone or token doesn't lock users out. See OTP factors for recovery codes.

Over the API

MFA is composed from two API surfaces: the authenticator registry (which factors exist) and flows (where you place them). Whether MFA is mandatory realm-wide is the requireMfa field of the realm-settings resource. The examples assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

List the available factors

Each authenticator reports a factorClass and a level of assurance (levelOfAssurance) — a higher LoA is a stronger factor, which lets a risk-based flow demand step-up to a minimum strength.

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/authenticators"
[
  { "id": "otp",           "displayName": "One-Time Password (TOTP)", "factorClass": "POSSESSION", "levelOfAssurance": 2 },
  { "id": "sms-otp",       "displayName": "One-Time Code (SMS)",       "factorClass": "POSSESSION", "levelOfAssurance": 2 },
  { "id": "email-otp",     "displayName": "One-Time Code (Email)",     "factorClass": "POSSESSION", "levelOfAssurance": 2 },
  { "id": "hotp",          "displayName": "One-Time Password (HOTP)",  "factorClass": "POSSESSION", "levelOfAssurance": 2 },
  { "id": "recovery-code", "displayName": "Recovery Code",             "factorClass": "POSSESSION", "levelOfAssurance": 1 },
  { "id": "webauthn",      "displayName": "Passkey (WebAuthn)",        "factorClass": "POSSESSION", "levelOfAssurance": 3 },
  { "id": "push",          "displayName": "Push Approval",             "factorClass": "POSSESSION", "levelOfAssurance": 6 }
]

Require MFA realm-wide

requireMfa is one field of the realm-settings resource. PUT /settings takes the full object — read it first, then submit the whole document (see password policy for the full pattern).

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/settings" | grep -o '"requireMfa":[^,]*'
"requireMfa":false

Wire a factor into a flow

Adding a second-factor step is a flow edit — place the authenticator's id (for example otp or webauthn) in the execution tree with the requirement you want (REQUIRED or CONDITIONAL). See Authentication flows → Over the API.

Full endpoint set

Method & path (under /admin/realms/{realm}) Purpose
GET /authenticators List available factors and their level of assurance
GET /flows/{alias} · PUT /flows/{alias} Read / save the execution tree that places a factor
GET /settings · PUT /settings Read / update requireMfa and other realm policy

See also