Two-factor authentication (OTP/TOTP)

Airlock supports multi-factor authentication (MFA) for local users. The otp type implements the TOTP standard — time-based one-time codes.

You can use any TOTP client to generate codes: Authy, FreeOTP, KeePassXC, or similar apps.

Available second_factor modes

Enabling TOTP

Dynamic configuration

Retrieve the current cluster_auth_preference resource:

airctl get cap > cap.yaml

Set second_factor:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factor: "otp"
version: v2

Apply:

airctl create -f cap.yaml

For mandatory MFA use second_factor: "on". For gradual rollout use "optional".

Static configuration

Add to /etc/airlock.yaml:

auth_service:
  authentication:
    type: local
    second_factor: otp

Restart the Auth Service after making changes.

Registering a TOTP device

A user registers TOTP via airsh:

airsh mfa add
# Choose device type [TOTP, WEBAUTHN]: totp
# Enter device name: phone
# Scan QR code with your TOTP app
# Enter an OTP token from the device: 123456
# MFA device "phone" added.

List registered devices:

airsh mfa ls

Remove a device:

airsh mfa rm phone

Logging in with TOTP

After registering a device, a one-time code is requested on login:

airsh login --proxy=airlock.example.com
# Enter password for Airlock user alice:
# Enter an OTP token from a registered device: 654321

Lockout after failed attempts

A local user is locked for 20 minutes if there are several failed login or password reset attempts within a 30-minute window.

To unlock, an administrator runs:

airctl get users/alice > user.yaml

Set status.is_locked to false and apply:

airctl create -f user.yaml

Next steps

• Configure WebAuthn for hardware keys
• Review local users and role management