Multi-Factor Authentication (MFA)

Multi-factor authentication requires users to provide a second form of verification in addition to their primary credentials. Auris supports four MFA mechanisms — TOTP authenticator apps, SMS one-time passwords, WebAuthn hardware keys and passkeys, and adaptive risk-based MFA that triggers additional factors automatically based on detected risk — that can be combined according to your security policy.

TOTP (Authenticator App)

Time-Based One-Time Password (TOTP) is the most widely supported MFA mechanism. Users scan a QR code with an authenticator app — such as Google Authenticator, Authy, 1Password, or any RFC 6238-compliant application — and enter the six-digit code it generates.

How it works

TOTP codes are derived from a shared secret and the current time. The server and the authenticator app independently compute the same code for each 30-second window. No network connection is required on the user’s device.

User setup

The TOTP enrollment flow:

1. The user navigates to Account → Security → Two-Factor Authentication.
2. A QR code and manual entry key are displayed.
3. The user scans the QR code with their authenticator app.
4. The user enters the initial six-digit code to confirm setup.
5. Recovery codes are generated and displayed. The user must save these — they cannot be retrieved later.

Recovery codes

Each TOTP setup generates 10 single-use recovery codes. If a user loses access to their authenticator device, they can enter a recovery code to bypass MFA and log in. After use, a recovery code is invalidated. Users can generate a new set of recovery codes from their account security page — doing so invalidates all previous codes.

Admin actions

Admins can reset a user’s TOTP enrollment via the Console (User detail → Security → Reset TOTP). This removes the existing TOTP configuration and forces the user to re-enroll on next login. Use this when a user reports a lost or replaced device.

SMS OTP

SMS one-time passwords deliver a verification code to the user’s registered mobile phone number via SMS. Auris uses Twilio as the SMS provider.

Requirements

SMS OTP requires:

• A Twilio account with a phone number capable of sending SMS.
• TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_FROM_NUMBER environment variables configured in the Auris API.

For a complete SMS OTP setup guide including Twilio configuration, see SMS OTP Authentication.

User setup

1. The user navigates to Account → Security → Phone Number.
2. The user enters their mobile number in E.164 format (e.g., +39 02 1234 5678).
3. Auris sends a verification code via SMS.
4. The user enters the code to confirm phone ownership.
5. The phone number is verified and can be used for SMS OTP MFA.

Rate limits

To prevent abuse, Auris enforces rate limits on SMS OTP codes:

• Maximum 5 codes sent per phone number per hour.
• A 30-second cooldown between send requests.
• Maximum 5 verification attempts per code before it is invalidated.

WebAuthn / Passkeys

WebAuthn (Web Authentication, FIDO2) allows users to authenticate using hardware security keys (YubiKey, Titan Key) or platform authenticators (Touch ID, Face ID, Windows Hello). When used as a second factor, the user taps their hardware key or uses biometrics to complete the MFA challenge.

WebAuthn credentials are phishing-resistant by design: the credential is bound to the specific origin (domain) and cannot be replayed on a different site.

For a complete WebAuthn setup guide, see WebAuthn / Passkeys.

User setup

1. The user navigates to Account → Security → Passkeys.
2. The user clicks “Register Passkey” and provides a name for the credential.
3. The browser presents a platform authenticator prompt (Touch ID, Windows Hello, or a hardware key).
4. The credential is registered. The user can register multiple passkeys for different devices.

During MFA challenge

When WebAuthn MFA is required, the Hosted Login page presents a WebAuthn challenge. The user’s registered authenticator handles the cryptographic response — no code entry is needed.

Adaptive MFA (Risk-Based)

Adaptive MFA evaluates a risk score on every login and automatically escalates the authentication requirement when risk is elevated. Rather than always requiring MFA or never requiring it, Auris responds proportionally to the actual risk of each login attempt.

Risk factors

Auris computes a risk score from five weighted factors:

Factors are combined into a final risk score from 0 to 100.

Risk thresholds

Configure thresholds in Console → Security → Adaptive MFA:

These thresholds are configurable. You can also disable adaptive MFA entirely and use a fixed policy.

ACR and AMR in tokens

When step-up authentication occurs, Auris includes standard claims in the access token:

• ACR (Authentication Context Class Reference): The level of assurance achieved. For example, urn:mace:incommon:iap:silver for MFA-verified sessions.
• AMR (Authentication Methods References): The authentication methods used. For example, ["pwd", "totp"] for password + TOTP, or ["pwd", "hwk"] for password + hardware key.

Your application server can inspect these claims to enforce session-level access control.

Step-Up Authentication

Step-up authentication allows your application to require additional verification for specific operations within an existing session, without forcing a full re-login.

For example, a user is logged in and navigates to “Delete Account”. Your application can trigger a step-up challenge requiring the user to re-authenticate (enter their password) or complete an MFA factor before the destructive action proceeds.

Auris implements step-up via ACR in the authorization request. When your application requests an authorization code with acr_values=2fa, Auris checks the current session’s ACR level and only prompts for additional authentication if the session does not already meet the requirement.

Console Configuration

MFA settings are available in Console → Authentication → MFA Settings.

Per-method toggles:

Enforcement policies:

Risk thresholds: Configurable sliders for the Low/Medium/High boundaries and per-factor weights.

Required Permissions

All MFA management endpoints operate on the authenticated user’s own account and require no special permission beyond authentication. Admin-level operations (resetting another user’s TOTP, viewing MFA status) require manage:users.

Related Pages

• SMS OTP Authentication — Full Twilio setup and SMS OTP implementation guide
• WebAuthn / Passkeys — Passkey registration, challenge, and management
• Attack Protection — Rate limiting, brute-force lockout, suspicious login detection
• Console: Security Settings — Full Console walkthrough for MFA and security configuration