Custom MFA factors

The platform ships with WebAuthn, TOTP, SMS, and backup codes. Custom factors let your tenant define additional factors users can enrol — typically for in-house tokens, SaaS MFA integrations, or any specialised flow.

This is an advanced surface; most tenants don't need it. Reach for it when:

Your organisation has issued hardware tokens (e.g., your own branded YubiKey-equivalent) and you want users to see "Set up Cymmetri Token" instead of generic "WebAuthn".
You're integrating with a third-party MFA SaaS (Duo, Authy as a service, RSA SecurID) and want it surfaced as a factor option in the IntelliAuth sign-in UI.
Your industry has a specific compliance requirement that names a factor type.

How a custom factor is defined

MFA → Custom factors → New custom factor.

Each custom factor is a configuration:

Name — what users see ("Cymmetri Token", "Duo Push").
Slug — URL-safe identifier. Immutable once saved.
Icon — an icon to display next to the factor in the enrolment + sign-in UI. SVG or PNG.
Description — short copy explaining the factor to users at enrolment ("Tap your Cymmetri-issued security key.").
AAL — what AAL this factor satisfies. AAL 2 typically; AAL 3 for phishing-resistant hardware.
Backing protocol — what the platform actually runs under the hood:
- WebAuthn — for hardware tokens, branded or otherwise.
- TOTP — for generic time-based codes.
- Custom webhook — calls out to your service for the actual factor logic.
- SAML attribute — uses a SAML assertion from a federated IdP as the factor proof.

Save. The factor is available in MFA → Allowed factors to enable, and users see it in enrolment / sign-in UI.

Backing protocol details

WebAuthn-backed custom factor

For "your branded hardware tokens" — the underlying protocol is standard WebAuthn; you're just renaming + re-iconing it for your users.

Configure:

Allowed authenticator attachment — cross-platform for hardware keys, platform for built-in (Touch ID, Windows Hello).
Allowed AAGUIDs (optional) — limit enrolment to specific token manufacturers / models. E.g., your tenant only accepts Cymmetri-issued tokens; the AAGUID filter rejects YubiKeys / Titans at enrolment.

TOTP-backed custom factor

Identical to the standard TOTP factor; just with custom branding. Useful if you want "Cymmetri Code" instead of generic "Authenticator app". The QR code at enrolment carries your tenant name + your icon (in apps that support icons).

Custom-webhook-backed factor

The most flexible — your service handles the factor's logic; IntelliAuth invokes it via webhook.

The contract:

On enrolment, the platform POSTs to your enroll URL with the user's identifier. Your service returns the factor's "claim" (an identifier the platform stores against the user) plus optional setup data (a URL the user should visit on their phone, etc.).
On verification (sign-in), the platform POSTs to your verify URL with the claim + user-submitted input. Your service returns success / failure.

The platform handles the UI prompts, rate limiting, retry, audit — your service is just the verification engine. Useful when integrating with an existing MFA SaaS that exposes its own verify API.

SAML-attribute-backed factor

For corner-case integrations where a SAML assertion from a federated IdP carries an attribute that confirms MFA was completed at the IdP. IntelliAuth checks the attribute presence + value; if it matches, the factor is satisfied.

Useful in B2B SSO scenarios where the customer's IdP does the MFA and IntelliAuth wants to trust it. The IdP's metadata + assertion shape determine what attribute / value to check.

User-facing presentation

Custom factors appear in the user's MFA enrolment + sign-in alongside the standard ones. The UI surfaces your name + icon. From the user's perspective, "Cymmetri Token" is just another factor option; they don't know (and don't need to know) it's WebAuthn under the hood.

Audit

Every custom-factor event records the factor's slug + the underlying protocol's audit. So a sign-in via "Cymmetri Token" produces both an auth.mfa.succeeded event for the factor slug AND a webauthn.authentication_completed event for the protocol. The pair lets you correlate without ambiguity.

When NOT to define a custom factor

Just to rename WebAuthn. You can change the label in Branding → User-facing copy without defining a custom factor. Cheaper, fewer moving parts.
For a unique-per-user factor. Custom factors are tenant-wide; they don't take per-user parameters. If you need per-user verification logic, it's not a factor — it's a flow / action.

What to set AAL to

Per NIST 800-63B:

WebAuthn-backed — AAL 2 (any) or AAL 3 (phishing-resistant + hardware-backed + biometric-bound).
TOTP-backed — AAL 2.
Custom-webhook — depends on what your service actually does. If it's a strong protocol (PKCS#11 hardware token), AAL 2 or 3. If it's a weak protocol (email-based callback), AAL 1.
SAML-attribute — AAL 2 typically; depends on what the upstream IdP claims.

Setting AAL accurately is what lets adaptive step-up actually work — if you mark a custom factor as AAL 3 but it's effectively AAL 1 under the hood, you're undermining the platform's ability to reason about the user's authentication strength.