Implement Enterprise Runtime Configuration Management

[aaronlippold]

Enterprise Runtime Configuration Management Implementation

Overview

Implement dynamic runtime configuration management to match enterprise tools like Heimdall2, enabling administrators to modify settings, manage users, and perform bulk operations without application restarts.

Research Summary

Current State

• ✅ Comprehensive environment variable documentation (ENVIRONMENT_VARIABLES.md)
• ✅ OIDC auto-discovery reducing configuration complexity
• ❌ All configuration requires application restart
• ❌ No web-based administration interface
• ❌ Limited bulk operation capabilities

Enterprise Requirements (from #654)

Based on user feedback comparing to Heimdall2 capabilities:

• Runtime configuration changes without restarts
• Web-based administration interface
• Bulk user management operations
• STIG/SRG bulk import and update capabilities
• Scalable configuration management

Implementation Strategy

Recommended Technology Stack

Proven Rails gems for rapid implementation:

1. rails-settings-cached - Database-backed configuration with automatic caching
2. ActiveAdmin - Complete admin interface framework
3. Flipper - Feature flags and A/B testing capabilities
4. Flipper-UI - Web interface for feature management

Architecture Approach

Security Boundaries

# Keep as environment variables (security-critical):
- Database connections (DATABASE_URL)
- OIDC client secrets (VULCAN_OIDC_CLIENT_SECRET) 
- Encryption keys
- LDAP bind credentials

# Move to database-backed (administrative):
- Welcome text and UI customizations
- Session timeout settings
- Email templates and contact information
- Feature flags for experimental features
- User registration and project creation permissions

Technical Implementation

# Database-backed settings with validation
class Setting < RailsSettingsCached::Base
  field :welcome_text, type: :string, default: "Welcome to Vulcan"
  field :session_timeout_minutes, type: :integer, default: 60
  field :contact_email, type: :string, default: "admin@vulcan.local"
  
  validates :session_timeout_minutes, 
    inclusion: { in: 15..480, message: "must be between 15 minutes and 8 hours" }
end

# Runtime usage throughout application
# Before: ENV['VULCAN_WELCOME_TEXT'] || 'Welcome to Vulcan'  
# After:  Setting.welcome_text

Implementation Phases

Phase 1: Foundation (4-6 hours)

Dependencies: Ruby 3.2+, Rails 7+, Modern asset pipeline
Deliverables:

• Install and configure rails-settings-cached
• Install and configure ActiveAdmin
• Create admin authentication and authorization
• Migrate 5-10 safe settings to database-backed configuration
• Basic admin interface for settings management

Settings to migrate first:

• Welcome text and contact information
• Session timeout (with validation limits)
• User registration enablement
• Project creation permissions
• Email template customizations

Phase 2: User Management (2-3 hours)

Deliverables:

• Complete admin interface for user management
• Batch operations (bulk admin assignment, account confirmation)
• User search and filtering capabilities
• Audit logging for administrative actions

Phase 3: Feature Flags (1-2 hours)

Deliverables:

• Install and configure Flipper with web UI
• Implement feature flags for experimental features
• A/B testing capabilities for UI improvements
• Gradual feature rollout mechanisms

Phase 4: Bulk Operations (2-4 hours)

Deliverables:

• STIG/SRG bulk import operations
• Component batch management
• Automated maintenance task scheduling
• Background job monitoring interface

Benefits Analysis

Enterprise Administration Capabilities

✅ Zero-restart configuration changes
✅ Web-based administrative interface
✅ Scalable user management with batch operations
✅ Feature toggles for safe deployments
✅ Bulk STIG/SRG management operations
✅ Audit trails for configuration changes

Implementation Advantages

• Rapid Development: 8-12 hours total using proven gems vs. weeks of custom development
• Battle-Tested: ActiveAdmin powers thousands of Rails applications
• Maintainable: Standard Rails patterns, extensive documentation
• Secure: Maintains separation between security-critical and administrative settings
• Scalable: Database-backed with automatic caching

Dependencies

Prerequisites

• ✅ Issue Heroku-20 Stack EOL + Webpacker Compatibility Blocking All Deployments #670: Heroku-20 EOL + Webpacker migration (BLOCKING)
• ✅ Issue Ruby and NodeJS need updating to current 3.x and NodeJS 20+  #638: Ruby 3.2+ and Node.js 20+ upgrade (REQUIRED)
• ✅ Modern asset pipeline (jsbundling-rails or similar)

Technical Requirements

• Ruby 3.2+ (for gem compatibility)
• Rails 7+ (current: 7.0.8.7)
• PostgreSQL (current setup)
• Redis/Memcached (for settings caching)

Success Criteria

Functional Requirements

• Administrators can modify UI settings without restarts
• Bulk user operations (admin assignment, confirmation, etc.)
• Feature flags enable safe experimental feature deployment
• STIG/SRG bulk import and management capabilities
• All changes include audit logging

Performance Requirements

• Settings cached automatically (< 10ms retrieval)
• Admin interface responsive (< 2s page loads)
• Bulk operations process in background jobs
• Zero downtime for configuration changes

Security Requirements

• Admin interface requires authentication and authorization
• Security-critical settings remain environment variable based
• All administrative actions logged with user attribution
• Settings validation prevents invalid configurations

Timeline Estimate

Total Implementation: 8-12 hours over 2-3 sprints

Sprint 1 (Post-Webpacker Migration):

• Phase 1: Foundation (4-6 hours)

Sprint 2:

• Phase 2: User Management (2-3 hours)
• Phase 3: Feature Flags (1-2 hours)

Sprint 3:

• Phase 4: Bulk Operations (2-4 hours)
• Documentation and testing

Related Issues

• Addresses: Enterprise use case and Environmental variables #654 - Enterprise use case and Environmental variables
• Depends on: Heroku-20 Stack EOL + Webpacker Compatibility Blocking All Deployments #670 - Heroku-20 Stack EOL + Webpacker Compatibility
• Depends on: Ruby and NodeJS need updating to current 3.x and NodeJS 20+  #638 - Ruby and NodeJS need updating to current 3.x and NodeJS 20+
• Enhances: Recent OIDC auto-discovery work (PR OIDC Auto-Discovery Enhancement #672)

References

• rails-settings-cached gem
• ActiveAdmin documentation
• Flipper feature flags
• Enterprise Rails configuration patterns

---

Priority: Medium (after infrastructure upgrades)
Labels: enhancement, enterprise, administration, configuration
Estimated LOE: 8-12 hours across 2-3 sprints

[aaronlippold]

🔍 Integration Analysis: Current User Management System

After conducting a comprehensive analysis of Vulcan's existing user management, roles, and
permissions system, I can confirm that the proposed enterprise configuration management is
highly compatible and complementary to the current architecture.

Current System Architecture ✅

Existing User/Role/Permission System

Vulcan has a sophisticated two-tier authorization system:

1. Global Authorization:

• user.admin = true - Global admins with full system access
• Current admin interface at /users (Vue.js component)
• Basic user management: admin toggle, search, delete, audit history

2. Project/Component Authorization:

# Hierarchical role system (viewer → author → reviewer → admin)
PROJECT_MEMBER_ROLES = %w[viewer author reviewer admin].freeze

Polymorphic membership model

• Users can be members of Projects and/or Components
• Project permissions inherit to all components
• Component permissions can only be higher than project permissions
• Smart cleanup removes redundant permissions

Key Features Already Implemented

• ✅ Devise authentication with multiple providers (local, LDAP, OIDC)
• ✅ Membership model with polymorphic associations (Projects + Components)
• ✅ Permission inheritance from projects to components
• ✅ Access request system for project membership
• ✅ Audit trails using audited gem
• ✅ Email/Slack notifications for membership changes
• ✅ Authorization helpers (can_view_project?, can_admin_component?, etc.)

Integration Assessment: 🎯 ZERO CONFLICTS

Enterprise Enhancement Strategy: Additive, Not Replacement

What Stays Unchanged:

• ✅ All existing role hierarchy and permission logic
• ✅ Project/component membership management workflows
• ✅ Access request system and user-facing interfaces
• ✅ Authentication providers (local, LDAP, OIDC)
• ✅ Permission inheritance and validation rules

What Gets Enhanced:

• ✅ Bulk user operations (mass admin assignment, account confirmation)
• ✅ Advanced search and filtering beyond current basic search
• ✅ Runtime configuration management (welcome text, session timeouts)
• ✅ Feature flags for gradual rollouts
• ✅ Enhanced audit logging and reporting

ActiveAdmin Integration Strategy

  Parallel Enhancement Approach:
  # app/admin/users.rb - Enhances existing /users functionality
  ActiveAdmin.register User do
    # Respects existing authorization
    controller do
      before_action :ensure_admin
    end

    # Bulk operations (new capability)
    batch_action :assign_admin do |ids|
      batch_action_collection.find(ids).update_all(admin: true)
      # + audit logging + notifications
    end

    batch_action :confirm_accounts do |ids|
      # Bulk account confirmation with email notifications
    end

    # Enhanced filtering (beyond current search)
    filter :admin
    filter :provider
    filter :created_at
    filter :confirmed_at
  end

  # app/admin/memberships.rb - New bulk membership management
  ActiveAdmin.register Membership do
    # Bulk role changes across multiple projects
    # Advanced membership reporting and cleanup
    # Respects existing permission validation rules
  end

Database Schema Compatibility

Existing Tables (No Changes Required):

users # ✅ Perfect for ActiveAdmin enhancement
memberships # ✅ Ideal for bulk operations
project_access_requests # ✅ Enhanced workflow management

New Tables (Additive):
settings # ✅ Runtime configuration (rails-settings-cached)
flipper_features # ✅ Feature flags (Flipper gem)
flipper_gates # ✅ Feature flag rules

Authorization Integration

  Seamless Integration with Existing Authorization:
  # ActiveAdmin respects current admin system
  ActiveAdmin.setup do |config|
    config.authentication_method = :authenticate_admin_user!
    config.current_user_method = :current_admin_user
  end

  def authenticate_admin_user!
    redirect_to new_user_session_path unless current_user&.admin?
  end

  # Leverages existing global admin flag
  def current_admin_user
    current_user if current_user&.admin?
  end

Concrete Enhancement Examples

1. Enhanced User Management

  # Current: Individual operations
  user.update(admin: true)

  # Enhanced: Bulk operations with full audit trail
  User.where(id: selected_ids).each do |user|
    user.update(admin: true)
    UserMailer.admin_assigned(user).deliver_later
    send_slack_notification(:assign_vulcan_admin, user)
    # Full audit trail automatically captured
  end

2. Advanced Membership Operations

  # Current: One-by-one membership management in project UI
  # Enhanced: Cross-project bulk role management
  Membership.joins(:membership)
            .where(user: selected_users, membership: selected_projects)
            .update_all(role: 'reviewer')
  # + validation + notifications + audit trails

3. Runtime Configuration

  # Current: Environment variables + application restart
  ENV['VULCAN_WELCOME_TEXT'] = 'New welcome text'
  # Requires restart

  # Enhanced: Zero-restart configuration changes
  Setting.welcome_text = 'New welcome text'        # Immediate effect
  Setting.session_timeout_minutes = 120            # Immediate effect
  Setting.enable_user_registration = false         # Immediate effect
  # All changes logged with user attribution

Migration Strategy: Gradual Enhancement

Phase 1: Parallel Systems (Low Risk)

• Keep existing /users interface fully functional
• Add new /admin interface with enhanced capabilities
• Allow global admins to use either interface
• Zero impact on existing workflows

Phase 2: Enhanced Integration

• Add "Manage in Admin Panel" links from existing interfaces
• Gradually introduce bulk operations in existing workflows
• Maintain all existing user-facing interfaces

Phase 3: Optional Consolidation

• Can optionally retire old /users interface if desired
• Or maintain both for different admin preferences
• Full backward compatibility maintained

Security and Permission Boundaries

Clear Separation Maintained

Security-critical (Environment Variables - NO CHANGE):

• Database connections (DATABASE_URL)
• OIDC client secrets (VULCAN_OIDC_CLIENT_SECRET)
• Encryption keys and LDAP credentials

Administrative (Database-backed - NEW CAPABILITY):

• UI customizations and welcome text
• Session timeout settings (with validation limits)
• User registration and project creation permissions
• Feature flags for experimental features

Permission Validation Preserved

• ✅ All existing authorization helpers continue working
• ✅ Permission inheritance rules remain unchanged
• ✅ Membership validation logic preserved
• ✅ Access request workflows unmodified

Business Value Assessment

Enterprise Administration Capabilities Gained

• 🚀 Zero-restart configuration management
• 🚀 Bulk user operations (admin assignment, confirmation, etc.)
• 🚀 Advanced user search and filtering
• 🚀 Cross-project membership management
• 🚀 Feature flags for safe feature deployment
• 🚀 Enhanced audit trails and reporting
• 🚀 STIG/SRG bulk import operations

Risk Assessment: LOW

• ✅ No breaking changes to existing functionality
• ✅ Additive enhancements only
• ✅ Gradual migration possible
• ✅ Battle-tested gems (ActiveAdmin, rails-settings-cached, Flipper)
• ✅ Existing authorization patterns respected

Conclusion: 🎯 PROCEED WITH HIGH CONFIDENCE

The comprehensive analysis confirms that the proposed enterprise configuration management is
perfectly complementary to Vulcan's existing well-designed user/role/permission system:

✅ Zero architectural conflicts
✅ Preserves all existing functionality
✅ Enhances admin capabilities without disrupting user workflows
✅ Respects security boundaries between critical and administrative settings
✅ Builds on existing authorization patterns
✅ Enables gradual adoption with parallel interfaces

The integration will transform Vulcan into an enterprise-grade platform while maintaining the
robust foundation already built.