Admin Plugin

OverviewCopy Anchor Link

The Admin plugin provides administrative operations for managing users, accounts, sessions, and user impersonation. It enables system administrators to perform CRUD operations on users and accounts, manage user and session states (banning, revoking sessions), control impersonation activities, and maintain comprehensive audit trails.

FeaturesCopy Anchor Link

• User Management — Create, read, update, and delete users with full lifecycle support
• Account Management — Manage linked provider accounts for users
• User State Management — Ban and unban users with optional expiration and reason tracking
• Session State Management — Revoke sessions with audit trail and reason tracking
• User Impersonation — Admin impersonation of users with time-limited sessions and audit logging
• Audit Trail — Comprehensive tracking of all administrative actions

ConfigurationCopy Anchor Link

Standalone ModeCopy Anchor Link

[plugins.admin]
enabled = true
impersonation_max_expires_in = "15m"

Library ModeCopy Anchor Link

import (
	adminplugin "github.com/Authula/authula/plugins/admin"
	adminplugintypes "github.com/Authula/authula/plugins/admin/types"
)

adminplugin.New(adminplugintypes.AdminPluginConfig{
	Enabled:                     true,
	ImpersonationMaxExpiresIn:   15 * time.Minute,
}),

API ReferenceCopy Anchor Link

Each endpoint in this plugin requires the caller to have a specific hardcoded permission assigned to their role(s).

User ManagementCopy Anchor Link

Account ManagementCopy Anchor Link

User State ManagementCopy Anchor Link

Session State ManagementCopy Anchor Link

Impersonation ManagementCopy Anchor Link

Database SchemaCopy Anchor Link

Table: admin_impersonationsCopy Anchor Link

Table: admin_user_statesCopy Anchor Link

Table: admin_session_statesCopy Anchor Link

Migrations are automatically handled when the plugin is initialized.

Plugin CapabilitiesCopy Anchor Link

The Admin plugin provides the following capabilities:

• User CRUD Operations — Full lifecycle management for user accounts
• Account Linking — Manage external provider account associations
• User Banning — Temporary or permanent user suspension with reason tracking
• Session Revocation — Invalidate sessions with audit trail
• User Impersonation — Admin impersonation with time-limited sessions and comprehensive logging
• Audit Logging — All administrative actions are tracked for compliance and debugging

Impersonation LifecycleCopy Anchor Link

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Start     │────▶│ Impersonation│────▶│   Active    │
│ Impersonation│    │   Created    │     │  Session    │
└─────────────┘     └──────────────┘     └──────┬──────┘
                                                │
                      ┌─────────────────────────┼──────────────────────┐
                      │                         │                      │
                      ▼                         ▼                      ▼
              ┌──────────────┐          ┌─────────────┐        ┌─────────────┐
              │   Expiration │          │   Manual    │        │   Target    │
              │   (Timeout)  │          │    Stop     │        │   Deleted   │
              └──────┬───────┘          └──────┬──────┘        └──────┬──────┘
                     │                         │                      │
                     ▼                         ▼                      ▼
              ┌──────────────┐          ┌─────────────┐        ┌─────────────┐
              │   Session    │          │   Session   │        │   Session   │
              │   Ended      │          │   Ended     │        │   Ended     │
              └──────────────┘          └─────────────┘        └─────────────┘

Client PluginCopy Anchor Link

If you're using the Authula SDK, add the plugin to the SDK like so:

import { createClient } from "authula";
import { AdminPlugin } from "authula/plugins";

export const authulaClient = createClient({
  url: "http://localhost:8080/auth",
  plugins: [
    // other plugins...
    new AdminPlugin(),
  ],
});

Security RecommendationsCopy Anchor Link

• Access Control — All admin endpoints should be protected by appropriate authentication and authorization ideally using the Access Control plugin alongside this plugin to restrict access to authorized administrators only.
• Impersonation Limits — Set reasonable impersonation_max_expires_in values to limit exposure window
• Audit Review — Regularly review impersonation and ban logs for compliance and security auditing
• Least Privilege — Only grant access to routes for users who absolutely require it
• Reason Tracking — Always document reasons for bans and session revocations for audit purposes
• Session Security — Impersonation sessions should be treated with the same security considerations as regular sessions