Guardian is a robust, open-source authentication and authorization solution designed for modern applications. It provides a comprehensive suite of authentication methods (passwordless, username/password, social login) with full OAuth 2.0 and OpenID Connect support, while giving you complete control over your user data.

• 🔐 Enterprise-Grade Security: Built with security best practices

• 🎯 Flexible Integration: Works seamlessly with your existing user service

• 🏢 Multi-Tenant Ready: Supports multiple tenants with logical isolation

• 🚀 Quick Implementation: Get up and running in minutes

• 📱 Multi-Platform Support: Native support for web, mobile, and API authentication

• 🔑 OAuth 2.0 & OIDC: Full OAuth 2.0 and OIDC protocol support, secured with PKCE and discovery endpoints

• ⚡ High Performance: Built on Vert.x for reactive, non-blocking I/O

• Features
• Getting Started
• Configuration
• API Reference
• Deployment
• Contributing
• Community
• License

• 📱 Passwordless Authentication

• 🔑 Username Password Authentication

• 🌐 Social Authentication

• 👤 Guest Login (coming soon)

• 📲 Multi Factor Authentication (coming soon)

• 📊 Multi-device session tracking

• 🔒 Secure session management

• ⚡ Real-time session invalidation

• 🔄 Token refresh mechanisms

• 🚪 Universal Logout

• 🔐 Full OAuth 2.0 implementation (Authorization Code, Implicit, Client Credentials)

• ✅ OpenID Connect 1.0 compliant (Discovery, UserInfo, JWKS endpoints)

• 🛡️ PKCE support for enhanced security

• 📝 Consent Management(coming soon)

• 📈 Scalable design for serving multiple tenants

• ⚙️ Tenant-level configuration

• Docker ≥ 20.10 (Download Docker Desktop)

• Docker Compose ≥ 2.0 (Usually included with Docker Desktop)(Install instructions)

• Maven ≥ 3.6 (Download Maven)

• Java 17 (JDK) (Download Java 17)

You can verify the installations by running the following commands in your terminal:

docker --version
mvn --version
java -version

Important: Ensure that Java 17 is the active version in use. Maven should also be configured to use Java 17 - you can verify this by checking that mvn --version shows Java 17 in its output.

Make sure the following ports are free and not in use by other services:

• 3306 – MySQL database
• 6379 – Redis cache
• 8080 – Guardian application server
• 6000 – Mock user/communication service (for development)

If any of these ports are in use, you'll need to stop the conflicting services or modify the port mappings in docker-compose.yaml.

1. Clone the repository:

git clone https://github.com/dream-horizon-org/guardian.git
cd guardian

2. Start Guardian:

./quick-start.sh

This script will:

• Build the Guardian application using Maven
• Start all required services (MySQL, Redis, Guardian, and mock services) using Docker Compose
• Run database migrations and seed initial data

3. Test the setup with passwordless flow:

The seed data includes a pre-configured tenant (tenant1) and client (client1) for testing.

Initialize passwordless authentication:

curl --location 'localhost:8080/v2/passwordless/init' \
--header 'tenant-id: tenant1' \
--header 'Content-Type: application/json' \
--data '{
    "contacts": [
        {
            "channel": "SMS",
            "identifier": "7878787878"
        }
    ],
    "flow": "SIGNINUP",
    "response_type": "token",
    "client_id": "client1"
}'

Expected response: You'll receive a JSON response containing a state field. Copy this value for the next step.

Complete authentication (using mock OTP for development):

curl --location 'localhost:8080/v2/passwordless/complete' \
--header 'tenant-id: tenant1' \
--header 'Content-Type: application/json' \
--data '{
    "state": "<paste-state-from-init-response-here>",
    "otp": "999999"
}'

Follow our comprehensive guide on website to set up Guardian in minutes.

For the complete configuration reference and detailed setup instructions, see the Configuration Guide.

The complete API specification including all endpoints, request/response schemas, and examples can be found in the Guardian OpenAPI Specification.

For information about the endpoints that your services need to implement to integrate with Guardian, refer to the Integration Endpoints Specification.

Guardian can be deployed using Docker Compose for development or containerized / virtual machine for production environments.

For detailed deployment instructions, production best practices, and infrastructure setup, see the Deployment Guide.

We welcome contributions! Please see our Contributing Guide for details on:

• Code of Conduct

• Development Process

• Pull Request Process

• Coding Standards

• Testing Guidelines

• 💬 GitHub Discussions - Ask questions and share ideas

• 🐛 Issue Tracker - Report bugs and request features

• 📖 Documentation - Comprehensive guides

Guardian is licensed under the MIT License.

Built with ❤️ by the Guardian team and contributors