Troubleshooting Guide

Common issues and solutions for CAS authentication system

Quick Issue Navigation

Authentication Issues Database Connection Problems SSL/Certificate Issues Performance Problems Logging and Debugging System Recovery

Emergency Actions

System Down

Check server status and restart services

Database Issues

Verify database connection and credentials

Login Failures

Check authentication logs and user accounts

Authentication Issues

Users Cannot Login

Symptoms:

  • Login form shows "Invalid credentials" error
  • reCAPTCHA validation failures
  • Account lockout messages
  • 2FA verification issues

Solutions:

# Check user account status
php artisan cas:check-user [email protected]

# Reset account lockout
php artisan cas:unlock-user [email protected]

# Check authentication logs
tail -f storage/logs/laravel.log | grep "login"

# Test database connection
php artisan cas:test-db

SSO Token Issues

Common Problems:

  • JWT token validation failures
  • HMAC signature mismatches
  • Token expiration issues
  • Client system authentication errors

Debug Commands:

# Validate JWT token
php artisan cas:validate-token "your-jwt-token-here"

# Check client system credentials
php artisan cas:test-client client-system-id

# Regenerate client secrets
php artisan cas:regenerate-secrets client-system-id

# Check HMAC signature validation
php artisan cas:verify-signature payload signature

Database Connection Problems

Connection Failures

Check Database Status:

# Test database connection
php artisan cas:db-status

# Check PostgreSQL service
sudo systemctl status postgresql

# Verify database credentials
psql -h $PGHOST -U $PGUSER -d $PGDATABASE -c "SELECT version();"

# Check connection pool
php artisan cas:connection-pool

Common Issues:

SSL Connection Issues

Update .env file:

DB_SSLMODE=require
Schema Not Found

Run migrations:

php artisan migrate

Migration and Schema Issues 

# Check migration status
php artisan migrate:status

# Reset and rebuild database
php artisan migrate:fresh --seed

# Repair specific table
php artisan cas:repair-table table_name

# Check schema integrity
php artisan cas:check-schema

SSL/Certificate Issues

Certificate Problems

Check Certificate Status:

# Check certificate expiration
openssl x509 -in /path/to/certificate.crt -text -noout | grep "Not After"

# Test SSL connection
openssl s_client -connect cas.yourdomain.com:443 -servername cas.yourdomain.com

# Verify certificate chain
openssl verify -CAfile /path/to/ca-bundle.crt /path/to/certificate.crt

# Renew Let's Encrypt certificate
certbot renew --dry-run

Common SSL Errors

  • ERR_CERT_AUTHORITY_INVALID: Untrusted certificate authority
  • ERR_CERT_DATE_INVALID: Certificate expired or not yet valid
  • ERR_SSL_PROTOCOL_ERROR: SSL/TLS protocol mismatch
  • ERR_CERT_COMMON_NAME_INVALID: Domain mismatch in certificate

Performance Problems

Slow Response Times

Performance Monitoring:

# Check application performance
php artisan cas:performance-check

# Monitor database queries
php artisan cas:query-monitor

# Check Redis cache status
redis-cli info stats

# Monitor server resources
htop
free -h
df -h
Cache Optimization
# Clear all caches
php artisan optimize:clear

# Rebuild caches
php artisan optimize
Database Optimization
# Analyze slow queries
php artisan cas:slow-queries

# Optimize database
php artisan cas:optimize-db

Logging and Debugging

Log File Locations

Application Logs

  • Laravel: storage/logs/laravel.log
  • Authentication: storage/logs/auth.log
  • SSO Events: storage/logs/sso.log
  • Audit Trail: storage/logs/audit.log

System Logs

  • Nginx: /var/log/nginx/
  • PostgreSQL: /var/log/postgresql/
  • System: /var/log/syslog
  • Security: /var/log/auth.log

Debug Commands:

# Enable debug mode (development only)
php artisan cas:debug on

# Monitor logs in real-time
tail -f storage/logs/laravel.log

# Search for specific errors
grep -n "ERROR" storage/logs/laravel.log | tail -20

# Check log file sizes
du -sh storage/logs/

# Rotate log files
php artisan cas:rotate-logs

System Recovery

Recovery Procedures

Complete System Failure 

# Emergency recovery steps
1. sudo systemctl restart nginx
2. sudo systemctl restart postgresql
3. sudo systemctl restart redis
4. php artisan queue:restart
5. php artisan cas:health-check

Database Recovery 

# Restore from backup
pg_restore -h $PGHOST -U $PGUSER -d $PGDATABASE backup_file.sql

# Verify data integrity
php artisan cas:verify-data

# Rebuild indexes
php artisan cas:rebuild-indexes

Security Incident Response

  • Immediately change all admin passwords
  • Regenerate all JWT secrets and client credentials
  • Review audit logs for suspicious activity
  • Update IP whitelist to block threats
  • Force logout of all active sessions

Additional Support

Documentation

Complete guides and API reference

Browse Docs

Code Examples

Integration examples and samples

View Examples

System Status

Check system health and status

Health Check