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 auth.secrets.MFA_SECRET in the Access Manager Helm values. The chart exposes it to Auth as MFA_SECRET. 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 require a non-empty MFA_SECRET at startup. Auth refuses to start if the secret is empty. 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. Verification requests count only after input, token, session, organization, and IP checks pass. 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. Successful verification 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.