admin

package
v0.0.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 4, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

README

Admin Plugin

Cross-cutting administrative operations for AuthSome platform management.

Purpose

The admin plugin provides platform-level administrative APIs that span multiple services:

  • User lifecycle management
  • Security operations (ban, impersonation)
  • Session oversight
  • Aggregated statistics
  • Centralized audit logs

Scope

What belongs in admin plugin (cross-cutting):
  • User CRUD operations
  • User impersonation (security-sensitive)
  • Session management across all users
  • Platform-wide statistics
  • Centralized audit log access
  • Role assignments (RBAC integration)
What belongs in individual plugins (plugin-specific):
  • OAuth provider configuration → social plugin
  • 2FA settings management → mfa plugin
  • Passkey configuration → passkey plugin
  • Email template management → notification plugin
  • Rate limit overrides → respective plugins

Architecture Decision

Per architecture decision 1b, 2a, 3a:

  • Admin plugin handles cross-cutting operations
  • Individual plugins expose their own admin endpoints for plugin-specific features
  • Impersonation remains centralized in admin plugin (security-sensitive)

Usage

// Admin plugin is typically used internally, not registered as a plugin
adminSvc := admin.NewService(config, userSvc, sessionSvc, rbacSvc, auditSvc, banSvc)
adminHandler := admin.NewHandler(adminSvc)

// Mount admin routes
router.POST("/admin/users", adminHandler.CreateUser)
router.GET("/admin/users", adminHandler.ListUsers)
// ... other cross-cutting operations

Available Endpoints

User Management
  • POST /admin/users - Create a new user
  • GET /admin/users - List users with filtering and pagination
  • DELETE /admin/users/:id - Delete a user
Security Operations
  • POST /admin/users/:id/ban - Ban a user
  • POST /admin/users/:id/unban - Unban a user
  • POST /admin/users/:id/impersonate - Impersonate a user (security-sensitive)
Session Management
  • GET /admin/sessions - List all active sessions
  • DELETE /admin/sessions/:id - Revoke a session
Role Management
  • POST /admin/users/:id/role - Assign role to user
Statistics & Monitoring
  • GET /admin/stats - Get platform-wide statistics
  • GET /admin/audit-logs - View centralized audit logs

Plugin-Specific Admin Endpoints Pattern

Individual plugins should expose their own admin endpoints:

// Example: MFA plugin admin endpoints
router.GET("/mfa/admin/policies", mfaHandler.ListPolicies)       // Plugin-specific
router.PUT("/mfa/admin/policies/:id", mfaHandler.UpdatePolicy)    // Plugin-specific

// Example: Social plugin admin endpoints  
router.POST("/social/admin/providers", socialHandler.AddProvider) // Plugin-specific
router.GET("/social/admin/providers", socialHandler.ListProviders) // Plugin-specific

See plugin-specific documentation for admin endpoint implementations.

Security & Permissions

Role-Based Access Control

The admin plugin registers the following roles and permissions during initialization:

Admin Role (admin):

  • Priority: 80 (platform-level)
  • Inherits from: member
  • Permissions:
    • admin:user:create on admin:* - Create users
    • admin:user:read on admin:* - List and view users
    • admin:user:update on admin:* - Update user information
    • admin:user:delete on admin:* - Delete users
    • admin:user:ban on admin:* - Ban/unban users
    • admin:session:read on admin:* - View sessions
    • admin:session:revoke on admin:* - Revoke sessions
    • admin:role:assign on admin:* - Assign roles
    • admin:stats:read on admin:* - View statistics
    • admin:audit:read on admin:* - View audit logs

Superadmin Role (superadmin):

  • Priority: 100 (highest platform-level)
  • Inherits from: admin
  • Additional Permissions:
    • admin:user:impersonate on admin:* - Impersonate users (security-sensitive)
    • * on admin:* - Full wildcard access to admin operations
Permission Checks

All admin endpoints:

  • Check permissions via RBAC before performing operations
  • Validate app/org context
  • Log all administrative actions to audit service
  • Use rate limiting
  • Require CSRF protection for state-changing operations
Bootstrapping

Permissions are automatically registered during plugin initialization via the RegisterRoles interface:

// Automatic during server startup
plugin := admin.NewPlugin()
plugin.RegisterRoles(roleRegistry)

See Also

Documentation

Overview

Package admin provides cross-cutting administrative operations for the AuthSome platform.

This service handles platform-level operations that span multiple core services:

  • User lifecycle management (create, list, delete users)
  • Security operations (ban, unban, impersonate users)
  • Session oversight (list and revoke sessions across all users)
  • Platform statistics (aggregated metrics)
  • Centralized audit log access

Plugin-specific administrative operations should be implemented in the respective plugins. See docs/PLUGIN_ADMIN_ENDPOINTS.md for guidelines on adding plugin admin endpoints.

Architecture Decision: Based on decisions 1b, 2a, 3a:

  • This service handles cross-cutting operations only
  • Individual plugins expose their own admin endpoints for plugin-specific features
  • Impersonation remains centralized here (security-sensitive)

Index

Constants

View Source 
const (
	PermUserCreate      = "admin:user:create"
	PermUserRead        = "admin:user:read"
	PermUserUpdate      = "admin:user:update"
	PermUserDelete      = "admin:user:delete"
	PermUserBan         = "admin:user:ban"
	PermUserImpersonate = "admin:user:impersonate"
	PermSessionRead     = "admin:session:read"
	PermSessionRevoke   = "admin:session:revoke"
	PermRoleAssign      = "admin:role:assign"
	PermStatsRead       = "admin:stats:read"
	PermAuditRead       = "admin:audit:read"
)

Admin Permissions These permission strings are registered with the RBAC system during plugin initialization

View Source 
const (
	PluginID      = "admin"
	PluginName    = "Admin"
	PluginVersion = "1.0.0"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BanUserRequest 

type BanUserRequest struct {
	AppID              xid.ID     `json:"app_id"`                         // Platform app (required)
	UserOrganizationID *xid.ID    `json:"user_organization_id,omitempty"` // User-created org (optional)
	UserID             xid.ID     `json:"user_id"`
	Reason             string     `json:"reason"`
	ExpiresAt          *time.Time `json:"expires_at,omitempty"`
	AdminID            xid.ID     `json:"-"` // Set by handler
}

BanUserRequest represents a request to ban a user Updated for V2 architecture

type BanUserRequestDTO added in v0.0.7 

type BanUserRequestDTO struct {
	ID        string     `path:"id" validate:"required"`
	Reason    string     `json:"reason,omitempty"`
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

type Config 

type Config struct {
	// RequiredRole is the role required to access admin endpoints
	RequiredRole string `json:"required_role"`
	// AllowUserCreation allows admins to create users
	AllowUserCreation bool `json:"allow_user_creation"`
	// AllowUserDeletion allows admins to delete users
	AllowUserDeletion bool `json:"allow_user_deletion"`
	// AllowImpersonation allows admins to impersonate users
	AllowImpersonation bool `json:"allow_impersonation"`
	// MaxImpersonationDuration is the maximum duration for impersonation sessions
	MaxImpersonationDuration time.Duration `json:"max_impersonation_duration"`
}

Config holds the admin plugin configuration

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns the default admin plugin configuration

type CreateUserRequest 

type CreateUserRequest struct {
	AppID              xid.ID            `json:"app_id"`                         // Platform app (required)
	UserOrganizationID *xid.ID           `json:"user_organization_id,omitempty"` // User-created org (optional)
	Email              string            `json:"email"`
	Password           string            `json:"password,omitempty"`
	Name               string            `json:"name,omitempty"`
	Username           string            `json:"username,omitempty"`
	Role               string            `json:"role,omitempty"`
	EmailVerified      bool              `json:"email_verified"`
	Metadata           map[string]string `json:"metadata,omitempty"`
	AdminID            xid.ID            `json:"-"` // Set by handler
}

CreateUserRequest represents a request to create a user Updated for V2 architecture: App → Environment → Organization

type CreateUserRequestDTO added in v0.0.7 

type CreateUserRequestDTO struct {
	Email         string            `json:"email" validate:"required,email"`
	Password      string            `json:"password,omitempty"`
	Name          string            `json:"name,omitempty"`
	Username      string            `json:"username,omitempty"`
	Role          string            `json:"role,omitempty"`
	EmailVerified bool              `json:"email_verified"`
	Metadata      map[string]string `json:"metadata,omitempty"`
}

Request types

type DeleteUserRequestDTO added in v0.0.7 

type DeleteUserRequestDTO struct {
	ID string `path:"id" validate:"required"`
}

type ErrorResponse 

type ErrorResponse = responses.ErrorResponse

Response types - use shared responses from core

type GetAuditLogsRequestDTO added in v0.0.7 

type GetAuditLogsRequestDTO struct {
	Page     int `query:"page"`
	PageSize int `query:"page_size"`
}

type GetStatsRequestDTO added in v0.0.7 

type GetStatsRequestDTO struct {
	Period string `query:"period"`
}

type Handler 

type Handler struct {
	// contains filtered or unexported fields
}

Handler handles admin HTTP requests Updated for V2 architecture: App → Environment → Organization

func NewHandler 

func NewHandler(service *Service) *Handler

NewHandler creates a new admin handler

func (*Handler) BanUser 

func (h *Handler) BanUser(c forge.Context) error

BanUser handles POST /admin/users/:id/ban

func (*Handler) CreateUser 

func (h *Handler) CreateUser(c forge.Context) error

CreateUser handles POST /admin/users

func (*Handler) DeleteUser 

func (h *Handler) DeleteUser(c forge.Context) error

DeleteUser handles DELETE /admin/users/:id

func (*Handler) GetAuditLogs 

func (h *Handler) GetAuditLogs(c forge.Context) error

GetAuditLogs handles GET /admin/audit

func (*Handler) GetStats 

func (h *Handler) GetStats(c forge.Context) error

GetStats handles GET /admin/stats

func (*Handler) ImpersonateUser 

func (h *Handler) ImpersonateUser(c forge.Context) error

ImpersonateUser handles POST /admin/users/:id/impersonate

func (*Handler) ListSessions 

func (h *Handler) ListSessions(c forge.Context) error

ListSessions handles GET /admin/sessions

func (*Handler) ListUsers 

func (h *Handler) ListUsers(c forge.Context) error

ListUsers handles GET /admin/users

func (*Handler) RevokeSession 

func (h *Handler) RevokeSession(c forge.Context) error

RevokeSession handles DELETE /admin/sessions/:id

func (*Handler) SetUserRole 

func (h *Handler) SetUserRole(c forge.Context) error

SetUserRole handles POST /admin/users/:id/role

func (*Handler) UnbanUser 

func (h *Handler) UnbanUser(c forge.Context) error

UnbanUser handles POST /admin/users/:id/unban

type ImpersonateUserRequest 

type ImpersonateUserRequest struct {
	AppID              xid.ID        `json:"app_id"`                         // Platform app (required)
	UserOrganizationID *xid.ID       `json:"user_organization_id,omitempty"` // User-created org (optional)
	UserID             xid.ID        `json:"user_id"`
	Duration           time.Duration `json:"duration,omitempty"`
	IPAddress          string        `json:"-"` // Set by handler
	UserAgent          string        `json:"-"` // Set by handler
	AdminID            xid.ID        `json:"-"` // Set by handler
}

ImpersonateUserRequest represents a request to impersonate a user Updated for V2 architecture

type ImpersonateUserRequestDTO added in v0.0.7 

type ImpersonateUserRequestDTO struct {
	ID       string        `path:"id" validate:"required"`
	Duration time.Duration `json:"duration,omitempty"`
}

type ListSessionsRequest 

type ListSessionsRequest struct {
	AppID              xid.ID  `json:"app_id"`                         // Platform app (required)
	UserOrganizationID *xid.ID `json:"user_organization_id,omitempty"` // User-created org (optional)
	UserID             *xid.ID `json:"user_id,omitempty"`
	Page               int     `json:"page"`
	Limit              int     `json:"limit"`
	AdminID            xid.ID  `json:"-"` // Set by handler
}

ListSessionsRequest represents a request to list sessions Updated for V2 architecture

type ListSessionsRequestDTO added in v0.0.7 

type ListSessionsRequestDTO struct {
	Page   int    `query:"page"`
	Limit  int    `query:"limit"`
	UserID string `query:"user_id"`
}

type ListSessionsResponse 

type ListSessionsResponse struct {
	Sessions   []*session.Session `json:"sessions"`
	Total      int                `json:"total"`
	Page       int                `json:"page"`
	Limit      int                `json:"limit"`
	TotalPages int                `json:"total_pages"`
}

ListSessionsResponse represents the response for listing sessions

type ListUsersRequest 

type ListUsersRequest struct {
	AppID              xid.ID  `json:"app_id"`                         // Platform app (required)
	UserOrganizationID *xid.ID `json:"user_organization_id,omitempty"` // User-created org (optional)
	Page               int     `json:"page"`
	Limit              int     `json:"limit"`
	Search             string  `json:"search,omitempty"`
	Role               string  `json:"role,omitempty"`
	Status             string  `json:"status,omitempty"` // active, banned, inactive
	AdminID            xid.ID  `json:"-"`                // Set by handler
}

ListUsersRequest represents a request to list users Updated for V2 architecture

type ListUsersRequestDTO added in v0.0.7 

type ListUsersRequestDTO struct {
	Page   int    `query:"page"`
	Limit  int    `query:"limit"`
	Search string `query:"search"`
	Role   string `query:"role"`
	Status string `query:"status"`
}

type ListUsersResponse 

type ListUsersResponse struct {
	Users      []*user.User `json:"users"`
	Total      int          `json:"total"`
	Page       int          `json:"page"`
	Limit      int          `json:"limit"`
	TotalPages int          `json:"total_pages"`
}

ListUsersResponse represents the response for listing users

type MessageResponse 

type MessageResponse = responses.MessageResponse

type Plugin 

type Plugin struct {
	// contains filtered or unexported fields
}

Plugin implements the AuthSome plugin interface for admin operations

func NewPlugin 

func NewPlugin() *Plugin

NewPlugin creates a new admin plugin instance

func (*Plugin) Description 

func (p *Plugin) Description() string

Description returns the plugin description

func (*Plugin) ID 

func (p *Plugin) ID() string

ID returns the unique plugin identifier

func (*Plugin) Init 

func (p *Plugin) Init(auth interface{}) error

Init initializes the plugin

func (*Plugin) Migrate 

func (p *Plugin) Migrate() error

Migrate runs database migrations (placeholder)

func (*Plugin) Name 

func (p *Plugin) Name() string

Name returns the human-readable plugin name

func (*Plugin) RegisterHooks 

func (p *Plugin) RegisterHooks(registry interface{}) error

RegisterHooks implements the hooks registration (placeholder)

func (*Plugin) RegisterRoles 

func (p *Plugin) RegisterRoles(registry interface{}) error

RegisterRoles implements the PluginWithRoles optional interface This is called automatically during server initialization to register admin permissions

func (*Plugin) RegisterRoutes 

func (p *Plugin) RegisterRoutes(router forge.Router) error

RegisterRoutes registers HTTP routes for the plugin

func (*Plugin) RegisterServiceDecorators 

func (p *Plugin) RegisterServiceDecorators(registry interface{}) error

RegisterServiceDecorators implements service decoration (not needed for admin)

func (*Plugin) Version 

func (p *Plugin) Version() string

Version returns the plugin version

type RevokeSessionRequestDTO added in v0.0.7 

type RevokeSessionRequestDTO struct {
	ID string `path:"id" validate:"required"`
}

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service provides admin functionality for user management

func NewService 

func NewService(
	config Config,
	userService interface{},
	sessionService interface{},
	rbacService *rbac.Service,
	auditService interface{},
	banService interface{},
) *Service

NewService creates a new admin service

func (*Service) BanUser 

func (s *Service) BanUser(ctx context.Context, req *BanUserRequest) error

BanUser bans a user

func (*Service) CreateUser 

func (s *Service) CreateUser(ctx context.Context, req *CreateUserRequest) (*user.User, error)

CreateUser creates a new user with admin privileges

func (*Service) DeleteUser 

func (s *Service) DeleteUser(ctx context.Context, userID, adminID xid.ID) error

DeleteUser deletes a user

func (*Service) ImpersonateUser 

func (s *Service) ImpersonateUser(ctx context.Context, req *ImpersonateUserRequest) (*session.Session, error)

ImpersonateUser creates a session for impersonating a user

func (*Service) ListSessions 

func (s *Service) ListSessions(ctx context.Context, req *ListSessionsRequest) (*ListSessionsResponse, error)

ListSessions lists all sessions with filtering and pagination

func (*Service) ListUsers 

func (s *Service) ListUsers(ctx context.Context, req *ListUsersRequest) (*ListUsersResponse, error)

ListUsers lists users with filtering and pagination

func (*Service) RevokeSession 

func (s *Service) RevokeSession(ctx context.Context, sessionID, adminID xid.ID) error

RevokeSession revokes a session

func (*Service) SetUserRole 

func (s *Service) SetUserRole(ctx context.Context, req *SetUserRoleRequest) error

SetUserRole sets a user's role

func (*Service) UnbanUser 

func (s *Service) UnbanUser(ctx context.Context, req *UnbanUserRequest) error

UnbanUser unbans a user

type SetUserRoleRequest 

type SetUserRoleRequest struct {
	AppID              xid.ID  `json:"app_id"`                         // Platform app (required)
	UserOrganizationID *xid.ID `json:"user_organization_id,omitempty"` // User-created org (optional)
	UserID             xid.ID  `json:"user_id"`
	Role               string  `json:"role"`
	AdminID            xid.ID  `json:"-"` // Set by handler
}

SetUserRoleRequest represents a request to set a user's role Updated for V2 architecture

type SetUserRoleRequestDTO added in v0.0.7 

type SetUserRoleRequestDTO struct {
	ID   string `path:"id" validate:"required"`
	Role string `json:"role" validate:"required"`
}

type StatsResponse 

type StatsResponse struct {
	ActiveUsers    int    `json:"active_users"`
	ActiveSessions int    `json:"active_sessions"`
	TotalUsers     int    `json:"total_users"`
	TotalSessions  int    `json:"total_sessions"`
	BannedUsers    int    `json:"banned_users"`
	Timestamp      string `json:"timestamp"`
}

type UnbanUserRequest 

type UnbanUserRequest struct {
	AppID              xid.ID  `json:"app_id"`                         // Platform app (required)
	UserOrganizationID *xid.ID `json:"user_organization_id,omitempty"` // User-created org (optional)
	UserID             xid.ID  `json:"user_id"`
	Reason             string  `json:"reason,omitempty"`
	AdminID            xid.ID  `json:"-"` // Set by handler
}

UnbanUserRequest represents a request to unban a user Updated for V2 architecture

type UnbanUserRequestDTO added in v0.0.7 

type UnbanUserRequestDTO struct {
	ID     string `path:"id" validate:"required"`
	Reason string `json:"reason,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.