Skip to main content

Quick Start Guide

Get AuthProxy up and running in 5 minutes with Docker Compose. This guide sets up a minimal working environment for development and testing.

Prerequisites​

  • Docker and Docker Compose installed
  • Basic understanding of web authentication
  • Domain name or localhost for testing

5-Minute Setup​

Step 1: Create project structure​

mkdir -p myproject/configs
mkdir -p myproject/AuthProxy
mkdir -p myproject/storage/authproxy-files

Step 2: Create configuration​

Create myproject/configs/authproxy.json:

{
  "ServiceId": 10,
  "ServiceName": "AuthProxy",
  "ServerOrigin": "http://localhost:8001",
  "ProjectName": "AuthProxy Dev",
  "CoreApiKey": "dev-secret-key-change-in-production",
  "DBConnections": {
    "GateDB": "Data Source=/app/data/authproxy.db"
  },
  "FIDO2": {
    "serverDomain": "localhost",
    "serverName": "AuthProxy Dev",
    "origins": ["http://localhost:8001"]
  },
  "LocalFileStoragePath": "/var/lib/authproxy/files",
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

This uses SQLite — no external database needed — and preconfigures local disk storage for a mono-proxy deployment.

Attachment byte storage will go to /var/lib/authproxy/files inside the container.

Note: End-to-end file attachments still require the Chat module for file metadata and attachment lifecycle operations.

Step 3: Create docker-compose.yml​

Create myproject/docker-compose.yml:

services:
  authproxy:
    image: mcr.microsoft.com/dotnet/aspnet:10.0-alpine
    container_name: quickstart-authproxy
    ports:
      - "8001:80"
    volumes:
      - ./AuthProxy:/app
      - ./configs/authproxy.json:/app/appsettings.json
      - authproxy-data:/app/data
      - ./storage/authproxy-files:/var/lib/authproxy/files
    entrypoint: ["dotnet", "AuthProxy.dll"]
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:80/health"]
      interval: 30s
      timeout: 3s
      retries: 3

volumes:
  authproxy-data:

Step 4: Place binaries and start​

Copy the AuthProxy published binaries to myproject/AuthProxy/, then:

cd myproject
docker compose up -d

Step 5: Verify​

# Wait a few seconds for startup, then:
curl http://localhost:8001/auth/v1/get_info

Expected response:

{
  "result": {
    "project": "AuthProxy Dev",
    "version": "1.x.x",
    "utcNow": "2026-02-06T12:00:00Z"
  }
}

What You Can Do Now​

Admin Panel​

Open http://localhost:8001/ProxyAdmin in your browser to access the admin dashboard:

  • Users — view and manage user accounts
  • Route Map — configure reverse proxy routes to backend services
  • Settings — system configuration
  • Login Log — authentication activity

API Explorer (Swagger)​

Open http://localhost:8001/docs/swagger to explore the full API documentation interactively.

Test Authentication​

Register a passkey​

# 1. Get registration challenge
curl http://localhost:8001/auth/v1/register_options

# 2. Complete registration with WebAuthn (requires browser)
# Open the PWA frontend or use a WebAuthn testing tool

Test phone/email login (requires Chat module)​

# Send OTP to phone
curl -X POST http://localhost:8001/auth/v1/login_phone \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1234567890"}'

Note: Phone/email authentication requires the Chat module for SMS/email delivery. For standalone testing, use passkey or FIDO2 authentication.

Adding Backend Services​

To proxy requests to your backend, add routes via the admin panel or database:

  1. Open Route Map in the admin panel (/ProxyAdmin/RouteMap)
  2. Add a route:
    • Path: /api/v1/ (requests matching this prefix)
    • Service URL: http://core-service:80 (backend address)
    • Flags: Set authentication requirements

Or add the Core module to Docker Compose:

services:
  authproxy:
    # ... (existing config)
    networks:
      - myproject

  core:
    image: mcr.microsoft.com/dotnet/aspnet:10.0-alpine
    container_name: quickstart-core
    volumes:
      - ./Core:/app
      - ./configs/core.json:/app/appsettings.json
    entrypoint: ["dotnet", "Core.dll"]
    networks:
      - myproject

networks:
  myproject:
    driver: bridge

AuthProxy will route authenticated requests to the Core service based on the route map configuration.

Adding SQL Server (Production-Ready)​

Replace SQLite with SQL Server when you're ready for production. For development and small projects, SQL Server Express is free (10 GB limit):

services:
  sqlserver:
    # For production: mcr.microsoft.com/mssql/server:2022-latest
    # For development: mcr.microsoft.com/mssql/server:2022-latest (Express via MSSQL_PID=Express)
    image: mcr.microsoft.com/mssql/server:2022-latest
    container_name: quickstart-sql
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=Your_Strong_Password_123
    ports:
      - "1433:1433"
    volumes:
      - sql-data:/var/opt/mssql
    networks:
      - myproject

  authproxy:
    # ... (existing config, update connection string)
    depends_on:
      - sqlserver

volumes:
  sql-data:

Update authproxy.json:

{
  "DBConnections": {
    "GateDB": "Server=sqlserver;Database=authproxy_db;User Id=sa;Password=Your_Strong_Password_123;TrustServerCertificate=true;Encrypt=true;"
  }
}

Next Steps​