Aptli

Authentication

Authentication verifies who you are before granting access to Aptli. Aptli supports username/password login, OAuth single sign-on (Google, GitHub, Microsoft, Keycloak), and two-factor authentication. This section covers how to use and configure each method, manage account locks, and handle password resets.

Active Login Methods

Login page showing available authentication methods including OAuth providers

Configure which authentication methods are available:

Username/Password (Default):

  • Email + password combination
  • Password requirements: minimum 8 characters, complexity rules
  • Automatic logout after inactivity (configurable, default 1 day)

OAuth Providers:

  • GitHub OAuth
  • Google OAuth
  • Additional providers configurable (contact support)

Configuration: Navigate to App Settings → Authentication → Active Login Methods

  • At least one method must be enabled
  • Multiple methods can be active simultaneously
  • Users choose preferred method at login screen

Two-Factor Authentication (2FA)

Enabling 2FA:

  1. Navigate to user profile
  2. Click "Enable Two-Factor Authentication"
  3. Scan QR code with authenticator app (Google Authenticator, Authy, etc.)
  4. Enter 6-digit code to confirm
  5. Save recovery codes (in case phone lost)

Login with 2FA:

  1. Enter email and password (or OAuth)
  2. System prompts for 6-digit code
  3. Open authenticator app
  4. Enter current code (refreshes every 30 seconds)
  5. Access granted

Recovery Codes:

  • 10 one-time-use codes generated at 2FA setup
  • Store securely (password manager, printed copy)
  • Use if authenticator unavailable
  • Each code valid once

Disabling 2FA:

  • Navigate to user profile
  • Click "Disable Two-Factor Authentication"
  • Enter current 6-digit code (or recovery code)
  • Confirm disable

Spotting Users Without 2FA

Admin View:

  1. Navigate to Admin → Users
  2. Add column: "2FA Enabled" (boolean)
  3. Filter: "2FA Enabled = false"
  4. Export list for follow-up

Enforcement: App Settings → Authentication → Require 2FA

  • Enable to force all users to set up 2FA
  • Grace period configurable (e.g., 30 days)
  • After grace period, users cannot login without 2FA

Notification Campaign:

  • Bulk email users without 2FA
  • Include setup instructions
  • Emphasize security benefits
  • Set deadline for compliance

OAuth Provider Setup

OAuth providers (Google, GitHub, Microsoft, Keycloak) are configured by your system administrator. See the OAuth Setup Guide for configuration details.

Adding OAuth to User Account

For Existing Username/Password Users:

  1. Login with email and password
  2. Navigate to user profile
  3. Click "Link OAuth Account"
  4. Choose provider (GitHub or Google)
  5. Authorize with provider
  6. OAuth account linked (can now login with either method)

For New Users:

  • First login with OAuth creates account automatically
  • Email from OAuth provider must be in allowed domains
  • Account created with OAuth-only login (no password set)
  • Can add password later from profile

Email Validation

New User Flow:

  1. User signs up (or admin creates account)
  2. Validation email sent to user's email address
  3. Email contains 10-minute expiration token
  4. User clicks link in email
  5. Account validated (can now login)

Validation Required:

  • Cannot login (any method) until email validated
  • Includes OAuth users (email must be validated even if provider verified)

Resend Validation Email: Admin can resend from user profile:

  1. Navigate to Admin → Users
  2. Open user profile
  3. Click "Resend Validation Email"
  4. New 10-minute token sent

Manual Validation: Admin with usersUpdate can manually validate:

  1. Navigate to user profile
  2. Set "Email Validated" date to current date
  3. Save (user can now login)

Login Security

Max Login Attempts:

  • Default: 5 failed attempts
  • Configurable in App Settings
  • After max attempts: account hard locked
  • Unlock requires admin with usersUpdate permission

Hard Lock:

  • Account cannot login (any method)
  • Visible in user profile: "Hard Lock" badge
  • Unlock: Admin clicks "Unlock Account" action
  • Reset: Failed attempt counter reset to 0

Session Expiry:

  • Automatic Logout: Inactivity timeout (default 1 day)
    • Reading or writing data resets countdown
    • Configurable per app settings
  • Server Session Timeout: Server session timeout (default 1 week)
    • Forces re-login regardless of activity
    • Security measure for long-running sessions
  • Session Expiry: Absolute max session duration (default 1 week)
    • Multiple devices may have different expirations
    • Prevents indefinite sessions

Force Logout

Admin Action:

  1. Navigate to Admin → Users
  2. Open user profile
  3. Actions → Force Logout
  4. User's session terminated immediately
  5. User must re-login

Use Cases:

  • Security incident (compromised account)
  • User left session open on public computer
  • Administrative lock (pending investigation)

Troubleshooting Login

User Can't Find Account

Check:

  1. Navigate to Admin → Users
  2. Filter by email (case-sensitive)
  3. If not found: Account may be deleted
  4. Click "See Deleted" button (requires viewDeleted permission)
  5. If found in deleted: Undelete (requires usersCreate permission)

Hard Lock

Check:

  1. Navigate to user profile
  2. Look for "Hard Lock" badge
  3. If present: Click "Unlock Account" (requires usersUpdate permission)
  4. User can now login

Email Not Validated

Check:

  1. Navigate to user profile
  2. "Email Validated" field should have date
  3. If blank: Resend validation email OR manually set date
  4. User cannot login via any method without validation

Bad Domain

Check:

  1. Navigate to App Settings → Authentication
  2. "Allowed Domains" list
  3. Verify user's email domain included
  4. If missing: Add domain OR create account manually (bypasses domain check)

OAuth Not Working

Check:

  1. Verify environment variables set (CLIENT_ID, CLIENT_SECRET)
  2. Check callback URL matches provider configuration
  3. Test: Logout, click "Sign in with Provider"
  4. Error messages in browser console
  5. Check provider dashboard for auth attempts

Password Reset

User-Initiated:

  1. Click "Forgot Password" on login page
  2. Enter email address
  3. Reset email sent (10-minute token)
  4. Click link in email
  5. Enter new password
  6. Password reset (can now login)

Admin-Initiated: Admin with usersUpdate can reset:

  1. Navigate to user profile
  2. Actions → Reset Password
  3. Temporary password generated
  4. Email sent to user with temp password
  5. User must change password on first login

Best Practices

Enable 2FA:

  • Require for all admin accounts
  • Encourage for all users
  • Set compliance deadline

Use OAuth When Possible:

  • Reduces password fatigue
  • Leverages provider security
  • Easier account recovery

Monitor Failed Logins:

  • Review hard locked accounts weekly
  • Pattern of locks = password guessing attack
  • Enable 2FA enforcement

Regular Session Expiry:

  • Don't set inactivity timeout too long (24 hours reasonable)
  • CSRF expiry prevents indefinite sessions
  • Balance security vs. user convenience

Allowed Domains:

  • Keep list tight (only org domains)
  • External contractors = create manually (bypass domain check)
  • Review quarterly (remove unused domains)