Skip to content

Platform Identity, Session And Impersonation — Administrator And Support Runbook

  • Status: SOURCE-RECONCILED REPOSITORY RUNBOOK / NOT CURRENT WIKI
  • Current source baseline: qa/master@3c084671c034f8f5136b02dce990ecff6c66d107
  • Source authority: Identity source authority
  • Rebuild packet: Identity rebuild packet
  • Audience: super-admin, tenant administrator, support operator, identity/session owner and migration operator
  • Phase implementation: USER HOLD
  • Important: this Runbook documents diagnosis and recovery boundaries. It does not authorize account, password, session or impersonation changes.

1. First Principle

Before changing anything, identify four independent values.

Physical actor
Effective subject
Tenant target
Session / impersonation state

Do not use only the username displayed in the tenant application. Under impersonation it may be the effective subject, not the physical actor.

2. Safe Information To Collect

Collect:

  • environment and release SHA;
  • current URL/page/API route;
  • physical login username/ID when available;
  • effective displayed username;
  • tenant ID/name;
  • whether impersonation banner is present;
  • target user ID/username when selected;
  • session start/last known activity/expiry evidence when available;
  • request/correlation ID;
  • exact visible error;
  • whether another device/session is involved;
  • recent password/role/tenant changes.

Do not collect in a ticket or chat:

  • password;
  • password hash;
  • raw session cookie/token;
  • API/OAuth token;
  • secret config value;
  • authorization header;
  • full sensitive provider payload.

3. Sign-In Diagnosis

3.1 User sees invalid username/password

  1. Confirm the exact username entered.
  2. Do not reveal whether the username exists.
  3. Confirm whether the account is expected in this environment.
  4. Check whether another tenant may use the same username only through authorized DB/schema review.
  5. Confirm whether the user recently changed/reset the password.
  6. Do not repeatedly retry many passwords.
  7. Escalate to identity owner with safe account reference and request time.

3.2 User sees service unavailable sign-in error

  1. Record request time and environment.
  2. Check application/DB availability through approved diagnostics.
  3. Do not reset the password unless credential failure is actually established.
  4. If a legacy-hash rehash race is suspected, preserve the exact user/time and inspect the conditional update result.

3.3 Sign-in succeeds but wrong page opens

Read in order:

original session user/client/role
-> effective impersonation target
-> effective roles
-> role default menu
-> menu/page/module availability

Do not change role or default page until the access chain is identified.

4. Session Diagnosis

4.1 User is unexpectedly signed out

Current source has one 20-hour PHP TTL but does not expose a separate idle/absolute/revocation reason.

Collect:

  • last successful request time;
  • whether the browser/device changed;
  • HTTPS/proxy route;
  • cookie presence through approved browser diagnostics;
  • whether password/account/role changed;
  • whether application restarted or session storage changed.

Report the reason as UNKNOWN until authoritative evidence distinguishes expiry, missing cookie, invalid session or explicit logout.

4.2 User remains signed in longer than expected

Do not infer a defect from elapsed clock time alone. Current PHP cookie/GC behavior, request activity and server cleanup must be measured.

4.3 Page hangs while another request is active

Check whether a long request holds the PHP session lock. Some read-only API routes release the lock; many other requests may not.

Do not invalidate the session as the first recovery step.

5. Logout And Reset

5.1 Reset

Current Reset clears selected UI/menu/sessionStorage state and reloads the app. It is not sign-out.

5.2 Sign out

Current sign-out destroys the current PHP session after unsetting selected fields.

After sign-out:

  1. confirm the next protected request redirects or returns unauthenticated;
  2. do not claim other devices/sessions were revoked;
  3. if another device remains active, escalate under the open session-revocation policy;
  4. do not clear cookies/tokens manually unless authorized support procedure requires it.

6. Impersonation Diagnosis

6.1 Before starting impersonation

Confirm:

  • physical actor is super-admin;
  • exact target tenant;
  • whether a real target user is required;
  • reason/support case;
  • intended read/write scope;
  • whether target-role acceptance is the goal.

If target-role acceptance is required, tenant-only impersonation is insufficient.

6.2 User impersonation

Expected visible state:

physical actor remains super-admin
subject is target user
tenant is target user's tenant
banner identifies target

Verify:

  • target user belongs to tenant;
  • effective roles match current target user record;
  • direct page and API behavior matches expected subject policy;
  • physical actor remains in audit/correlation.

6.3 Tenant-only impersonation

Expected state:

actor = super-admin
subject = none
tenant = selected tenant

Use for bounded support/diagnostics only. Do not report role-specific behavior as verified.

6.4 Wrong target or stale impersonation

  1. Stop business writes.
  2. Record current actor, target and tenant.
  3. End impersonation through the supported control.
  4. Confirm the admin console/physical actor is restored.
  5. Start a new context only after the target is rechecked.
  6. Do not edit session storage manually.

6.5 Impersonation end response is unclear

Reread:

  • impersonation banner;
  • effective tenant/user;
  • current landing page;
  • safe identity context if available.

Do not submit end/start repeatedly without reread.

7. Password Change And Reset

7.1 Own password

Before changing:

  • confirm the physical/effective identity;
  • do not perform “own password” while impersonating unless accepted policy explicitly permits it;
  • verify the current password only through the command.

After success:

  • confirm the new credential at the next accepted login point;
  • record whether the current session remained active;
  • do not claim other sessions were revoked;
  • do not store the password in evidence.

7.2 Administrator reset

Before reset:

  • confirm target tenant and user;
  • confirm privileged authorization/reason;
  • determine whether session revocation/user notification is separately required;
  • avoid resetting merely to solve an access-policy problem.

After reset:

password changed
-> verify exact target row/result
-> verify accepted notification/session disposition

Do not publish or log the new password.

8. Common Failure Matrix

Symptom First authoritative reread Do not do first Owner
login rejected account/environment and safe login result reveal account existence or mass reset identity owner
wrong tenant original session + impersonation target edit business record/client ID identity/tenant owner
wrong role/menu target user current role + access chain add broad admin role access owner
impersonation banner stale current session impersonation object/effective context manually alter browser storage identity owner
password changed but old session works session/revocation evidence assume breach or revoke DB rows ad hoc session policy owner
unexpected logout cookie/session/proxy/application evidence change TTL immediately deployment/session owner
provider user mismatch local actor/subject + provider mapping treat provider identity as local authority integration owner
response missing after start/end/reset authoritative identity/session reread repeat command blindly identity owner

9. Unknown-Result Recovery

Identity command response missing
-> reread current session and impersonation state
-> reread password/session disposition when safely possible
-> classify committed / not committed / unknown
-> repeat only an idempotent or explicitly missing boundary

Examples:

  • Impersonation may already be active.
  • Password may already be updated.
  • Current session may already be destroyed.
  • A redirect may fail after successful state change.

10. Escalation Packet

Include:

  • environment and release SHA;
  • physical actor safe ID/username;
  • effective subject safe ID/username;
  • tenant ID;
  • impersonation mode/start time if applicable;
  • page/API/action;
  • request/correlation ID;
  • visible state/error;
  • last authoritative reread;
  • recent password/role/account changes;
  • whether another device/session is involved;
  • actions already attempted.

Exclude passwords, cookies, tokens and secrets.

11. Current Versus Target Procedures

Current supported procedures are limited to the current PHP login/session/admin controls.

The following are target-only until implemented and verified:

  • session inventory/revoke UI;
  • separate idle/absolute timeout display;
  • privileged-action reauthentication;
  • reasoned/expiring impersonation reference;
  • cross-runtime PHP/Next.js session diagnostics;
  • MFA;
  • durable access-decision trace.

Do not publish target-only instructions as current.

12. Verification Checklist For A Future Implementation Wave

  • [ ] login modern password;
  • [ ] login legacy hash and one-time rehash;
  • [ ] session ID changes at accepted boundaries;
  • [ ] current and other-session revocation policy;
  • [ ] user impersonation actor/subject/tenant;
  • [ ] tenant-only support warning;
  • [ ] impersonation start/end recovery;
  • [ ] password change/reset session disposition;
  • [ ] service/CLI explicit tenant identity;
  • [ ] PHP/Next.js same-session parity;
  • [ ] logout across selected runtimes;
  • [ ] Client 1 non-regression;
  • [ ] current Wiki labels and links;
  • [ ] rollback.

This Runbook remains repository input until separately reviewed and published.

---

Source: docs/runbooks/PLATFORM_IDENTITY_IMPERSONATION_ADMIN_SUPPORT_RUNBOOK.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.