A modern, secure, and scalable authentication service built with Ruby on Rails

EvoAuth Service is a comprehensive authentication and authorization solution designed for modern applications. It provides OAuth 2.0, Multi-Factor Authentication (MFA), Role-Based Access Control (RBAC), and GDPR compliance out of the box.

• Bearer Token Authentication with standard JWT tokens
• Legacy DeviseTokenAuth Support for backward compatibility
• OAuth 2.0 Provider with Doorkeeper (RFC 6749)
• Multi-Factor Authentication (TOTP, Email OTP, Backup Codes)
• Role-Based Access Control (RBAC) with granular permissions
• Account Isolation for multi-tenant applications

• GDPR/LGPD Compliance with data privacy controls
• Comprehensive Audit Logging for all user actions
• Database-driven Feature Flags for controlled rollouts
• Secure Session Management with token rotation
• Well-Known Discovery endpoints (RFC 8414)

• RESTful API with 200+ documented endpoints
• OpenAPI/Swagger Documentation for easy integration
• Webhook Support for real-time notifications
• Multi-language Support (EN, PT-BR)
• Account-scoped Operations for data isolation

• Structured Audit Trails with detailed event tracking
• Health Check Endpoints for monitoring
• Request ID Tracking for debugging
• Performance Metrics ready for APM integration

• Ruby 3.4.4+
• Rails 7.1+
• PostgreSQL 12+
• Redis 6+

1. Clone the repository

   git clone https://github.com/EvolutionAPI/evo-auth-service.git
   cd evo-auth-service

2. Install dependencies

   bundle install

3. Setup database

   rails db:create
   rails db:migrate
   rails db:seed

4. Start the server

   rails server -p 3001

5. Access the API documentation

   http://localhost:3001/api-docs
   

After running rails db:seed, you can use these default credentials:

Email: [email protected]
Password: password123

Visit http://localhost:3001/api-docs for interactive Swagger UI documentation.

EvoAuth Service supports multiple authentication methods:

# Login and get Bearer token
curl -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "password"}'

# Use Bearer token for API requests
curl -X GET http://localhost:3001/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl -X POST http://localhost:3001/auth/sign_in \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "password"}'

curl -X GET http://localhost:3001/api/v1/users \
  -H "api_access_token: YOUR_API_TOKEN"

curl -X GET http://localhost:3001/api/v1/users \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"

Create a .env file in the root directory:

# Database
DATABASE_URL=postgresql://username:password@localhost:5432/evo_auth_service_development

# Redis
REDIS_URL=redis://localhost:6379/1

# JWT Secret
DEVISE_JWT_SECRET_KEY=your_super_secret_jwt_key_here

# OAuth
DOORKEEPER_SECRET_KEY=your_doorkeeper_secret_key_here

# Frontend URL (for CORS and OAuth callbacks)
FRONTEND_URL=http://localhost:3000

# Email (for MFA and notifications)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your_app_password

# Optional: Enable account signup
ENABLE_ACCOUNT_SIGNUP=true

# Optional: Super Admin email
SUPER_ADMIN_EMAIL=[email protected]

EvoAuth Service uses database-driven feature flags. Manage them via:

# Enable a feature for an account
account.enable_feature!('advanced_mfa')

# Check if feature is enabled
account.feature_enabled?('advanced_mfa')

# Available features
Feature.available_features

EvoAuth Service is built with multi-tenancy in mind:

• Resource Separation: Each account has isolated users, roles, and OAuth applications
• Feature Flags: Features can be enabled/disabled per account
• Audit Trails: All actions are logged with account context

Key models and relationships:

Account (1) ──── (N) AccountUser (N) ──── (1) User
   │                                         │
   │                                         ├── UserRole ──── Role ──── Permission
   │                                         │
   └── OauthApplication                      ├── DataPrivacyConsent
                                            │
                                            └── AuditLog

• JWT Tokens: Stateless authentication with configurable expiration
• OAuth 2.0: Industry-standard authorization with PKCE support
• MFA: TOTP (Google Authenticator) and Email OTP
• RBAC: Granular permissions with role inheritance
• Audit Logging: Comprehensive activity tracking

Run the test suite:

# Run all tests
bundle exec rspec

# Run with coverage
COVERAGE=true bundle exec rspec

# Run specific test file
bundle exec rspec spec/models/user_spec.rb

# Run tests matching pattern
bundle exec rspec spec/requests/api/v1/auth_spec.rb

Current test coverage: 95%+

• Unit tests for all models
• Integration tests for API endpoints
• Authentication and authorization tests
• MFA workflow tests
• RBAC permission tests

Please report security vulnerabilities to [email protected]. See SECURITY.md for details.

• Input Validation: All inputs are validated and sanitized
• SQL Injection Protection: Using ActiveRecord ORM
• XSS Protection: Content Security Policy headers
• CSRF Protection: Rails built-in CSRF protection
• Rate Limiting: Configurable rate limits per endpoint
• Secure Headers: Security headers for all responses

EvoAuth Service supports multiple languages:

• English (en) - Default
• Portuguese Brazil (pt-BR)
• Spanish (es) - Planned

Add new translations in config/locales/:

# config/locales/pt-BR.yml
pt-BR:
  auth:
    login_success: "Login realizado com sucesso"
    invalid_credentials: "Credenciais inválidas"

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Ensure tests pass: bundle exec rspec
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

We use RuboCop for code style enforcement:

# Check code style
bundle exec rubocop

# Auto-fix issues
bundle exec rubocop -a

• SSO integrations (SAML, LDAP)
• Advanced audit analytics
• Webhook system
• API rate limiting
• Performance optimizations

• Mobile SDK support
• Advanced MFA options (WebAuthn)
• Custom branding support
• Plugin architecture
• GraphQL API

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

• DeviseTokenAuth for JWT authentication
• Doorkeeper for OAuth 2.0 provider
• ROTP for TOTP implementation
• RSwag for API documentation

• Complete Documentation Suite - All guides and references
• API Documentation - Interactive Swagger UI
• Integration Examples - React, Vue, Node.js, Python examples
• Migration Guide - Upgrade from legacy authentication

• GitHub Repository - Source code and releases
• Issues - Bug reports and feature requests
• Discussions - Community discussions and Q&A
• Releases - Latest versions and changelogs

• General: [email protected]
• Security: [email protected]
• Business: [email protected]

Built with ❤️ by the Evolution Team

Features • Quick Start • API Docs • Contributing • License