Termix supports multiple authentication methods that can be used independently or together. Admins control which methods are available site-wide, while each user manages their own 2FA and session settings from their profile.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Termix-SSH/Termix/llms.txt
Use this file to discover all available pages before exploring further.
Local password authentication
By default, users register with a username and password. Passwords are hashed with bcrypt using theSALT cost factor (default: 10) and stored in the encrypted SQLite database.
Admin controls
These settings are available in Admin Panel → Settings:Allow registration
When enabled, the registration form is shown on the login page so anyone with access to the URL can create an account. Disable this after you have created all your users to prevent unauthorized sign-ups.
Allow password login
Controls whether the username/password form appears at all. Disable this to force all users through OIDC. Any user who also has an OIDC account linked (dual auth) can still log in via OIDC.
Allow password reset
When enabled, users can request a password reset from the login page. The reset code is written to the Docker logs; there is no email delivery. An admin reads the code from
docker logs termix and shares it with the user.OIDC / single sign-on
Termix supports any OIDC-compliant identity provider, including Authentik, Keycloak, Authelia, Google, GitHub (via OIDC apps), and others. OIDC can be configured either through environment variables at startup or through the admin UI at Admin Panel → OIDC Configuration. Environment variables take precedence over UI settings.Required fields
The client ID registered with your identity provider.
The client secret from your identity provider. Stored encrypted in the database using the admin user’s data key.
The issuer URL of your OIDC provider. Termix uses this to discover the JWKS endpoint for token verification.
The authorization endpoint where users are redirected to authenticate.
The token endpoint used to exchange an authorization code for tokens.
Dot-separated path into the userinfo payload used as the unique user identifier (e.g.
sub, email, profile.id).Dot-separated path into the userinfo payload from which Termix reads the display name.
Optional fields
The userinfo endpoint. When omitted, Termix discovers it automatically from
.well-known/openid-configuration or tries common paths.Space-separated OAuth 2.0 scopes requested during the authorization flow.
Comma-separated list of allowed identifiers or domain patterns. See below for pattern syntax.
OIDC allowed users
Theallowed_users field filters which OIDC users can access Termix. When left empty, any successfully authenticated OIDC user is allowed.
| Pattern | Effect |
|---|---|
alice@example.com | Exact match against the identifier or email |
@example.com | Allows any identifier or email ending in @example.com |
* | Allows all OIDC users |
@example.com,admin@other.org
The filter is checked against both the configured identifier_path value and the user’s email claim (when available and different from the identifier).
OIDC callback URL
When registering Termix in your identity provider, set the redirect URI to:X-Forwarded-Proto and X-Forwarded-Host headers so the callback URL is constructed correctly.
Two-factor authentication (TOTP)
Each user can enable time-based one-time password (TOTP) 2FA from their Profile page. Admins cannot force 2FA on other users from the admin panel; each user opts in individually.Setting up TOTP
Open your profile
Click your username in the top-right corner and select Profile, then navigate to the Security section.
Initiate setup
Click Enable Two-Factor Authentication. Termix generates a TOTP secret and displays a QR code.
Scan the QR code
Scan the QR code with an authenticator app such as Google Authenticator, Authy, or Bitwarden Authenticator. The entry will appear as Termix (your-username).
Logging in with TOTP
After entering your username and password, a second screen prompts for a 6-digit TOTP code. You can enter either a live code from your authenticator app or one of your backup codes (which is then consumed and can no longer be used). TOTP verification attempts are rate-limited. Too many failed attempts will temporarily block verification for that user.Generating new backup codes
Go to Profile → Security → Backup Codes and authenticate with your password or a current TOTP code to generate a fresh set of 8 backup codes. The old set is immediately invalidated.Disabling TOTP
Go to Profile → Security and click Disable Two-Factor Authentication. You must authenticate with either your current password or a valid TOTP code.Trusted devices
After successfully completing TOTP verification, you can check Remember this device on the TOTP prompt. Termix registers a fingerprint for that browser/device combination. On subsequent logins from the same device, the TOTP step is skipped. Trusted devices are also cleared automatically when you enable or change TOTP. You can view and remove individual trusted devices from Profile → Security → Trusted Devices.Dual authentication (account linking)
If you created a local account and later want to also sign in via OIDC, Termix can link both methods to the same account. When a user who has a local password also has an OIDC identifier set, they can log in with either method. Their username is preserved from the local account and is not overwritten by the OIDC display name. To link an OIDC account to an existing local account, log in via OIDC when registration is enabled. If the OIDC identifier matches a known user in the database, the link is created automatically. Contact your admin if you need assistance linking accounts.Session management
Termix issues a signed JWT stored in an HTTP-only cookie. Sessions can be configured and revoked from the user’s Profile → Sessions page.| Session type | Default duration |
|---|---|
| Standard browser session | 24 hours (configurable in admin settings) |
| “Remember me” session | 30 days |
| Desktop / mobile app session | 30 days |
| Pending TOTP token | 10 minutes |