Admin Plugin

Overview

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.

Features

• 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

Configuration

Standalone Mode

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

Library Mode

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 Reference

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

User Management

Account Management

User State Management

Session State Management

Impersonation Management

Database Schema

Table: admin_impersonations

Table: admin_user_states

Table: admin_session_states

Migrations are automatically handled when the plugin is initialized.

Plugin Capabilities

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 Lifecycle

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

Client Plugin

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 Recommendations

• 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