Full-stack authentication and authorization solution for Kotlin Multiplatform (KMP) and Compose Multiplatform (CMP), featuring a Spring Boot Authorization Server and multiplatform client SDKs.

Your own auth server and a Compose Multiplatform login SDK, in one repo. Run one Docker image, add one Gradle dependency, and your Android, iOS, desktop and web apps sign users in with passwords, passkeys, Google, Apple or one-time codes, against a standard OAuth 2.1 / OpenID Connect server you host and own. No per-user pricing, and your users' data stays in your MongoDB.

git clone https://github.com/pitampoudel/komposeauth && cd komposeauth
cp .env.example .env && echo "BASE64_ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env
docker compose up -d   # then open http://localhost:8080/admin/config

// commonMain
implementation("io.github.pitampoudel:komposeauth-client:<latest-version>")

val httpClient = HttpClient {
    installKomposeAuth(
        authServerUrl = "https://auth.example.com",
        resourceServerUrls = listOf("https://api.example.com") // your APIs get the bearer token
    )
}

If komposeauth is useful to you, a ⭐ helps other Kotlin developers find it.

Most auth options for a Kotlin Multiplatform app make you pick between a hosted service that bills per active user and a generic identity server you have to wire into Compose yourself. komposeauth gives you both halves, built for each other:

Pick komposeauth when you are building a Kotlin Multiplatform or Compose Multiplatform app, want to own your users, and would rather not glue a generic identity server to your client by hand. Pick something else if you need SAML, enterprise federation, or a fully managed service you never operate.

• Why komposeauth?
• Overview & Architecture
• Features
• Quickstart (Docker)
• Server Configuration & Deployments
  • Admin Console & Connections
  • File & Asset Storage
  • Environment Variables
  • Production Deployments
• Role of the Consumer Resource Server (Your APIs)
  • How Authentication & Verification Works
  • Token Verification Examples
• Client SDK Setup
  • Installation
  • HTTP Client Configuration
  • Usage Examples
• Integration Guide (LLMs & Backends)
• Security & Architecture Details
• Building, Publishing & Versioning
• Contributing & License

komposeauth provides a complete, modern authentication ecosystem across server and client platforms:

• Auth Server: Spring Boot OAuth 2.1 & OpenID Connect Authorization Server with administrative management, rate limiting, and encrypted KYC storage.
• Shared SDK (komposeauth-shared): Cross-platform Kotlin Multiplatform data models, DTOs, and validation logic.
• Client SDK (komposeauth-client): Compose Multiplatform UI components, Ktor authentication plugins, Credential Manager integrations, and ViewModels for Android, iOS, Desktop, and Web.

┌────────────────────────────────────────────────────────────────────────┐
│                          Client Applications                           │
│                (Android, iOS, Desktop, Web / KMP & CMP)                │
└──────────────┬──────────────────────────────────────────┬──────────────┘
               │                                          │
               │ 1. Sign in (OAuth 2.1 / PKCE / /login)   │ 3. API Requests with Bearer JWT
               ▼                                          ▼
┌────────────────────────────────────────┐     ┌─────────────────────────┐
│    komposeauth Server (Auth Server)    │     │ Consumer Resource Server│
│  - Issues RS256 JWTs                   │     │ (Your API Backend)      │
│  - Hosted OIDC / Session Login         │     │ - Validates JWT locally │
│  - Admin Console (/admin)              │     │ - Reads user roles/UID  │
│  - KYC & File Encryption               │     └───────────┬─────────────┘
└──────────────┬───────────┬─────────────┘                 │
               │           │                               │ 2. Fetch JWKS public keys
               ▼           ▼                               │    (cached automatically)
      ┌─────────────────┐ ┌──────────────────┐             │
      │  MongoDB Store  │ │ S3 / GCS Storage │◄────────────┘
      └─────────────────┘ └──────────────────┘

• 🔐 Authentication Flows: Email or phone with password, Passkeys (WebAuthn / FIDO2), Sign in with Google and Apple, and one-time codes by SMS, WhatsApp or email.
• 🤖 Works with MCP clients: Client ID Metadata Documents (CIMD) let MCP clients such as Claude sign in to your APIs without manual registration.
• 🛡️ OAuth 2.1 & OpenID Connect: PKCE (S256), discovery (/.well-known/openid-configuration), and RS256 JWT token issuance validated via JWKS.
• 📱 Multiplatform Client: Compose Multiplatform UI components, Credential Manager, and automatic Ktor token interceptors.
• ✉️ Verification & Recovery: Email verification codes and SMS OTP retriever support.
• 🪪 KYC Document Management: Client-side encryption before S3/GCS upload and restricted retrieval endpoints.
• ⚙️ Admin Console: Web UI (/admin/config) for runtime configuration of OAuth clients, SMTP, SMS providers, CORS, and rate limits.
• 🚦 Abuse & Rate Limiting: Distributed rate-limiting backed by MongoDB with configurable edge proxy awareness.
• 📊 Observability & Docs: OpenAPI/Swagger UI, Sentry integration, and Actuator health endpoints.

The fastest way to get started is using Docker Compose, which starts the server alongside a MongoDB instance:

git clone https://github.com/pitampoudel/komposeauth && cd komposeauth
cp .env.example .env
echo "BASE64_ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env
docker compose up -d

Open http://localhost:8080/admin/config, enter the BASE64_ENCRYPTION_KEY from .env, and create the initial super admin account. Keep this key safe: it encrypts every secret the server stores.

To run the standalone Docker image against an existing MongoDB instance:

docker run -d -p 8080:8080 \
  --name komposeauth \
  -e MONGODB_URI="mongodb://your-mongo-host:27017" \
  -e BASE64_ENCRYPTION_KEY="$(openssl rand -base64 32)" \
  -e SPRING_SECURITY_OAUTH2_AUTHORIZATIONSERVER_ISSUER="http://localhost:8080" \
  pitampoudel/komposeauth:latest

Once the container is running, navigate to the web administration console:

• URL: http://localhost:8080/admin/config
• Initial Authentication: Enter your BASE64_ENCRYPTION_KEY into the form, or provide it via the X-Master-Key header:

curl -H "X-Master-Key: <paste-your-base64-key>" http://localhost:8080/admin/config

When no super admin exists yet (SUPER_ADMIN), the page opens with Create the first admin: enter an email and password (or the address of an account that already exists) to grant that account super admin privileges. Afterwards, sign in at /admin using your admin credentials instead of the master key. The initial setup form disappears once a super admin exists, and additional roles can be assigned from the Users management page.

Use the Admin Console to configure email (SMTP), SMS providers (Twilio, Infobip, WhatsApp), Google and Apple sign-in, error reporting and chat alert webhooks, custom branding, CORS origins, and rate limits. All third-party integrations are optional.

Profile photos, organization logos, and KYC documents are stored in buckets configured under Storage (/admin/storage) in the admin console. Any admin can view storage settings; only a SUPER_ADMIN can add or modify storage buckets. Note that asset uploads require an active storage bucket.

Supported storage backends include Google Cloud Storage (GCS) and any S3-compatible provider (Amazon S3, Cloudflare R2, MinIO, Backblaze B2, etc.):

• For non-AWS S3 providers, specify the custom endpoint URL. Path-style addressing ({endpoint}/{bucket}/{name}) is supported.
• Set a custom CDN or domain in front of the bucket as its public URL if desired.
• Leave credentials blank to use runtime ambient IAM credentials (e.g., Cloud Run service accounts, ECS task roles), or supply an API/service account key (stored securely with AES encryption).
• Use the Test button in the console to verify write, read, and delete operations.

Public vs. Private Access:

• Profile photos and organization logos are loaded directly by client browsers and require public read permissions on the users/ and organization_logos/ path prefixes.
• KYC documents remain private and are accessible only via authenticated endpoints (see Encrypted KYC Documents).

Bucket Migration:

• Active uploads are directed to whichever bucket is designated as active ("Send new files here").
• Existing files remain accessible at their original URLs without requiring automatic server-side data migration.
• When migrating to a new bucket, use sync tools (rclone, aws s3 sync, or gcloud storage rsync) and link the old bucket entry using Files copied to… to preserve backward compatibility.

Set SPRING_SECURITY_OAUTH2_AUTHORIZATIONSERVER_ISSUER to the public origin URL of your auth server (e.g. https://auth.example.com).

• Do not include trailing slashes or subpaths.
• If using Google Sign-In, register <ISSUER_URL>/login/oauth2/code/google as the authorized redirect URI in Google Cloud Console.

Under Rate Limiting in /admin/config, configure client IP resolution depending on your deployment:

• Header-based platforms (e.g. Railway, Fly.io, Cloudflare): Set clientIpHeader to X-Real-IP, Fly-Client-IP, or CF-Connecting-IP.
• X-Forwarded-For platforms: Set trustedProxyCount to the number of reverse proxy hops you control (e.g., 1 for Google Cloud Run, 2 when behind an external load balancer).
• Direct exposure: Leave unset and pass FORWARD_HEADERS_STRATEGY=none.

Verify your detected IP address at any time using:

curl https://your-auth-server/admin/client-ip -H "Cookie: <your-session-cookie>"

Every option runs the same image and keeps everything in MongoDB, so moving between them is a matter of pointing the new one at the same database with the same key and issuer. Where there is no MongoDB alongside, a MongoDB Atlas cluster works; the free M0 is enough to start. Allow the host's outbound addresses in Atlas's network access, or 0.0.0.0/0 on hosts whose addresses change.

Platform	Deployment Method	Scales to zero	Memory Profile
Render	(render.yaml)	Yes (Free plan)	512 MB
Railway	(railway.json)	Sleeps on idle (Hobby)	512 MB
DigitalOcean	(.do/deploy.template.yaml)	Configurable	512 MB
Fly.io	fly launch / fly deploy (fly.toml)	Yes (auto stop/start)	512 MB
Google Cloud Run	gcloud run deploy command below	Yes	1 GiB
Self-hosted Docker	docker compose up -d (Quickstart)	No	512 MB+

Deploy via the Blueprint button above or use render.yaml. The blueprint creates a web service from the published image and generates BASE64_ENCRYPTION_KEY; it asks only for MONGODB_URI. With no issuer set, the server uses its own onrender.com address. To serve it from your own domain, add the domain in Render and set SPRING_SECURITY_OAUTH2_AUTHORIZATIONSERVER_ISSUER to it.

The blueprint sets BPL_JVM_THREAD_COUNT=50 and JAVA_TOOL_OPTIONS=-XX:ReservedCodeCacheSize=64M so the JVM fits in 512 MB.

Deploy using the Railway button above or connect your GitHub repo using railway.json:

1. Add a MongoDB plugin or connect an external MongoDB Atlas cluster (MONGODB_URI).
2. Add environment variables:
   • BASE64_ENCRYPTION_KEY: A 32-byte Base64 key (openssl rand -base64 32).
   • SPRING_SECURITY_OAUTH2_AUTHORIZATIONSERVER_ISSUER: https://${{RAILWAY_PUBLIC_DOMAIN}} or your custom domain.
3. Under /admin/config $\rightarrow$ Rate Limiting, set clientIpHeader to X-Real-IP.

Deploy using the DigitalOcean button above or create a new App pointing to your repository (.do/deploy.template.yaml will be auto-detected):

1. Set MONGODB_URI to a MongoDB Atlas connection string.
2. BASE64_ENCRYPTION_KEY is generated automatically; keep a copy somewhere safe.
3. Set SPRING_SECURITY_OAUTH2_AUTHORIZATIONSERVER_ISSUER to https://<your-app>.ondigitalocean.app or your custom domain.

Deploy to Fly.io using the included fly.toml:

fly launch --no-deploy
fly secrets set \
  MONGODB_URI="mongodb+srv://..." \
  BASE64_ENCRYPTION_KEY="$(openssl rand -base64 32)" \
  SPRING_SECURITY_OAUTH2_AUTHORIZATIONSERVER_ISSUER="https://<your-app>.fly.dev"
fly deploy

Under /admin/config $\rightarrow$ Rate Limiting, set clientIpHeader to Fly-Client-IP.

gcloud run deploy komposeauth \
  --image pitampoudel/komposeauth:latest \
  --set-env-vars MONGODB_URI="mongodb+srv://...",BASE64_ENCRYPTION_KEY="<your-base64-key>",SPRING_SECURITY_OAUTH2_AUTHORIZATIONSERVER_ISSUER="https://auth.example.com" \
  --min-instances 0 \
  --concurrency 40 \
  --cpu 1 --memory 1Gi \
  --cpu-boost \
  --startup-probe httpGet.path=/actuator/health/readiness,httpGet.port=8080,initialDelaySeconds=4,periodSeconds=2,timeoutSeconds=2,failureThreshold=45

Under /admin/config $\rightarrow$ Rate Limiting, set trustedProxyCount to 1.

In the komposeauth architecture, your backend application is the OAuth 2.1 Resource Server. It hosts your business logic and protected REST/GraphQL/gRPC endpoints (e.g. https://api.example.com), while komposeauth serves exclusively as the Authorization Server (e.g. https://auth.example.com).

1. Client Obtains Token: The client application (Android, iOS, Desktop, Web) authenticates with komposeauth and receives an RS256 JWT access token.
2. Client Calls Your API: When making HTTP calls to URLs listed in resourceServerUrls, the client SDK attaches the token: Authorization: Bearer <jwt>.
3. Stateless Local Verification: Your backend validates the JWT locally and cryptographically using public keys fetched from https://auth.example.com/oauth2/jwks (or OIDC discovery at /.well-known/openid-configuration).
   • ⚡ Zero Per-Request Network Overhead: Your backend does not call komposeauth for each incoming request. The public keys are fetched once and cached.
   • 🔒 Trust & Integrity: The token's signature, issuer (iss), expiration (exp), and audience/scopes are verified by your backend framework's standard JWT validator.
4. Extract User & Claims: Your API extracts the user ID (sub), email, roles (roles), and custom claims directly from the verified JWT payload.

Every access token issued by komposeauth contains standard JWT claims:

{
  "iss": "https://auth.example.com",
  "sub": "66f1c0e4a1b2c3d4e5f60718",
  "aud": ["https://api.example.com"],
  "exp": 1729000000,
  "iat": 1728999100,
  "scope": ["openid", "profile", "email"],
  "roles": ["USER"]
}

Any standard OAuth2/OIDC library can secure your backend:

install(Authentication) {
    jwt("auth-jwt") {
        realm = "komposeauth"
        verifier(
            JwkProviderBuilder(URL("https://auth.example.com/oauth2/jwks"))
                .cached(10, 24, TimeUnit.HOURS)
                .rateLimited(10, 1, TimeUnit.MINUTES)
                .build(),
            issuer = "https://auth.example.com"
        ) {
            acceptLeeway(3)
        }
        validate { credential ->
            if (credential.payload.subject.isNotEmpty()) {
                JWTPrincipal(credential.payload)
            } else null
        }
    }
}

routing {
    authenticate("auth-jwt") {
        get("/api/me") {
            val principal = call.principal<JWTPrincipal>()
            val userId = principal?.payload?.subject
            call.respondText("Hello user: $userId")
        }
    }
}

# application.yml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com
          jwk-set-uri: https://auth.example.com/oauth2/jwks

import { expressjwt } from "express-jwt";
import jwksRsa from "jwks-rsa";

const checkJwt = expressjwt({
  secret: jwksRsa.expressJwtSecret({
    cache: true,
    rateLimit: true,
    jwksUri: "https://auth.example.com/oauth2/jwks"
  }) as any,
  issuer: "https://auth.example.com",
  algorithms: ["RS256"]
});

app.get("/api/me", checkJwt, (req, res) => {
  res.json({ user: req.auth });
});

For complete examples in Python, Go, Fastify, and other frameworks, see the Full Integration Guide.

Add the dependencies to your Kotlin Multiplatform commonMain source set:

// build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            // Client SDK (includes UI components, ViewModels, and Ktor plugins)
            implementation("io.github.pitampoudel:komposeauth-client:<latest-version>")
            
            // Optional: Shared DTOs and validators (already transitive in client)
            implementation("io.github.pitampoudel:komposeauth-shared:<latest-version>")
        }
    }
}

Install the KomposeAuth plugin on your Ktor HttpClient:

val httpClient = HttpClient {
    installKomposeAuth(
        authServerUrl = "https://auth.example.com",
        resourceServerUrls = listOf(
            "https://api.example.com"
        )
    )
}

// Initialize the SDK with the configured client
initializeKomposeAuth(
    httpClient = httpClient
)

Platform Notes:

• Android: Pass the Android Context to store tokens encrypted with Android Keystore.
• Desktop: Pass appId (e.g. your application ID) to isolate token storage in Java Preferences.

@Composable
fun UserProfileScreen() {
    val userState by rememberAuthenticatedUser()
    
    userState?.let { user ->
        Text("Welcome, ${user.displayName ?: user.email}")
    } ?: Text("Not logged in")
}

@Composable
fun LoginScreen(vm: LoginViewModel = koinViewModel()) {
    val state by vm.state.collectAsStateWithLifecycle()
    val credentialManager = rememberKmpCredentialManager()

    LaunchedEffect(state.loginConfig) {
        state.loginConfig?.let { config ->
            when (val result = credentialManager.getCredential(config)) {
                is Result.Success -> vm.onEvent(LoginEvent.Login(result.data))
                is Result.Error -> vm.onEvent(LoginEvent.ShowInfoMsg(result.message))
            }
        }
    }
}

@Composable
fun OtpVerificationScreen(vm: OtpViewModel = koinViewModel()) {
    registerSmsOtpRetriever { otpCode ->
        vm.onEvent(OtpEvent.CodeChanged(otpCode))
    }
}

The SDK includes ready-to-use Compose Multiplatform UI components and utilities:

• ScreenStateWrapper with error/info and loading progress dialogs
• CountryPicker, DateTimeField, and OTPTextField
• rememberFilePicker for image/document selection
• String resource mapping helpers for validation errors: (error).toStringRes()

A comprehensive integration guide for developers and LLM coding assistants covers frontend OAuth 2.1 PKCE flows, JWT claims structure, and backend token validation across multiple platforms (Spring Boot, Node.js, Python, Go, and Ktor):

• llms.txt — High-level quick reference index (llms.txt standard)
• docs/llms-full.txt — Complete integration guide

Both files are also served directly by the server at https://<your-auth-server>/llms.txt and https://<your-auth-server>/llms-full.txt.

The project follows Semantic Versioning (vMAJOR.MINOR.PATCH).

Version resolution works uniformly across both local builds and CI:

1. Gradle Property: -Pversion=X.Y.Z (explicit override)
2. CI Tag / Ref: Environment variable GITHUB_REF_NAME (e.g. v0.2.8 → 0.2.8)
3. Git Tag: Automatically extracted from git describe --tags (e.g. v0.2.8 → 0.2.8)
4. Development Default: 1.0.0-SNAPSHOT

CI publishes the image (.github/workflows/docker-publish.yml): a push to main publishes main and latest, and a GitHub release vX.Y.Z publishes X.Y.Z and X.Y.

From IntelliJ, the shared run configurations in .run/ run the same commands:

• Publish server image: tests, then bootBuildImage --publishImage to main and latest. Sign in to Docker Hub once (Docker Desktop, or docker login).
• Deploy to Cloud Run: publishes, then rolls the existing komposeauth service onto the new image, keeping its environment. It deploys to your gcloud default project and asks for a region if run/region isn't set.

CI publishes the SDK (.github/workflows/library-publish.yml) to GitHub Packages and Maven Central. From IntelliJ, publishToMavenLocal installs it into ~/.m2 for a local app, and Release SDK to Maven Central tests and releases the version of the tag you are on (v0.2.8 → 0.2.8), with mavenCentralUsername, mavenCentralPassword and the signingInMemoryKey* properties in ~/.gradle/gradle.properties.

The authorization server enforces browser origin security using the Sec-Fetch-Site header:

• Same-origin requests are always allowed.
• Cross-site requests are restricted to origins explicitly configured under CORS allowed origins in /admin/config.
• Non-browser API clients (mobile apps, KMP SDK, backend servers) authenticate with bearer tokens and are unaffected.

• Profile pictures are publicly accessible if configured, but sensitive KYC identity scans and selfies are encrypted using BASE64_ENCRYPTION_KEY before upload to cloud storage.
• KYC documents are served exclusively via authenticated endpoints (GET /kyc/{userId}/documents/{front|back|selfie}) requiring a user bearer token or administrative session.

Please report vulnerabilities privately, as described in SECURITY.md, rather than in a public issue.

Contributions are welcome. CONTRIBUTING.md covers running the server locally, the tests, and what a pull request needs. For changes that affect existing deployments, please open an issue first. What changed in each release is in CHANGELOG.md.

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