Evrmore Authentication Troubleshooting Guide¶

This guide provides tools and techniques for troubleshooting the Evrmore Authentication system, with a focus on the OAuth 2.0 implementation.

Debugging Tools¶

The Evrmore Authentication CLI includes several useful debugging tools that can help diagnose issues with the system.

Database Monitoring¶

Database Summary¶

Check the contents of the SQLite database:

evrmore-authentication check-db

It displays a summary of: - Authorization Codes - OAuth Clients

OAuth Authorization Codes¶

Monitor OAuth authorization codes in the database in real-time:

evrmore-authentication check-auth-codes

It shows detailed information about each authorization code, including: - Code value - Client ID - User ID - Redirect URI - Scope - Creation and expiration timestamps - Used status

This tool is particularly useful for debugging the OAuth authorization code flow, as you can see the codes being created and used in real-time.

OAuth Clients¶

View all registered OAuth clients in the database:

evrmore-authentication check-oauth-clients

It displays a list of all registered OAuth clients, including: - Client ID - Client Secret - Name - Redirect URIs - Active status

Register OAuth Client¶

Register a new OAuth client with the system:

evrmore-authentication register-oauth-client --name "My App" --redirect-uris "http://localhost:3000/callback"

Optional parameters: - --client-uri: Client website URI - --scopes: Allowed OAuth scopes (default: profile) - --response-types: Allowed OAuth response types (default: code)

Log Monitoring¶

Monitor the authentication server logs in real-time:

evrmore-authentication monitor-logs

It tails the auth_server.log file and displays new log entries as they are added. This is useful for seeing detailed information about the authentication process, including debug messages and errors.

System Management¶

Installation and Uninstallation¶

Install the Evrmore Authentication system:

# Interactive installer (default)
evrmore-authentication install

# Non-interactive installation
evrmore-authentication install --no-interactive

# Basic installation (includes systemd service by default)
evrmore-authentication install --no-interactive

# Install without systemd service
evrmore-authentication install --no-systemd

# Custom installation options
evrmore-authentication install --host 127.0.0.1 --port 8001

Uninstall the Evrmore Authentication system:

# Interactive uninstaller (default)
evrmore-authentication uninstall

# Non-interactive uninstallation
evrmore-authentication uninstall --no-interactive

# Remove just the systemd service
evrmore-authentication uninstall --no-interactive

# Remove systemd service and database
evrmore-authentication uninstall --remove-db

Server Management¶

# Start the server (manual mode)
evrmore-authentication start

# Start the server in background (daemon mode)
evrmore-authentication start --daemon

# Start with custom host/port
evrmore-authentication start --host 127.0.0.1 --port 8001

# Stop the server
evrmore-authentication stop

# Restart the server
evrmore-authentication restart

# Check server status
evrmore-authentication status

If you've installed the systemd service, these commands will automatically use systemd to manage the service. Otherwise, they will handle the server process directly.

Common Issues and Solutions¶

Database Issues¶

Missing Tables: If you see errors about missing tables, initialize the database:
```
evrmore-authentication db-init
```
Database Path Mismatch: Ensure your .env file has the correct path:
```
SQLITE_DB_PATH=./evrmore_authentication/data/evrmore_auth.db
```
SQLite Permissions: If you get permission errors, check file permissions on the database file and directory.

OAuth Issues¶

See the OAuth 2.0 Implementation Guide for detailed troubleshooting of OAuth-specific issues.

Signature Verification Issues¶

Incorrect Signature Format: Ensure signatures are in the correct format expected by the system.
Challenge Expiry: Challenges expire after a set time (default: 15 minutes). If a challenge has expired, a new one must be generated.

Parameter Order: If you've customized the signature verification code, ensure parameters are passed in the correct order:

# Correct:
verify_message(address, message, signature)

# Incorrect:
verify_message(message, address, signature)

Server Issues¶

Server Won't Start: Check that the port is not already in use:

# Check if port 8001 is in use
lsof -i :8001

# Kill the process using the port
pkill -f "evrmore-authentication run-server"

CORS Errors: If you're getting CORS errors in the browser, check the CORS configuration in the API server.
Process Already Terminated: During uninstallation, you might see a message that a process is "no longer running" before killing it. This is normal when stopping via systemd first, as systemd will terminate the processes before the manual process check runs.

Systemd Service Issues¶

Permission Denied: If you see permission errors when trying to install or manage the systemd service, make sure you have sudo privileges:
```
# Check current user's sudo privileges
sudo -v
```
Service Not Starting: Check the systemd logs for more details:
```
sudo journalctl -u evrmore-authentication.service
```

Manual Management: If the systemd commands fail, you can manage the service manually:

sudo systemctl start evrmore-authentication.service
sudo systemctl stop evrmore-authentication.service
sudo systemctl restart evrmore-authentication.service
sudo systemctl status evrmore-authentication.service

Running Tests¶

The test suite can help diagnose issues:

# Run all tests
evrmore-authentication test

# Run specific tests
evrmore-authentication test evrmore_authentication/tests/unit/test_auth.py

# Run tests with verbose output
evrmore-authentication test -v

Getting Help¶

If you encounter persistent issues:

Check the GitHub Issues for similar problems and solutions.
Enable debug mode in your .env file to get more detailed logs:
```
DEBUG_MODE=True
LOG_LEVEL=DEBUG
```
Contact support:
Email: dev@manticore.technology
GitHub: https://github.com/manticoretechnologies