Admin Features

Overview

ARROW provides administrative features for site administrators to support users and troubleshoot issues. The primary admin feature is user impersonation, which allows authorized administrators to temporarily assume the identity of another user.

Admin Impersonation

Admin impersonation enables site administrators to experience ARROW exactly as a specific user would, facilitating support and troubleshooting without requiring the user’s credentials.

Purpose

Use Case	Description
Support troubleshooting	Investigate user-reported issues
Permission verification	Verify user sees expected content
Training	Demonstrate features from user perspective
Audit	Verify user access and capabilities

Security Model

Only users with elevated privileges can impersonate:

Privilege	Can Impersonate
is_site_admin	Yes
is_superuser	Yes
Regular Admin	No
Manager	No
User	No

Impersonation Workflow

The impersonation process follows a secure workflow with full audit logging.

Impersonation Flow

sequenceDiagram
    participant Admin
    participant Arrow
    participant PocketBase
    participant TargetUser

    Admin->>Arrow: Select Organization
    Arrow-->>Admin: List Users in Org
    Admin->>Arrow: Generate Token (user, reason, duration)
    Arrow->>Arrow: Validate Admin Permissions
    Arrow->>PocketBase: Create Auth Token for Target User
    PocketBase-->>Arrow: JWT Token
    Arrow->>Arrow: Hash Token (SHA-256)
    Arrow->>Arrow: Create Session Record
    Arrow-->>Admin: Return Token
    Admin->>Arrow: Use Token as Target User
    Arrow->>PocketBase: Validate Token
    PocketBase-->>Arrow: Authenticated as Target User
    Arrow-->>Admin: Access Granted

Workflow Steps

1. Select organization - Admin chooses the target user’s organization
2. Select role filter - Optionally filter users by role
3. Select target user - Choose the user to impersonate
4. Provide reason - Document justification for impersonation (required)
5. Set duration - Specify token validity period (default: 1 hour)
6. Generate token - System creates time-limited auth token
7. Session logged - Comprehensive audit record created
8. Use token - Admin authenticates as target user
9. Terminate session - Manually end early or let token expire

Token Generation

Token generation is implemented in backend/api/admin_impersonation/handlers.go (lines 262-271):

token, err := targetUser.NewAuthToken()
if err != nil {
    return err
}

The token is a standard PocketBase JWT that authenticates as the target user.

Security Controls

ARROW implements multiple security controls to prevent abuse of the impersonation feature.

Rate Limiting

Impersonation is rate-limited per admin (lines 205-329 in backend/api/admin_impersonation/handlers.go):

Limit	Value
Impersonations per hour	5
Per admin	Individual tracking

Token Security

Control	Implementation
Token hashing	SHA-256 hash stored (never raw token)
Time limitation	Configurable expiration (default 1 hour)
Single use tracking	Session records track token usage

Session Expiration

Tokens automatically expire after the specified duration. The system enforces expiration by:

1. Storing expires_at timestamp on session record
2. Validating expiration on token use
3. Rejecting expired tokens

Forensic Logging

Every impersonation session records:

Field	Purpose
ip_address	Client IP of admin
user_agent	Browser/client information
created	Session start timestamp
reason	Documented justification

Organization Requirement

Users without an organization cannot be impersonated. This prevents impersonation of:

• Site administrators
• System service accounts
• Unassigned users

Session Management

Impersonation sessions are tracked in the impersonation_sessions collection.

Session Schema

Field	Type	Description
admin_user	Relation	ID of admin who initiated impersonation
target_user	Relation	ID of user being impersonated
reason	Text	Justification for impersonation
token_hash	Text	SHA-256 hash of the auth token
expires_at	DateTime	Session expiration timestamp
terminated_at	DateTime	Early termination timestamp (optional)
ip_address	Text	Client IP of admin
user_agent	Text	Browser/client info

Session Listing

Sessions can be viewed based on admin privileges:

Privilege	Visibility
Site Admin	All sessions across all admins
Regular Admin	Only their own sessions

Session Termination

Active sessions can be terminated early:

POST /api/admin/impersonation/terminate/{session_id}

Termination:

• Sets terminated_at timestamp
• Invalidates the token immediately
• Logs termination event

API Endpoints

List Organizations

GET /api/admin/impersonation/organizations

Returns organizations available for impersonation.

Response:

[
  {
    "id": "org_123",
    "name": "Acme Corporation"
  }
]

List Roles for Organization

GET /api/admin/impersonation/roles?organizationId={org_id}

Returns roles assignable within the specified organization.

Response:

[
  {
    "id": "role_admin",
    "name": "Admin"
  },
  {
    "id": "role_manager",
    "name": "Manager"
  },
  {
    "id": "role_user",
    "name": "User"
  }
]

List Users for Organization

GET /api/admin/impersonation/users?organizationId={org_id}

Returns users in the specified organization that can be impersonated.

Query Parameters:

Parameter	Required	Description
organizationId	Yes	Organization ID
roleId	No	Filter by role

Response:

[
  {
    "id": "user_123",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "Admin"
  }
]

Generate Impersonation Token

POST /api/admin/impersonation/generate-token

Generates a time-limited authentication token for impersonation.

Request:

{
  "target_user_id": "user_123",
  "reason": "Investigating reported permission issue",
  "duration_minutes": 60
}

Field	Required	Description
target_user_id	Yes	User to impersonate
reason	Yes	Justification (min 10 characters)
duration_minutes	No	Token validity (default: 60, max: 480)

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2024-01-15T15:30:00Z",
  "session_id": "session_abc123"
}

Terminate Session

POST /api/admin/impersonation/terminate/{session_id}

Terminates an active impersonation session early.

Response:

{
  "success": true,
  "terminated_at": "2024-01-15T14:45:00Z"
}

List Sessions

GET /api/admin/impersonation/sessions

Lists impersonation sessions (filtered by admin privileges).

Query Parameters:

Parameter	Description
status	Filter by status: active, expired, terminated, all
admin_id	Filter by admin (site admins only)

Response:

[
  {
    "id": "session_abc123",
    "admin_user": {
      "id": "admin_1",
      "name": "Site Admin"
    },
    "target_user": {
      "id": "user_123",
      "name": "John Doe"
    },
    "reason": "Investigating permission issue",
    "created": "2024-01-15T14:00:00Z",
    "expires_at": "2024-01-15T15:00:00Z",
    "terminated_at": null,
    "ip_address": "192.168.1.100",
    "user_agent": "Mozilla/5.0..."
  }
]

Audit and Compliance

ARROW maintains a comprehensive audit trail for all impersonation activity.

Audit Logging

The system logs impersonation events in backend/api/admin_impersonation/handlers.go:

Token Generation (lines 250-258, 307-315):

[IMPERSONATION] Admin {admin_id} generated token for user {target_id}
  Reason: {reason}
  Duration: {minutes} minutes
  IP: {ip_address}
  User-Agent: {user_agent}

Session Termination (lines 368-373):

[IMPERSONATION] Session {session_id} terminated by {admin_id}
  Original admin: {original_admin}
  Target user: {target_user}
  Reason for termination: {reason}

Querying Sessions for Compliance

To audit impersonation activity:

1. Via API - Use GET /api/admin/impersonation/sessions with appropriate filters
2. Via PocketBase - Query impersonation_sessions collection directly
3. Export logs - Application logs contain detailed impersonation events

Immutable Audit Trail

Session records are never deleted:

Action	Record Effect
Create session	New record with all details
Terminate session	terminated_at timestamp set
Session expires	No change (natural expiration)

This ensures complete audit history for compliance requirements.

Compliance Considerations

Requirement	ARROW Implementation
Access justification	Required reason field
Time limitation	Configurable token expiration
Activity logging	Comprehensive session records
Review capability	Session listing and filtering
Termination	Immediate revocation support

Implementation Reference

Key Source Files

File	Purpose
backend/api/admin_impersonation/handlers.go	All impersonation endpoints and logic

Key Code Locations

Function	Lines	Description
Rate limiting	205-329	5 impersonations/hour/admin
Token generation	262-271	Create target user auth token
Token hashing	275-280	SHA-256 hash for storage
Logging (generate)	250-258, 307-315	Token generation audit
Logging (terminate)	368-373	Session termination audit

Related Documentation

• User Management - Role and permission system
• Authentication - Zitadel integration and token management