RoXX (v1.1.4)

RADIUS authentication integration with an admin portal, multi-factor authentication, and enterprise identity provider support.

RoXX does not listen for RADIUS packets on UDP 1812 by itself. Deploy FreeRADIUS with the documented rlm_python3 integration for RADIUS clients; roxx server runs the administration web service.

Website: https://tsautier.github.io/RoXX/ - overview, downloads, and operator guide.

---

🚀 Features

Core Functionality

• RADIUS Integration: FreeRADIUS module and configurable upstream authentication backends
• NPS Migration Assistant: Import tools for effortless transition from Microsoft NPS
• Multi-Backend Support: LDAP, Active Directory, SAML 2.0 SSO, Entra ID
• Admin Portal: Modern web interface with real-time analytics
• RESTful API: Complete API for automation and integration

Security & Authentication

• ✅ Multi-Factor Authentication (MFA)
  • TOTP/Authenticator Apps
  • WebAuthn (Security Keys, Biometrics)
  • TrustBuilder/inWebo Push Integration
  • SMS (via gateway integration)
• ✅ SAML 2.0 Single Sign-On
• ✅ LDAP/Active Directory / Entra ID Integration

Management & Monitoring

• Visual Dashboard: Real-time authentication charts and health monitoring
• Advanced Visibility: Live log viewer with color-coded event tracking
• User Management: Create, edit, delete admin users
• Audit Logs: Complete system activity tracking
• RBAC: superadmin, admin, and auditor roles for portal access control

---

📋 Requirements

• Python: 3.12 or higher
• Operating System: Linux, Windows 10/11, or Windows Server 2022/2025
• Database: SQLite (included)
• Optional:
  • LDAP/AD server for directory integration
  • SAML IdP for SSO
  • SMS gateway for SMS MFA

---

🔧 Installation

1. Clone and Setup

git clone https://github.com/tsautier/RoXX.git
cd RoXX

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install .

2. Bootstrap And Start

sudo ROXX_CONFIG_DIR=/etc/roxx ROXX_DATA_DIR=/var/lib/roxx ROXX_LOG_DIR=/var/log/roxx \
  roxx setup --non-interactive --hostname roxx.example.com
roxx server

The server uses HTTPS by default and listens on port 8000. Setup creates the initial superadmin with a unique generated password in /etc/roxx/initial-admin-credentials.txt (or the configured ROXX_CONFIG_DIR). The file is restricted to the service account where the platform supports POSIX permissions and is deleted after the password is changed.

For unattended secret injection, set ROXX_BOOTSTRAP_ADMIN_PASSWORD only while running setup. The supplied password must satisfy the local password policy and is never written to the credential file.

3. Configuration

Configuration files are located in:

• Linux: /etc/roxx/
• Development: ~/.roxx/

Key files:

• roxx.db - Main SQLite database
• webauthn.db - WebAuthn credentials
• mfa.db - MFA configuration

---

🎯 Quick Start

Access the Admin Portal

1. Read the generated initial credential file as the service account.
2. Navigate to https://localhost:8000.
3. Sign in and complete the mandatory password change.

Understand Roles

RoXX uses three admin roles:

• superadmin
• admin
• auditor

See docs/RBAC.md for the complete permission matrix and role-management rules.

Configure MFA

1. Go to Settings → MFA Settings
2. Choose your method:
   • TOTP: Scan QR code with authenticator app
   • WebAuthn: Register security key or biometric device
3. Complete setup and test login

Add an Identity Provider

SAML 2.0

1. Go to Config → Authentication Providers
2. Click + Add Provider
3. Select SAML 2.0
4. Fill in:
   • Name: e.g., "Corporate SSO"
   • IdP Entity ID: Your IdP's entity ID
   • IdP SSO URL: Your IdP's SSO endpoint
   • IdP Certificate: x509 certificate from IdP metadata
5. Configure your IdP with:
   • Metadata URL: https://your-domain.com/auth/saml/metadata/{provider_id}
   • ACS URL: https://your-domain.com/auth/saml/acs/{provider_id}

LDAP / Active Directory

1. Go to Config → Authentication Providers
2. Click + Add Provider
3. Select LDAP / Active Directory
4. Configure:
   • Server URL: ldap://dc.example.com:389
   • Base DN: dc=example,dc=com
   • Bind DN: Service account DN
   • Bind Password: Service account password

---

📚 API Documentation

Authentication

All API requests require authentication via session cookie or API token.

Endpoints

User Management

GET    /api/admins              - List all admin users
POST   /api/admins              - Create new admin user
GET    /api/admins/{username}   - Get user details
PUT    /api/admins/{username}/role - Change user role
DELETE /api/admins/{username}   - Delete user

MFA Management

GET    /api/admins/{username}/mfa/status       - Get MFA status
GET    /api/admins/{username}/mfa/credentials  - List WebAuthn credentials
DELETE /api/admins/{username}/mfa/webauthn/{id} - Delete security key
POST   /api/admins/{username}/mfa/totp/reset   - Reset TOTP

Authentication Providers

GET    /api/auth-providers     - List providers
POST   /api/auth-providers     - Create provider
DELETE /api/auth-providers/{id} - Delete provider

Example: Create Admin User

curl --insecure -X POST https://localhost:8000/api/admins \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john",
    "password": "SecurePass123!",
    "email": "john@example.com"
  }'

---

🔐 Security Best Practices

1. Protect Bootstrap Credentials: Read the generated credential file only from a trusted console and complete the mandatory password rotation
2. Enable MFA: Require MFA for all admin users
3. Use HTTPS: Deploy with proper SSL/TLS certificates
4. Regular Updates: Keep dependencies up to date
5. Audit Logs: Regularly review system audit logs
6. API Tokens: Use API tokens instead of passwords for automation
7. Network Security: Restrict admin portal access to trusted networks

---

🛠️ Configuration

Environment Variables

# Application
ROXX_HOST=0.0.0.0
ROXX_PORT=8000
ROXX_DEBUG=false

# Database
ROXX_DB_PATH=/etc/roxx/roxx.db

# Security
ROXX_SECRET_KEY=your-secret-key-here
ROXX_SESSION_TIMEOUT=3600
ROXX_SECURITY_PROFILE=production
ROXX_SECURE_COOKIES=true
ROXX_HSTS=true
ROXX_ALLOWED_ORIGINS=https://your-domain.com
ROXX_METRICS_TOKEN=your-monitoring-token

# SAML
ROXX_SAML_SP_ENTITY_ID=https://your-domain.com

SSL/TLS Configuration

Place certificates in /etc/roxx/ssl/:

• cert.pem - SSL certificate
• key.pem - Private key

The application will automatically use HTTPS if certificates are present.

---

📊 Monitoring

System Health

Access the dashboard at /dashboard for:

• CPU utilization
• Memory usage
• Disk space
• Active sessions
• Recent authentication events

Service endpoints:

• GET /livez for liveness.
• GET /readyz for local storage, database, and optional dependency readiness.
• GET /metrics for Prometheus metrics; set ROXX_METRICS_TOKEN to protect it.
• roxx audit export --output audit.jsonl for SIEM-compatible JSON Lines export.

Audit Logs

View comprehensive logs at /logs:

• User logins
• MFA events
• Configuration changes
• API requests
• SAML/LDAP authentication attempts

---

🐛 Troubleshooting

Common Issues

WebAuthn Not Working

• Ensure using HTTPS or localhost
• Check browser compatibility (Chrome/Edge/Firefox/Safari recommended)
• Verify WebAuthn credentials in browser dev tools

SAML Login Fails

• Verify IdP certificate is correct
• Check SP Entity ID matches IdP configuration
• Review logs at /config/auth-providers/logs
• Ensure SP metadata uploaded to IdP

LDAP Connection Issues

• Verify network connectivity to LDAP server
• Check bind DN and password
• Test with ldapsearch command
• Review firewall rules

Debug Mode

Enable debug logging:

export ROXX_DEBUG=true
roxx server

---

📖 Documentation

• Production operations, HA, upgrade and rollback: See docs/OPERATIONS.md
• Deployment: See docs/DEPLOYMENT_GUIDE.md
• SAML Setup: See docs/saml-setup.md
• RBAC: See docs/RBAC.md

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 License

📄 License

This project is licensed under the GNU Affero General Public License (AGPLv3) - see the LICENSE file for details.

This license requires that users who interact with the software over a network must have access to the source code of the exact version they are using, including any modifications.

---

🙏 Acknowledgments

• FastAPI - Modern web framework
• python3-saml - SAML implementation
• python-ldap - LDAP integration
• webauthn - WebAuthn/FIDO2 support

---

📞 Support

For issues and questions:

• GitHub Issues: https://github.com/tsautier/RoXX/issues

---

Built with ❤️ for secure, scalable authentication