Lite.Auth

Lite.Auth is a lightweight, flexible authorization management platform. It provides authorization services only and does not handle authentication - user authentication should be managed by your existing account systems (e.g., corporate SSO, identity providers, or custom authentication).

Features

• Multi-tenant Architecture: Support multiple applications with isolated users, resources, and policies
• Flexible Policy Engine: Define fine-grained access control with conditions based on user attributes
• Dual API Support: REST API and gRPC for seamless integration
• Modern Tech Stack: Built with .NET 9, Next.js 16, PostgreSQL, and TypeScript
• Extensible Condition System: Support various operators (=, !=, has, in, >, <, startswith, endswith, etc.)
• OAuth2 Integration: Built-in GitHub OAuth support for admin dashboard authentication

Architecture

Core Concepts

Concept	Description
App	An application using Lite.Auth for authorization. Each app has its own API keys, users, resources, and policies.
AppUser	Users within an app. AppUsers have attributes (e.g., role, group, department) used for authorization decisions.
LiteAuthUser	Platform-level users for accessing the Lite.Auth management dashboard.
Resource	Protected resources within an app (APIs, pages, buttons, etc.).
Policy	Access control policies with Allow/Deny effects, composed of multiple conditions.
Condition	Attribute-based conditions within policies. Multiple conditions are evaluated with AND logic.
Rule	Specific rules within conditions (e.g., user has Admin role). Multiple rules are evaluated with OR logic.

Project Structure

src/
  Lite.Auth.Core/        # Core authorization middleware and policy evaluators
  Lite.Auth.Server/      # Management server (REST + gRPC APIs)
  Lite.Auth.Web/         # Next.js management dashboard
  Lite.Auth.GrpcClient/  # gRPC client library for downstream apps
  Protos/                # Protocol buffer definitions

sample/
  Lite.Auth.Sample/      # Example downstream application

tests/
  Lite.Auth.Core.Tests/        # Core library tests
  Lite.Auth.Server.Tests/      # Server tests
  Lite.Auth.GrpcClient.Tests/  # gRPC client tests

Prerequisites

• .NET 9.0 SDK
• Node.js 20+ (for the web dashboard)
• PostgreSQL 14+

Getting Started

1. Clone the Repository

git clone https://github.com/your-org/Lite.Auth.git
cd Lite.Auth

2. Set Up the Database

Create a PostgreSQL database:

createdb lite-auth

Update the connection string in src/Lite.Auth.Server/appsettings.json.

3. Run Database Migrations

cd src/Lite.Auth.Server
dotnet ef database update

4. Start the Server

cd src/Lite.Auth.Server
dotnet run

The server will start on:

• HTTP API: http://localhost:5177
• gRPC: http://localhost:5277

5. Start the Web Dashboard

cd src/Lite.Auth.Web
npm install
npm run dev

The dashboard will be available at http://localhost:3000.

Integration Guide

Using the gRPC Client

Add the Lite.Auth.GrpcClient package to your project and configure it:

services.AddLiteAuthClient(options =>
{
    options.ServerAddress = "http://localhost:5277";
    options.ApiKey = "sk_your_api_key";
});

Using the Authorization Middleware

Add the authorization middleware to your ASP.NET Core application:

// Register services
services.AddLiteAuthCore();

// Use middleware
app.UseLiteAuthResource();

Protect your endpoints with the AuthzResource attribute:

[AuthzResource("api:users:read")]
public async Task<IActionResult> GetUsers()
{
    // Your code here
}

Checking Permissions Programmatically

public class MyService
{
    private readonly IAuthService _authService;

    public MyService(IAuthService authService)
    {
        _authService = authService;
    }

    public async Task<bool> CanAccessResource(string userKey, string resource)
    {
        var attributes = await _authService.GetUserAttributeDict(appId, userKey);
        return await _authService.CheckResourcePermission(appId, resource, attributes);
    }
}

API Endpoints

REST API

Endpoint	Method	Description
/api/apps	GET/POST	Manage applications
/api/apps/{id}/users	GET/POST	Manage app users
/api/apps/{id}/resources	GET/POST	Manage resources
/api/apps/{id}/policies	GET/POST	Manage policies
/api/apps/{id}/keys	GET/POST	Manage API keys

gRPC Services

Service	Method	Description
LiteAuthGrpc	CheckPolicyPermission	Check if attributes satisfy a policy
LiteAuthGrpc	CheckResourcePermission	Check if user can access a resource
LiteAuthGrpc	GetAppUserResources	Get all accessible resources for a user
LiteAuthGrpc	GetUserAttributeDict	Get user attributes as key-value pairs
LiteAuthGrpc	GetUserRoles	Get user's assigned roles

Configuration

Server Configuration

The server is configured via appsettings.json:

{
  "ConnectionStrings": {
    "default": "Server=127.0.0.1;Port=5432;Database=lite-auth;User Id=postgres;Password=your_password;"
  },
  "OAuth2": {
    "Enabled": true,
    "DefaultProvider": "github",
    "Providers": {
      "github": {
        "ClientId": "your_client_id",
        "ClientSecret": "your_client_secret"
      }
    }
  }
}

Policy Configuration

Policies support various condition operators:

Operator	Example	Description
=	role = admin	Exact match
!=	role != guest	Not equal
has	roles has admin	Source contains value (comma-separated)
not has	roles not has banned	Source does not contain value
in	role in admin,superuser	Value is in list
not in	role not in guest,banned	Value is not in list
>, >=, <, <=	level > 5	Numeric comparison
startswith	email startswith admin@	String prefix match
endswith	email endswith @company.com	String suffix match

Development

Running Tests

dotnet test

Building for Production

# Build server
cd src/Lite.Auth.Server
dotnet publish -c Release

# Build web dashboard
cd src/Lite.Auth.Web
npm run build

Security Considerations

1. API Keys: Store API keys securely and rotate them regularly
2. Database Credentials: Use environment variables or secrets management for database passwords
3. OAuth2 Secrets: Never commit OAuth2 client secrets to version control
4. HTTPS: Always use HTTPS in production
5. CORS: Configure CORS appropriately for your deployment

License

[Add your license here]

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request