Airlock supports WebAuthn as a second authentication factor. WebAuthn is used when logging in to Airlock (airsh login or the web interface), as well as when connecting to SSH nodes and Kubernetes (airsh ssh, kubectl).

Hardware keys (YubiKey, SoloKey) and biometric authenticators (Touch ID, Windows Hello) are supported.

Prerequisites

  • A WebAuthn hardware key or a built-in biometric authenticator.
  • A browser with WebAuthn support.
  • The airctl utility for cluster configuration.

Step 1. Enable WebAuthn

Dynamic configuration

Edit the cluster_auth_preference resource:

airctl edit cap

Example configuration:

kind: cluster_auth_preference
version: v2
metadata:
  name: cluster-auth-preference
spec:
  type: local
  second_factor: "on"
  webauthn:
    rp_id: airlock.example.com
    attestation_allowed_cas:
    - "/path/to/allowed_ca.pem"
    attestation_denied_cas:
    - "/path/to/denied_ca.pem"

Static configuration

Fragment of /etc/airlock.yaml:

auth_service:
  authentication:
    type: local
    second_factor: on
    webauthn:
      rp_id: airlock.example.com
      attestation_allowed_cas:
      - "/path/to/allowed_ca.pem"
      attestation_denied_cas:
      - "/path/to/denied_ca.pem"

Restart the Auth Service after making changes.

webauthn fields

FieldDescription
rp_idPublic domain of the Proxy Service (without https:// and port)
attestation_allowed_casAllow-list CAs for verifying devices during registration
attestation_denied_casDeny-list CAs — devices with these CAs are rejected

All devices are allowed by default. Use attestation_denied_cas to restrict specific device models.

Starting from Airlock v10, WebAuthn replaces U2F. Existing U2F devices are supported automatically.

Step 2. Register a device

A user registers a WebAuthn device:

airsh mfa add
# Choose device type [TOTP, WEBAUTHN]: webauthn
# Enter device name: desktop yubikey
# Tap any *registered* security key or enter a code from a *registered* OTP device:
# Tap your *new* security key
# MFA device "desktop yubikey" added.

If only OTP confirmation is needed during registration (without WebAuthn):

airsh mfa add --mfa-mode=otp

Step 3. Log in via WebAuthn

After registering a device, confirmation is requested on login:

airsh login --proxy=airlock.example.com
# Enter password for Airlock user alice:
# Tap any security key or enter a code from a OTP device:
# > Profile URL:        https://airlock.example.com
#   Logged in as:       alice
#   Cluster:            airlock.example.com
#   Roles:              access, editor
#   Logins:             alice
#   Kubernetes:         enabled
#   Valid until:        2026-07-05 14:00:00 +0300 MSK [valid for 12h0m0s]

WebAuthn on Airlock login is required only for local users. For SSO, configure MFA on the IdP side.

Migrating from U2F

If U2F was previously used, Airlock automatically derives the WebAuthn configuration from U2F. Preserve the u2f.app_id field to avoid re-registering devices:

auth_service:
  authentication:
    type: local
    second_factor: on
    u2f:
      app_id: https://airlock.example.com
    webauthn:
      rp_id: airlock.example.com
      attestation_allowed_cas:
      - "/path/to/u2f_attestation_ca.pem"

Next steps

←
Authentication / Two-factor authentication (OTP/TOTP)
Access policies (RBAC) / Access to SSH hosts
→