Two-factor sign-in
Two-factor sign-in asks for a 6-digit code from an authenticator app after your password, so a stolen password is not enough. You turn it on from your Profile page (click your avatar). Admins set which roles must use it in Settings > Security.
Any authenticator app works, for example 1Password, Bitwarden, Google Authenticator or Aegis. Passkeys and SMS codes are not supported.
Turn it on
- Open your Profile page. Find Two-factor authentication and choose Set up authenticator.
- Scan the QR code with your authenticator app. If you cannot scan it, type the key shown under it.
- Enter the 6-digit code from the app and choose Verify and enable.
- Save your 10 recovery codes with Download or Copy, then choose I saved my codes.
Recovery codes are shown only once. Each one works once, in place of an app code, if you lose your phone.
Admins and DevOps users must set this up. If they have not, they are sent to a setup screen right after signing in, and can do nothing else until they finish.
When you are asked for a code again
Some sensitive actions ask for a fresh code even when you are signed in. The code is valid for 15 minutes, then you are asked again. These actions are:
- revealing or exporting secrets, and turning a secret into a plain variable
- rotating Cairn's own passwords
- creating agent tokens for AI tools
- connecting or removing a GitHub or GitLab integration
- resetting another user's two-factor sign-in
- changing which roles must use two-factor sign-in
If you have not set up two-factor sign-in, the dialog sends you to your Profile page first.
Lost your phone
Use a recovery code. Sign in with a recovery code instead of the app code. Then, on your Profile page, enter a code and choose New recovery codes, or turn two-factor off and set it up again.
Ask an admin. An admin opens Users and chooses Reset MFA on your account. You set it up again at your next sign-in if your role requires it.
No admin can sign in. On the server, as root:
sudo platformctl mfa disable --user [email protected]Then sign in with your password and set up two-factor sign-in again. This works even when the portal is down.
Choose which roles must use it
- Open Settings in the sidebar and choose the Security tab.
- Tick the roles that must use two-factor sign-in. The default is admin and DevOps.
- Save. You are asked for a fresh code.
Only admins can change this. DevOps users can see it.
You can turn two-factor sign-in off on your Profile page with Turn off, unless your role requires it.
How it works
- Codes are standard time-based one-time passwords (TOTP, RFC 6238) with 30-second steps.
- Codes from the step before and after are accepted, to allow for clock drift.
- Each code is accepted only once. Reusing a code, or a code from an earlier step, fails.
- Failed code attempts are limited per account: 10 per 15 minutes by default. The counters are shared by every API replica.
- After the password, users with two-factor turned on get a challenge that expires after 5 minutes. GitHub and GitLab sign-in go through the same challenge.
- A session limited to setup lasts 1 hour and can only reach the setup endpoints.
- Agent tokens for AI tools (
plat_agent_*) do not use two-factor sign-in. Their scopes, and human approval of destructive commands, control them instead. - Authenticator secrets are stored encrypted with AES-256-GCM using
SECRETS_ENCRYPTION_KEY(orJWT_SECRETwhen that is not set). Recovery codes are stored as bcrypt hashes. - The built-in sign-in provider copies
amrandauth_timeinto the tokens it gives Grafana, Argo CD and other tools, so they can require two-factor sign-in. platformctl mfa disablerunspsqlin the PostgreSQL pod (namespacedatabases). It deletes the user's factor and recovery codes and writes anauth.mfa.break_glass_disableaudit entry.--databasepicks the database name; the default isPOSTGRES_DBfrom theplatform-envsecret, elseplatform.
Settings
| Setting | Default | What it does |
|---|---|---|
mfa.requiredRoles (Settings > Security) |
[admin, devops] |
Roles that must use two-factor sign-in |
MFA_REQUIRED_ROLES |
unset | Used when the setting was never saved. Comma list, or none. |
MFA_STEP_UP_MAX_AGE_SEC |
900 |
How long a fresh code counts for sensitive actions |
MFA_RATE_LIMIT_MAX |
10 |
Failed code attempts per account per 15 minutes |
MFA_ISSUER |
Platform (<DOMAIN>) |
Name shown in authenticator apps |
Session claims
| Claim | Meaning |
|---|---|
amr |
pwd (password) or fed (GitHub/GitLab), plus otp and mfa after a second factor |
auth_time |
When the user last authenticated (seconds). Refreshed by a fresh code. |
mfa_enroll |
Present on sessions limited to setup |
Audit log
Every event is recorded: auth.mfa.enroll_started, auth.mfa.enroll_failed, auth.mfa.enabled, auth.mfa.enrollment_forced, auth.mfa.challenge_succeeded, auth.mfa.challenge_failed, auth.mfa.recovery_code_used, auth.mfa.step_up, auth.mfa.step_up_failed, auth.mfa.recovery_codes_regenerated, auth.mfa.recovery_codes_failed, auth.mfa.disabled, auth.mfa.disable_failed, auth.mfa.admin_reset, auth.mfa.break_glass_disable and settings.mfa.updated.
For developers / API
When an action needs a fresh code, the API answers:
HTTP 401
{ "error": "step_up_required", "maxAgeSec": 900 }
The portal then asks for a code, calls POST /api/auth/mfa/step-up and retries. The new session has auth_time set to now and mfa in amr.
Sign-in for a user with two-factor turned on: POST /api/auth/login answers mfa_required with a challenge token. Finish with POST /api/auth/mfa/challenge. The GitHub/GitLab one-time code exchange answers the same way.
| Method | Path | Notes |
|---|---|---|
GET |
/api/auth/mfa/status |
On or off, setup pending, recovery codes left, whether your role requires it |
POST |
/api/auth/mfa/enroll |
Returns otpauthUri, qrDataUrl (PNG data URL) and secret. Pending until verified. |
POST |
/api/auth/mfa/verify |
{ code } → { recoveryCodes, token } (full session) |
POST |
/api/auth/mfa/challenge |
{ challengeToken, code } → { token, user }. code may be a recovery code. |
POST |
/api/auth/mfa/step-up |
{ code } → { token } |
POST |
/api/auth/mfa/recovery-codes |
{ code } → new recoveryCodes. Old ones stop working. |
POST |
/api/auth/mfa/disable |
{ code }. Refused (mfa_required_by_policy) when your role requires it. |
POST |
/api/users/:id/mfa/reset |
Admin, fresh code. Removes the user's factor. |
GET |
/api/settings/mfa |
Policy (DevOps or admin) |
PUT |
/api/settings/mfa |
{ requiredRoles } (admin, fresh code) |
Endpoints that need a fresh code:
POST /api/projects/:projectId/secrets/revealGET /api/projects/:projectId/secrets/export/:environmentId- converting a secret variable to plain in the environment-variables API
POST /api/settings/rotate-secretsPOST /api/agent-tokensPOST /api/settings/integrations/github/manifest,.../github/manifest/complete,POST /api/settings/integrations/gitlab/connect,DELETE /api/settings/integrations/:provider/appPOST /api/users/:id/mfa/resetPUT /api/settings/mfa
The OpenAPI document (GET /api/openapi.json) describes request and response bodies.