OTPme

OTPme is a distributed, multi-site authentication and authorization system that combines identity management, PKI, single sign-on, RADIUS, LDAP, PAM and file shares under a single directory tree.

Its central design principle: every user carries many independent tokens instead of one shared password. A user might unlock their workstation with a FIDO2 hardware key, mount OTPme file shares with the same key, connect to WLAN with a per-device password over RADIUS, and use a dedicated application-scoped token for CalDAV/CardDAV/IMAP from a smartphone — all managed under one identity. Lose a laptop, delete that laptop's token; no other device is affected and no password anywhere needs rotating.

What OTPme offers

• Token types — passwords (Argon2/PBKDF2/HKDF), HOTP/TOTP, FIDO2/U2F, WebAuthn passkeys, YubiKey HMAC challenge-response, YubiKey in PIV mode, mOTP, SSH keys, short-lived SSO temp-passwords, script-driven tokens for custom auth backends, and link tokens that delegate to another user's token.
• Access control by client + access group — every service (RADIUS NAS, LDAP consumer, SSO relying party, …) is an OTPme client bound to an access group; only tokens or roles in that group can authenticate. Access groups carry per-service session lifetime and parallel-session caps, and can be nested into child access groups. The SSO access group is an exception — its rights do not cascade to children, so each service listed in the SSO portal can be permissioned individually.
• Object-level ACLs — orthogonal to access groups: fine-grained view/modify/delete/enable/disable permissions on individual objects, inheritable down the unit tree, assignable to a user/token or a role.
• Realms, sites, units — a distributed topology with intra-site cluster replication (clusterd) and cross-site synchronisation (syncd/hostd), optional cross-site trust cascades for federated login.
• Built-in PKI — realm CA, per-site CAs, and node/host certs for daemon-to-daemon TLS; no external CA required.
• Web SSO portal with OIDC provider — front-end can be deployed into a DMZ (ssohost install) with no backend secrets on the box.
• RADIUS via FreeRADIUS (rlm_python module or otpme-auth as ntlm_auth drop-in) — WLAN, VPN, anything RADIUS-capable, including MSCHAP / MS-CHAPv2 (PEAP, EAP-MSCHAPv2) for Windows-flavoured supplicants.
• LDAP frontend (ldapd) — external services bind through a familiar LDAP interface; the dc=<client> component selects which access group the bind is scoped to.
• PAM module for system login, with nsscache integration for POSIX user/group lookups.
• Offline authentication — during an online login, hosts cache the token and session data encrypted with an Argon2i-derived key from the user's password / PIN / smartcard response. When the server is unreachable, hosts authenticate against the local cache with OTP replay protection; used OTPs and counters resync back to the server on reconnect. Expiry is bounded by both login-age and inactivity.
• File shares — FUSE-mounted OTPme shares served by fsd, with optional transparent per-share encryption (share key wrapped per user). Shares can be pinned to a node pool to control placement and locality.
• Encrypted backups to a dedicated backup host, with e-mail reporting.
• Roles, groups, resolvers — role-in-role composition, groups usable as sync groups, and resolvers that import users from external sources.
• Policies — a pluggable rule engine: password (quality / dictionary strength), authonaction (step-up reauth on sensitive actions), logintimes (cron-style login windows), autodisable (time-boxed accounts / tokens), forcetoken (restrict which token types and methods a service accepts), idrange (sequential or random UID/GID allocation), and objecttemplates / default{groups,roles,units,policies} for zero-touch defaults on freshly created objects.
• Server-side scripts (scriptd) — hooks executed during specific events: auth scripts run inside the authentication flow, share scripts fire when a share is created or mounted (e.g. to set up directories or permissions), and backup scripts run as pre/post hooks around backup jobs.
• Client-side agent (otpme-agent) — holds session state and, when configured, keeps an unlocked YubiKey PIV handler so subsequent sign / verify / encrypt / decrypt operations (e.g. mounting an encrypted share) don't prompt for the PIV PIN again.
• Trash & restore — soft-deletion with inspectable dumps before restore.
• Audit log — dedicated audit trail of who changed which object, independent of daemon logs.
• Per-object config inheritance — most parameters cascade site → unit → node/host → user → token, with most-specific match wins.

Full architecture, daemon layout and config-parameter reference are in the otpme.7 manpage. A hands-on walkthrough is in the Getting Started guide.

---

Installation instructions

Warning: OTPme is alpha software. Do not use it in production. Expect breaking changes, incomplete features and bugs.

Full documentation is available at https://otpme.readthedocs.io.

Manpages can be installed with:

otpme-install-manpages

Install debian dependencies

apt-get install python3.11-venv gobjc++ python3-pybind11 python3-dev build-essential cmake gcc dbus-x11 freeradius freeradius-python3 haproxy libacl1-dev libnss-cache liboath0 liboath-dev libpcsclite1 libpq-dev libre2-9 libre2-dev libsystemd-dev pkg-config postgresql postgresql-server-dev-all pwgen pyflakes3 redis redis-server redis-tools libpcsclite-dev ykcs11 fuse3 libpam-python

Disable installed services

systemctl stop redis
systemctl disable redis
systemctl stop postgresql
systemctl disable postgresql
systemctl stop freeradius
systemctl disable freeradius
systemctl stop haproxy
systemctl disable haproxy

Install otpme

Add otpme system user

useradd -r -U -d /var/lib/otpme otpme

Enable nsswitch nsscache module

Edit /etc/nsswitch.conf and append 'cache' to the lines passwd, shadow and group.

Create python venv

python3 -m venv /opt/otpme
. /opt/otpme/bin/activate

Install otpme and dependencies

pip3 install cython

Pick the install variant matching what this machine should do:

Command	Role
pip3 install otpme	host — client + otpme-agent + PAM + nsscache + offline login. Default.
pip3 install 'otpme[backuphost]'	backup host — backup server for nodes, shares and hosts.
pip3 install 'otpme[ssohost]'	SSO portal host — front-end for the SSO/OIDC web portal. Holds no backend secrets, so it can be deployed into the DMZ.
pip3 install 'otpme[node]'	node — full server install, all features.
pip3 install 'otpme[node,dev]'	full server + dev tools (pytest, coverage, ruff).

The backuphost and ssohost roles are activated by setting BACKUP_SERVER resp. SSO_SERVER to True in /etc/otpme/otpme.conf.

Copy configuration files

cp -a /opt/otpme/lib/python3.11/site-packages/etc/otpme /etc/
cp -a /etc/otpme/otpme.conf.dist /etc/otpme/otpme.conf

Edit /etc/otpme/otpme.conf

POSTGRES_PG_CTL_BIN="/usr/lib/postgresql/15/bin/pg_ctl"

Create PYTHONPATH file with path to venv (e.g. /opt/otpme/lib/python3.11/site-packages/)

/etc/otpme/PYTHONPATH

Init your otpme realm

otpme-realm --api -ddee --color-logs -f init --ca-key-len 2048 --site-key-len 2048 --node-key-len 2048 --dicts english,en-top10000,common-passwords,us-female,us-male,us-surnames,abbreviations-it --id-ranges "uidNumber:s:100000-200000,gidNumber:s:100000-200000" yourrealm.tld yoursite localhost 127.0.0.1

Note: Scan the generated QRCode with the "Google Autenticator App" and note the PIN of the admin token.

Start OTPme daemons

otpme-controld start

Login with admin token

You need to input pin+otp.
otpme-tool login

Add optional U2F/fido2 attestation certificates from https://developers.yubico.com/FIDO/yubico-fido-ca-certs.txt.

wget https://developers.yubico.com/FIDO/yubico-fido-ca-1.pem
wget https://developers.yubico.com/FIDO/yubico-fido-ca-2.pem
otpme-site add_fido2_ca_cert yoursite yubico-fido-ca-1.pem
otpme-site add_fido2_ca_cert yoursite yubico-fido-ca-2.pem
otpme-site config yoursite check_fido2_attestation_cert True

Disable gpg-agent (systemd) to use yubikey/GPG card with the PAM module.

systemctl --global mask --now gpg-agent.service gpg-agent.socket gpg-agent-ssh.socket gpg-agent-extra.socket gpg-agent-browser.socket