Skip to main content

Authentication

Xermius provides secure authentication methods to protect your SSH connections and data. The application uses a multi-layered security approach with backend authentication and local encryption.

Overview​

Xermius authentication consists of two main components:

1. Backend Authentication​

Authenticate with Xermius cloud services to enable:

  • Cross-device sync: Sync your hosts, keys, and settings across devices
  • Cloud backup: Automatic backup of your configurations
  • Notifications: Receive security alerts and sync notifications
  • Multi-device management: Manage all your devices from web dashboard

2. Local Encryption​

After backend authentication, set up local encryption to protect:

  • SSH credentials: Passwords and private keys
  • Connection data: Host configurations and metadata
  • Sensitive settings: API keys and tokens

All sensitive data is encrypted locally using your master password before being stored or synced.

Authentication Methods​

Email & Password​

Traditional email and password authentication with OTP verification:

  • Email-based registration and login
  • 6-digit OTP verification sent to your email
  • Secure password hashing on backend
  • Session management with automatic token refresh

Google OAuth​

Sign in with your Google account for quick access:

  • Loopback flow: Opens browser for Google sign-in (recommended)
  • URI scheme flow: Alternative method for restricted environments
  • No password to remember
  • Leverages Google's security infrastructure

Security Features​

Master Password​

Your master password is the key to your encrypted data:

  • Never sent to server: Stays on your device only
  • Encrypts all sensitive data: SSH keys, passwords, credentials
  • Cannot be recovered: If lost, data cannot be decrypted
  • Optional auto-login: Save master password in system keychain for convenience

Encryption Setup​

First-time setup wizard guides you through:

  1. Backend authentication: Sign in or register
  2. Master password creation: Set up local encryption
  3. Password strength validation: Ensures strong master password
  4. Confirmation: Verify master password before proceeding

Session Management​

Secure session handling:

  • In-memory sessions: Active session stored securely
  • Auto-login support: Automatic login with saved master password
  • Session expiration: Automatic logout on token expiration
  • Unauthorized detection: Automatic logout on 401 responses

Authentication Flow​

First Time Setup​

1. Launch Xermius
   ↓
2. Choose authentication method:
   - Email & Password
   - Google OAuth
   ↓
3. Verify with OTP (email only)
   ↓
4. Set up encryption:
   - Create master password
   - Confirm password
   ↓
5. Ready to use!

Subsequent Logins​

1. Launch Xermius
   ↓
2. Auto-login attempt (if enabled)
   ↓
3. If auto-login fails:
   - Enter master password
   or
   - Sign in again
   ↓
4. Access granted

Best Practices​

Master Password​

  • Use strong password: Minimum 8 characters, mix of letters, numbers, symbols
  • Don't reuse passwords: Use unique password for Xermius
  • Store safely: Use password manager or write down securely
  • Cannot be recovered: No way to reset if forgotten

Account Security​

  • Enable 2FA: Add extra security layer (if available)
  • Use Google OAuth: Leverage Google's security features
  • Monitor devices: Check active devices in web dashboard
  • Review login notifications: Watch for suspicious activity

Session Security​

  • Logout when done: Especially on shared computers
  • Don't save master password: On untrusted devices
  • Regular password rotation: Change master password periodically
  • Secure your email: Email is recovery method

Troubleshooting​

Can't Login​

  • Check internet connection: Backend authentication requires internet
  • Verify credentials: Ensure correct email/password
  • Check OTP code: Code expires after 10 minutes
  • Try Google OAuth: Alternative sign-in method

Forgot Master Password​

  • No recovery possible: Master password cannot be reset
  • Data is encrypted: Cannot be decrypted without master password
  • Start fresh: Logout and setup new encryption (loses local data)
  • Restore from sync: If you have another device with access

Auto-Login Not Working​

  • Master password not saved: Need to save in system keychain
  • Keychain access denied: Check system permissions
  • Session expired: Need to re-authenticate
  • Try manual login: Enter master password manually

Next Steps​