alldigital/PSA
2
0
Fork 0
Code Issues Pull Requests Actions 15 Packages Projects Releases Wiki Activity
PSA/ee/docs/plans/2026-02-03-alga-psa-mobile-app/AUTH_SUPPORT_RUNBOOK.md
Hermes 284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Details
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Details
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
Details
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
Details
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Details
Integration Tests / Check for relevant changes (push) Waiting to run
Details
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Details
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Details
Mobile checks / Mobile unit tests (push) Waiting to run
Details
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Details
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Details
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Details
Temporal Readiness / fast-readiness (push) Waiting to run
Details
Temporal Readiness / docker-parity (push) Waiting to run
Details
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Details
Unit Tests / Skipped-test budget (push) Waiting to run
Details
Unit Tests / Nx affected unit tests (push) Waiting to run
Details
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Details
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Details
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
Details
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Details
Initial import of AlgaPSA codebase from PSA server 
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz

Source: /opt/alga-psa on psa.joliet.tech
2026-06-22 16:12:17 -05:00

1.9 KiB
Raw Permalink Blame History

Support Escalation Runbook — Mobile Auth Issues

Date: 2026-02-03

Symptoms

  • User can’t sign in (Sign In disabled / blocked)
  • User returns from browser but app shows error (callback rejected)
  • Login loop / frequent re-auth
  • Session refresh fails / user is logged out unexpectedly

Quick triage checklist

  1. Confirm the user is on an Alga-hosted environment and using the correct base URL.
  2. Confirm the base URL host is allowlisted (if allowlist enabled).
  3. Confirm the tenant has at least one SSO provider configured (Microsoft/Google).

Common failure modes

“Host not allowlisted”

  • Cause: mobile base URL host doesn’t match hostedDomainAllowlist.
  • Fix: update allowlist, or correct mobile EXPO_PUBLIC_ALGA_BASE_URL.

Callback “state mismatch” / “missing params”

  • Cause: deep link was not the expected callback URL or state was lost.
  • Fix:
    • Ensure app scheme is correct (alga://).
    • Ensure the sign-in flow uses /auth/mobile/handoff with state.

OTT exchange fails (400/401/429)

  • 400 validation: incorrect payload; confirm mobile app version aligns with server contract.
  • 401 auth: OTT expired or already used; check ALGA_MOBILE_OTT_TTL_SEC and user retry timing.
  • 429: rate limiting; verify if user is repeatedly triggering sign-in.

Refresh fails / session revoked

  • Cause: refresh token rotated/revoked; user logged out.
  • Fix:
    • Verify refresh rotation tables/migrations are applied.
    • Inspect audit log entries for refresh/revoke.

Data to collect for escalation

  • Approximate timestamp (UTC) of the failure.
  • Tenant id (from Settings → Account).
  • Mobile app build/version (Settings → Diagnostics).
  • Platform (iOS/Android) and device model/OS version.
  • Correlation id(s) from server logs (x-correlation-id) around the failure.
  • Server audit log events for mobile auth:
    • OTT issued/exchanged
    • Refresh succeeded/failed
    • Revoke/logout