inumansoul/kotauth repository overview

⁠Kotauth

Kotauth is an open-source authentication and identity platform that bridges the gap between enterprise IAM systems (Keycloak, Okta) and developer-friendly SaaS tools (Clerk, Auth0). Full OAuth2/OIDC compliance. Runs in Docker. Up in minutes.

⁠Quickstart — pre-built image (fastest)

You need Docker and Docker Compose. Nothing else — no repo clone, no build step.

1. Grab the compose file and env template

mkdir kotauth && cd kotauth
curl https://raw.githubusercontent.com/inumansoul/kotauth/main/docker/docker-compose.yml
curl https://raw.githubusercontent.com/inumansoul/kotauth/main/.env.example
cp .env.example .env

2. Set your secret key and base URL

Open .env and fill in the two required values:

# In .env:
KAUTH_BASE_URL=http://localhost:8080
KAUTH_SECRET_KEY=$(openssl rand -hex 32)

3. Start

docker compose up -d

Kotauth starts on port 8080. PostgreSQL is bundled — no separate database setup. Flyway migrations run automatically on first boot.

4. Open the admin console

http://localhost:8080/admin

Default master workspace credentials are printed in the startup log on first run. Change them immediately.

5. Create a workspace

In the admin console, create a new workspace (e.g. my-app). This is your tenant — it gets its own users, OAuth clients, and signing keys. Your OIDC discovery document is then live at:

http://localhost:8080/t/my-app/.well-known/openid-configuration

⁠Architecture

Kotauth is built on hexagonal architecture⁠ (Ports & Adapters). The domain layer has zero framework dependencies — all I/O goes through typed port interfaces.

domain/
  model/      — Pure data classes (User, Tenant, Session, …)
  port/       — Interface contracts (TenantRepository, EmailPort, …)
  service/    — Business logic (AuthService, OAuthService, MfaService, …)

adapter/
  web/        — Ktor HTTP routes
  persistence/— PostgreSQL + Exposed ORM
  token/      — JWT signing, password hashing
  email/      — SMTP delivery
  social/     — Google / GitHub OAuth adapters

infrastructure/
              — Cross-cutting: key provisioning, rate limiting, encryption

Key decisions are documented as ADRs in docs/IMPLEMENTATION_STATUS.md⁠.

⁠Tech Stack

• Runtime: Kotlin, Ktor 2, JVM 17
• Database: PostgreSQL 15, Exposed ORM, Flyway migrations
• Tokens: RS256 JWT (per-tenant key pairs), bcrypt, AES-256-GCM
• Container: Multi-stage Docker build, ~120 MB runtime image

⁠Contributing

See CONTRIBUTING.md⁠.

⁠License

MIT⁠