QuantaID

Next-Generation Unified Identity Authentication & Access Control Platform

简体中文 | Getting Started | Development Setup | Architecture | Contributing

---

🎯 Mission Statement

QuantaID revolutionizes enterprise identity management by providing a lightweight, plugin-based, and standards-compliant unified authentication platform. It addresses the critical pain points of fragmented identity systems, high customization costs, and complex integration challenges across diverse enterprise environments.

✨ Getting Started: 5-Minute Tutorial

Get a feel for QuantaID by running the server and interacting with the API.

1. Run the Server

First, clone the repository and install the dependencies:

git clone https://github.com/turtacn/QuantaID.git
cd QuantaID
go mod download

Now, run the server. No database or other dependencies are needed; it will start with an in-memory store by default.

go run ./cmd/qid-server/

You should see a log message indicating the server has started on port 8080.

2. Create a User

Open a new terminal. We'll use curl to interact with the API. Let's create a new user:

curl -X POST http://localhost:8080/api/v1/users \
-H "Content-Type: application/json" \
-d '{
  "username": "testuser",
  "email": "test@example.com",
  "password": "password123"
}'

You should receive a JSON response with the details of the created user.

3. Log In

Now, log in with the user you just created to get an access token:

curl -X POST http://localhost:8080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
  "username": "testuser",
  "password": "password123"
}'

The response will contain an accessToken. Copy it for the next step.

4. Access a Protected Route

Finally, use the access token to access a protected endpoint, like retrieving the user's own details. Replace YOUR_TOKEN_HERE with the token you copied.

# First, get the user ID from the login response. Let's assume it's "user-123" for this example.
# Then, make the authenticated request:
USER_ID="user-123" # Replace with the actual ID from the previous step
TOKEN="YOUR_TOKEN_HERE"

curl http://localhost:8080/api/v1/users/$USER_ID \
-H "Authorization: Bearer $TOKEN"

You've successfully started the server, created a user, logged in, and used a token for an authenticated API call.

🛠️ Development Setup

QuantaID is designed to be easy to set up for development.

Prerequisites

• Go 1.21 or higher
• Docker (optional, for containerized deployment)
• PostgreSQL 12+ (optional, for production-like deployment)

Running for Development

The server is configured to use an in-memory database by default, so you can run it without any external dependencies.

1. Clone the repository:

   git clone https://github.com/turtacn/QuantaID.git
   cd QuantaID

2. Install dependencies:

   go mod download

3. Run the server:

   go run ./cmd/qid-server/

   The server will start on http://localhost:8080.

4. Run tests:

   go test ./...

🏗️ Project Structure

The project follows the standard Go project layout. All custom source code is in the cmd, internal, and pkg directories.

QuantaID/
├── cmd/               # Command-line applications
│   ├── qid/           # Main CLI tool for managing the server.
│   └── qid-server/    # The server daemon itself.
├── pkg/               # Public Go packages, intended for use by external applications.
│   ├── client/        # A Go client SDK for interacting with the QuantaID API.
│   ├── types/         # Core type definitions (structs, constants) used across the project.
│   ├── auth/          # The core authentication engine logic.
│   └── plugins/       # The plugin framework, including interfaces and base implementations.
├── internal/          # Private application code, not intended for external use.
│   ├── domain/        # Core business logic and entities, decoupled from frameworks.
│   ├── orchestrator/  # A workflow engine for multi-step processes like authentication flows.
│   ├── server/        # HTTP server setup, handlers, and middleware.
│   ├── services/      # Application services that act as a facade over the domain layer.
│   └── storage/       # Data persistence implementations (e.g., PostgreSQL, Redis, in-memory).
├── deployments/       # Deployment configurations (e.g., Docker, Kubernetes).
└── docs/              # Project documentation.

📊 Architecture Overview

QuantaID is built on a clean, layered architecture that separates concerns and promotes modularity.

graph TB
    subgraph CL[Client Layer]
        WEB[Web UI]
        CLI[CLI Tools]
        SDK[Multi-Language SDKs]
    end
    
    subgraph AL[API Gateway Layer]
        GW[API Gateway]
        AUTH[Auth Middleware]
        RATE[Rate Limiter]
    end
    
    subgraph SL[Service Layer]
        ORE[Orchestration Engine]
        AUE[Authentication Engine]
        AZE[Authorization Engine]
        IMS[Identity Management]
        FED[Federation Service]
    end
    
    subgraph PL[Plugin Layer]
        IDP[Identity Providers]
        MFA[MFA Providers]
        CON[Custom Connectors]
    end
    
    subgraph DL[Data Layer]
        PG[(PostgreSQL)]
        RD[(Redis Cache)]
        ES[(Elasticsearch)]
    end
    
    CL --> AL
    AL --> SL
    SL --> PL
    SL --> DL

Loading

Detailed architecture documentation available at docs/architecture.md.

🤝 Contributing

We welcome contributions from the community! Please read our Contributing Guide to get started.

Contribution Areas

• 🔌 Plugin Development: Create connectors for new identity providers.
• 🌐 Internationalization: Add support for new languages.
• 📚 Documentation: Improve guides and API documentation.
• 🐛 Bug Reports: Help us identify and fix issues.
• ✨ Feature Requests: Propose new capabilities.

📄 License

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