Ligament 2FA Installation and Administration Guide

The Ligament platform functions completely autonomously inside your private infrastructure (100% On-Premise). Master encryption keys, user directories, active sessions, and security audit logs are stored securely in a relational PostgreSQL database. The engine makes zero external requests and is fully ready for air-gapped networks.

Network Ports Matrix

The platform engine is distributed as an optimized official Docker Hub image aligorov/ligament_2fa. No build tools or compilers are required.

Option A: Quickstart via Official Script (Recommended)

The script checks Docker prerequisites, tests port availability (80/8080 TCP, 1812/1813 UDP), generates a secure PostgreSQL password in .env (chmod 0600), deploys containers, and extracts master recovery credentials.

mkdir -p /opt/ligament && cd /opt/ligament
curl -fsSL https://raw.githubusercontent.com/aligorov/ligament/main/install.sh -o install.sh
chmod +x install.sh && ./install.sh

Option B: Manual Docker Compose Deployment

Create directory /opt/ligament and save docker-compose.yml:

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: twofa
      POSTGRES_PASSWORD: "${TWOFA_PG_PASSWORD:?Specify TWOFA_PG_PASSWORD in .env}"
      POSTGRES_DB: twofa
    volumes:
      - twofa_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U twofa -d twofa"]
      interval: 5s
      timeout: 3s
      retries: 20
    restart: unless-stopped

  twofa:
    image: aligorov/ligament_2fa:latest
    hostname: ligament-auth
    depends_on:
      db:
        condition: service_healthy
    environment:
      TWOFA_DB_DSN: "postgres://twofa:${TWOFA_PG_PASSWORD}@db:5432/twofa"
      TRUSTED_PROXIES: "127.0.0.0/8,::1/128,172.16.0.0/12,10.0.0.0/8,192.168.0.0/16"
    ports:
      - "80:8080"
      - "8080:8080"
      - "1812:1812/udp"
      - "1813:1813/udp"
    volumes:
      - /etc/machine-id:/etc/host-machine-id:ro
    restart: unless-stopped

volumes:
  twofa_pgdata:

Generate the .env file and launch the stack:

echo "TWOFA_PG_PASSWORD=$(openssl rand -hex 24)" > .env
chmod 600 .env
docker compose up -d

The admin password is never written to container console logs. On first launch, the system provisions an admin account, stores the initial password in admin_password.txt, and generates 5 single-use emergency recovery codes in admin_recovery_codes.txt.

# Extract generated admin password:
docker cp $(docker compose ps -q twofa):/home/nonroot/admin_password.txt .

# Extract 5 emergency break-glass recovery codes:
docker cp $(docker compose ps -q twofa):/home/nonroot/admin_recovery_codes.txt .

# Display password:
cat admin_password.txt

By default, the free Community edition is active for up to 5 users indefinitely.

To upgrade to a commercial tier or activate a 30-day pilot:

• Navigate to /admin → License in the web console.
• Paste the license key string and click "Save License".
• Keys are cryptographically signed with Ed25519 — validated locally and applied instantly without server restarts or internet connectivity.

Under /admin → Settings → Domain & Templates, configure your public URL in the server.domain parameter (e.g. https://auth.company.corp).

User provisioning and domain password verification operate over secure LDAPS. In /admin → Settings → Directory Services (LDAP), configure:

In /admin → Settings, enable your preferred verification channels:

• Telegram Bot: Create a bot via @BotFather and specify the token in telegram.bot_token. Employees confirm sign-ins via in-chat prompts or Number Matching.
• Corporate Email (SMTP): One-time passcode (OTP) delivery routed through your corporate mail server.
• FIDO2 / Passkeys / WebAuthn: Hardware security tokens (YubiKey, Rutoken MFA) and platform biometrics (Windows Hello, Touch ID).

Ligament Core provides a built-in RADIUS server (UDP 1812 / 1813). To connect MikroTik RouterOS gateways, execute in the RouterOS terminal:

/radius add address=192.168.1.10 secret="YourSecretKey" service=login,ppp,wireless timeout=5s
/user aaa set use-radius=yes
/ppp aaa set use-radius=yes accounting=yes
/radius incoming set accept=yes

The native Credential Provider integrates into Windows workstations and servers to secure console and RDP logons with instant Auto-Logon.

Workstation Logon Interface

🪟 Native Windows LogonUI Integration Integrates directly into the Windows lock screen: users type their credentials and confirm access via push notification (Number Matching), Telegram, or Passkey.

🔑 Passkey QR Sign-in (Dynamic QR) Employees scan a dynamic on-screen QR code using their phone camera and approve via Face ID / Touch ID biometrics. Zero manual code typing.

Active Directory Group Policy (GPO) Setup:

1. Copy Ligament2FA.admx into \\domain\SYSVOL\domain\Policies\PolicyDefinitions\.
2. Copy Ligament2FA.adml into PolicyDefinitions\en-US\.
3. In gpmc.msc, enable Server URL (https://auth.company.corp:8080), Auto-Logon (Enabled), and Number Matching (Enabled).

For employees running Windows or Linux distributions, the graphical Ligament Authenticator app provides seamless pairing, notifications, and telemetry.

💻 Workstation Pairing in Ligament Authenticator Pairs the workstation with the user identity, handles background system notifications, and tracks connection health.

The lightweight Relay node addresses two critical branch office requirements:

• Secure RDP & SSH Forwarding: Opens an outbound WSS (:443) tunnel to Core, granting secure remote admin access to internal hosts without a public IP or exposed ports.
• Cached Backup RADIUS for Wi-Fi: During WAN outages, operates as an autonomous local RADIUS server (802.1X WPA2/WPA3 Enterprise) using cached credentials.

• Healthcheck: curl -I http://localhost:8080/healthz (returns HTTP 200 OK).
• Live Audit Log: Streamed in real-time under /admin/audit.
• Database Backup:

docker compose exec -T db pg_dump -U twofa twofa | gzip > "ligament_backup_$(date +%F_%H%M).sql.gz"