> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# MFA deployment requirements (BYOC)

> Configure MFA session protection, challenge limits, and email delivery in a BYOC deployment.

This page tells a BYOC operator what to configure before users enable [multi-factor authentication](/en/platform/access-manager/features/mfa/overview).

<Note>
  This page applies to BYOC deployments only. On Lerian Cloud, Lerian operates this configuration for you.
</Note>

## 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.

<Warning>
  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.
</Warning>

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:

| Variable                  | Default | Purpose                                                                                    |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `MFA_SESSION_TTL_SEC`     | `300`   | Lifetime of the short MFA sign-in session, in seconds.                                     |
| `MFA_MAX_ATTEMPTS`        | `5`     | Maximum verification attempts allowed per user within the counter window.                  |
| `MFA_MAX_RESEND_ATTEMPTS` | `3`     | Maximum email challenge sends allowed per user and email method within the counter window. |

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](/en/reference/platform/access-manager/am-identity-apis).

## Validate the deployment

***

<Steps>
  <Step title="Enable an authenticator app for a test user">
    Complete setup and store the issued recovery codes.
  </Step>

  <Step title="Sign out and sign in again">
    Make sure Auth returns the MFA step after the first factor.
  </Step>

  <Step title="Verify a valid passcode">
    Enter the current authenticator passcode. Expect the normal user session.
  </Step>

  <Step title="Verify expiration">
    Start sign-in again and wait longer than `MFA_SESSION_TTL_SEC`. Expect the MFA session to expire.
  </Step>

  <Step title="Test configured delivery methods">
    Enable email for the test user. Request a challenge and make sure the message arrives at the saved address.
  </Step>

  <Step title="Test a recovery code">
    Sign in with one recovery code, then make sure the same code cannot be used again.
  </Step>
</Steps>

Do not run limit tests against a production user. Repeated invalid attempts can temporarily block MFA verification for that user.

## Related pages

***

<Columns cols={2}>
  <Card title="Complete MFA in the Console" icon="desktop" href="/en/platform/access-manager/features/mfa/console">
    Test passcode and recovery-code verification during sign-in.
  </Card>

  <Card title="Manage MFA via API" icon="code" href="/en/platform/access-manager/features/mfa/api">
    Integrate account enrollment and login verification.
  </Card>
</Columns>