Skip to content

Turn on two-factor sign-in for a self-hosted team

This walk-through is for the administrator of a self-hosted Preloop Enterprise installation who wants to require two-factor sign-in for a team and test it. Each step links to the page with the details.

Before you start

Take a database dump before you upgrade to a release with these controls. Changing the images back does not undo migrations; see the upgrade section of the Compose or Helm install guide. Ask a second administrator to complete step 1 before you turn on the policy, so one lost phone cannot lock the account.

1. Set up your own factor

Open Settings → Security → Authenticator app and select Set up authenticator app. Scan the QR code, enter the six-digit code, and save the ten recovery codes. Sign out and back in to check that the code step follows the password step. See Authenticator app and recovery codes.

2. Turn on the policy

Open Settings → Security → Account sign-in policy, set Require strong sign-in to Owners and admins or All members, and select Save policy. Your own session must already be strong. Enforcement is immediate: covered members' non-SSO sessions end, and a member without a factor is sent to Protect your sign-in at the next sign-in, where they can only enroll. See Require strong sign-in.

3. Check coverage

The table on the same card lists each member's factors (Passkey, Authenticator app, SSO) or Enrollment needed. Check it before you turn the policy on and again afterwards. Unconfirmed enrollment does not count. See Coverage and recovery.

4. Reset a member who lost their factor

Verify the person's identity independently, then select Reset sign-in in their row, enter a Reason for reset, and select Reset member sign-in. You need your own strong proof within the last ten minutes (or the account step-up window, if shorter), and you cannot reset yourself. The member signs in again and enrolls a new factor. See Coverage and recovery.

5. Choose a step-up window

Step-up window (minutes) is optional: 0 turns it off, or choose 5 to 720 minutes. Covered members then confirm a fresh code or passkey before console approvals, API-key changes, SSO and SCIM changes, policy changes and role changes. Mobile, watch, Slack and Mattermost approvals do not use console step-up. See Step-up window.

6. Roll back or recover the last administrator

To roll back, set Require strong sign-in to Off and save; this also sets the step-up window to 0. If the last administrator loses every factor, a server operator runs scripts/ee/reset_sign_in_policy.py and then the core reset script for the lost factor; no browser session is needed. See Last-administrator recovery and Operating authenticator authentication.

What it does not do

  • There is no grace period or scheduled deadline. Tell members before you turn the policy on.
  • Personal API keys, runner credentials and CI identities keep their own credential policies and are not affected.
  • Members who sign in with SSO satisfy the policy. Configure MFA in your identity provider; Preloop accepts its successful authentication.