Skip to content
Kotauth

Introduction

Kotauth is an open-source identity and authentication platform designed for teams that need full control over their auth infrastructure without the operational weight of enterprise IAM systems or the vendor lock-in of SaaS solutions.

It bridges the gap between complexity (Keycloak, Okta) and convenience (Clerk, Auth0) — giving you a spec-compliant OAuth2 / OIDC provider that runs in a single Docker container, manages its own database schema, and is ready to accept connections in minutes.

What Kotauth provides

Section titled “What Kotauth provides”

OAuth2 and OIDC compliance. Kotauth implements the Authorization Code flow with PKCE, the Client Credentials flow, refresh token rotation, token introspection (RFC 7662), token revocation (RFC 7009), and a full OIDC discovery document with per-tenant JWKS endpoints. Any library or framework that speaks standard OAuth2/OIDC works with Kotauth out of the box.

Multi-tenancy. A single Kotauth instance hosts multiple independent workspaces. Each workspace has its own isolated user directory, OAuth applications, role definitions, SMTP configuration, and RS256 signing key pair with admin-initiated key rotation. Signing keys can be rotated from the admin console with zero-downtime rollover — old keys remain in JWKS for token verification until explicitly retired. Users in workspace A cannot interact with workspace B in any way.

REST API. A machine-to-machine API covers the full lifecycle of users, roles, groups, OAuth applications, sessions, and audit logs. Each operation is guarded by API key scopes so you can issue keys with the minimum privilege required.

Role-based access control. Roles can be scoped to the entire workspace (tenant roles) or to a specific application (client roles). Groups provide a hierarchy layer — users inherit all roles assigned to their groups and parent groups. Access token JWT claims expose these as realm_access.roles and resource_access.<clientId>.roles.

Webhooks. Subscribe any endpoint URL to identity events — user.created, login.failed, session.revoked, and five others. Payloads are signed with HMAC-SHA256 (X-KotAuth-Signature) and delivered asynchronously with automatic retries (immediate → 5 min → 30 min). Your application reacts to auth events in real time without polling.

White-label auth pages. Every workspace ships with a fully themeable login, registration, and MFA flow. Override colors, border radius, logo, and favicon per workspace through the admin console or the REST API. CSS custom properties are injected server-side at render time — no rebuild required.

Built-in admin console. A full web UI for workspace management, user administration, application setup, audit log review, webhook configuration, and security policies. No separate tooling required for day-to-day operations.

User invitations. Admins can invite users via branded email instead of setting passwords on their behalf. Invited users receive a secure activation link (72-hour expiry), set their own password, and their account activates automatically. A required actions framework tracks pending setup steps like SET_PASSWORD, with purpose-scoped tokens ensuring invite and password-reset flows never interfere with each other.

Self-service user portal. Users can manage their own profile, change passwords, view and revoke active sessions, enroll in or disable MFA, and view connected social accounts (Google, GitHub) — without developer involvement.

Custom JWT claims. Attach per-user key-value attributes and project them into JWT access and/or ID tokens using tenant-level claim mappers. 41 reserved OIDC claim names are protected. Changes propagate on next token issuance or immediately on refresh token renewal.

Magic-link passwordless. Users can authenticate via email with 15-minute one-time tokens — no password required. Same-device cookie binding prevents token replay from a different browser. MFA is still enforced if enrolled. Workspaces can disable password login entirely to go fully passwordless.

Admin impersonation. Administrators can act as any user without knowing their password. Impersonated sessions carry an RFC 8693 act claim for full audit attribution. A dual-session model preserves the admin session underneath, and cascade revocation ensures impersonated sessions are terminated when the admin logs out.

Tenant backup & restore. Export entire workspaces as encrypted, portable archive files (PBKDF2 600k iterations + AES-256-GCM) via CLI or admin API. Import with schema-version compatibility validation. Useful for disaster recovery, environment promotion, and migration between instances.

Redis distributed sessions. An optional Redis sidecar upgrades in-memory session storage and rate limiting to distributed implementations. Lua-scripted rate limiting ensures consistent enforcement across all instances. Fail-closed semantics prevent security bypass during Redis outages.

Internationalization (i18n). All user-facing strings in auth pages and the portal are externalized through a translation system. Volume-mounted JSON bundles let you add languages without recompiling. Accept-Language header resolution with quality-factor ranking and configurable per-workspace default locale.

App launcher. A per-workspace tile grid at /t/{slug}/launcher shows all applications the user is entitled to access, based on client-scoped roles. Tiles are auto-generated from registered OAuth applications.

Breached password detection. Passwords are checked against the Have I Been Pwned database using k-Anonymity range queries during registration and password changes. Only the first 5 characters of the SHA-1 hash leave the server.

Silent SSO. OIDC prompt=none checks for existing sessions without user interaction. max_age enforces re-authentication after a specified duration. id_token_hint validates session identity. The auth_time claim lets clients verify session age independently.

AI-native management (MCP). The @kotauth/mcp package connects AI assistants like Claude and Cursor directly to your Kotauth instance via the Model Context Protocol. 25 tools let you manage users, roles, groups, applications, sessions, audit logs, user attributes, and claim mappers through natural language — no HTTP requests, no SDK, no code.

How Kotauth compares

Section titled “How Kotauth compares”
KotauthKeycloakClerk / Auth0
Self-hostedYesYesNo
Docker-nativeYesComplicatedN/A
Multi-tenantYesRealm-basedOrganization-based
OIDC compliantYesYesYes
REST management APIYesYesYes
Magic-link passwordlessYesNoYes
AI assistant integration (MCP)YesNoNo
Tenant backup & restoreYesNoNo
Admin impersonationYesYesYes
Silent SSO (prompt=none)YesYesYes
Redis distributed sessionsYesYesN/A
InternationalizationYesYesYes
Breached password detectionYesNoYes
User invitationsYesYesYes
Custom JWT claimsYesYes (protocol mappers)Yes
Setup time~2 min~30 min~5 min
Operational footprintMinimalHeavy (JVM, Infinispan)Zero
Open sourceMITApache 2.0Closed

Architecture at a glance

Section titled “Architecture at a glance”

Kotauth is built on Kotlin 2.3 with Ktor 3.4 and PostgreSQL, with an optional Redis sidecar for distributed deployments. It follows hexagonal architecture — the domain layer has zero framework dependencies and all I/O flows through typed port interfaces. Route handling uses Ktor’s route-scoped plugin system for tenant resolution, session guards, and API context injection. This makes the codebase straightforward to extend and the business logic easy to test in isolation.

graph TB
    subgraph Kotauth
        subgraph Domain
            M[model]
            P[port]
            S[service]
        end
        subgraph Adapters
            W[web]
            DB[persistence]
            T[token]
            E[email]
            SO[social]
        end
        subgraph Infrastructure
            R[rate limit]
            C[crypto]
            I[i18n]
        end
    end

    Domain --> Adapters
    Adapters --> PG[(PostgreSQL)]
    Adapters --> RD[(Redis<br/>optional)]
    Adapters --> OP[OAuth Providers<br/>Google · GitHub]

Next steps

Section titled “Next steps”