Skip to main content
This page tells a BYOC operator what to configure before users enable multi-factor authentication.
This page applies to BYOC deployments only. On Lerian Cloud, Lerian operates this configuration for you.

​
Protect MFA sessions

Set MFA_SECRET in the Auth process environment. Auth uses this secret to sign short-lived MFA-session tokens. These tokens connect the verified first sign-in factor to the MFA challenge. Set MFA_ENABLED=true in the Auth process environment to make Auth check MFA_SECRET at startup. If the secret is empty, Auth starts and logs an error. The MFA routes and the passkey sign-in routes then return 503 with code AUT-0028 until you set the secret and restart Auth. This startup check does not enable or disable MFA for individual users. MFA_ENABLED=false does not bypass their MFA requirement.
Configure MFA_SECRET before users enable MFA. If the value is empty, Auth cannot create the MFA token required to continue an MFA-enabled sign-in.
Inject the value from a secret store. Do not commit it to a values file.

​
Configure session and attempt limits

The Auth deployment supports these variables: Short session times reduce the period in which a stolen MFA token is useful. A verification request counts only after input, token, session, organization, and IP checks pass. Enrollment confirmations count toward the same limit. The per-user verification counter expires after MFA_SESSION_TTL_SEC without another counted request. Each counted request refreshes that expiry. The resend counter is per user and method, with a window of MFA_SESSION_TTL_SEC from its first reservation. Failed sends release their reservation. A successful verification or enrollment confirmation clears both counters. Restarting sign-in does not reset them. Attempt and resend limits reduce repeated passcode guessing and message delivery abuse.

​
Configure email delivery

Email MFA needs:
  • an email communication provider in Identity.
  • a link between the provider and the application that sends MFA messages.
  • an email address on the user account.
Use the provider and application-provider operations described in Identity APIs.

​
Validate the deployment

1

Enable an authenticator app for a test user

Complete setup and store the issued recovery codes.
2

Sign out and sign in again

Make sure Auth returns the MFA step after the first factor.
3

Verify a valid passcode

Enter the current authenticator passcode. Expect the normal user session.
4

Verify expiration

Start sign-in again and wait longer than MFA_SESSION_TTL_SEC. Expect the MFA session to expire.
5

Test configured delivery methods

Enable email for the test user. Request a challenge and make sure the message arrives at the saved address.
6

Test a recovery code

Sign in with one recovery code, then make sure the same code cannot be used again.
Do not run limit tests against a production user. Repeated invalid attempts can temporarily block MFA verification for that user.

Complete MFA in the Console

Test passcode and recovery-code verification during sign-in.

Manage MFA via API

Integrate account enrollment and login verification.