Aptli

Authentication

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

Active Login Methods

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:

  • Google OAuth
  • GitHub OAuth
  • Microsoft OAuth
  • Keycloak / your organization's single-sign-on provider

Configuration: Active login methods are not toggled in App Settings. The login screen shows username/password always, plus whichever OAuth providers have a client ID configured in the environment (NUXT_OAUTH_GOOGLE_CLIENTID, NUXT_OAUTH_GITHUB_CLIENTID, NUXT_OAUTH_MICROSOFT_CLIENTID, NUXT_OAUTH_KEYCLOAK_CLIENTID). To add or remove a provider, your system administrator sets or clears its credentials in the environment — see the OAuth Setup Guide.

  • Username/password is always available
  • 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 → Two-Factor Authentication

  • A single on/off setting (requireTwoFactorAuth) that requires 2FA for every login
  • There is no grace period — when it is on, 2FA applies immediately
  • Turning it on requires the enabling admin to have a verified phone, or they would lock themselves out

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, or your organization's single-sign-on provider) 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)
    • Prevents indefinite sessions

Concurrent Device Sessions:

  • Aptli allows a capped number of concurrent device sessions per account (default 2, set by NUXT_SESSION_MAX_DEVICES)
  • Signing in on a new device beyond the cap evicts the oldest session — that device is signed out and asked to sign in again
  • You can stay logged in on up to the configured number of devices at once
  • Two tabs or windows in the same browser profile share one session — they do not count as separate devices

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. The allowed-domains list is environment-only (NUXT_ALLOWED_DOMAINS), managed from the support portal's My Environment page — not an App Settings field
  2. Verify the user's email domain is included there
  3. If missing: add the domain in the environment OR create the account manually as an admin with usersCreate (bypasses the domain check)

OAuth Not Working

Check:

  1. Confirm with your system administrator that the provider is configured — see the OAuth Setup Guide
  2. Log out and try again, clicking "Sign in with Provider"
  3. If the error persists, capture the error message shown on the login page and share it with your administrator

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:

  • Managed in the environment (NUXT_ALLOWED_DOMAINS) via the support portal's My Environment page, not App Settings
  • Keep list tight (only org domains)
  • External contractors = create manually (bypass domain check)
  • Review quarterly (remove unused domains)