Important
Janua is the ecosystem identity provider. Keep examples placeholder-only; do not commit or paste user records, OAuth client secrets, session/refresh/access tokens, JWKS/private keys, MFA/passkey/backup-code material, SAML/SCIM metadata, webhook payloads, migration exports, database URLs, npm tokens, GitHub tokens, or production credentials.
Important
MADFAM-ENCLII-FIRST-LEGACY-RAW v1: This document contains legacy raw infrastructure command examples.
Routine production operations must use Enclii web, API, or CLI. Treat raw
kubectl, helm, SSH, provider CLI/API, docker exec, and direct container
access as platform bootstrap or documented break-glass only, and record any
missing Enclii adapter gap.
The Auth0 alternative you can run on your own infrastructure. Zero per-user pricing. Complete control. Currently in private alpha.
Website: janua.dev | Docs: docs.janua.dev | Demo: demo.janua.dev
Janua runs in production today as the identity provider for the MADFAM ecosystem — our own infrastructure, dogfooded daily. External availability is private alpha for design partners. The GA claim matrix is the source of truth for what is supported, beta, or roadmap; this README follows it.
| Service | Domain | Status |
|---|---|---|
| API / OIDC Provider | auth.madfam.io |
✅ Running on Enclii |
| Admin Dashboard | admin.janua.dev |
✅ Running on Enclii |
| User Dashboard | app.janua.dev |
✅ Running on Enclii |
| Documentation | docs.janua.dev |
✅ Running on Enclii |
| Website | janua.dev |
✅ Running on Enclii |
Infrastructure: 2-Node Hetzner Cluster via Enclii PaaS
- Production workloads on "The Sanctuary" (dedicated server)
- CI/CD builds on "The Forge" (CPX11)
- Zero-trust ingress via Cloudflare Tunnel
Active SSO Integrations:
- Enclii Dashboard (
enclii-web) - Enclii Admin/Dispatch (
dispatch-admin) - Dhanam Ledger (
dhanam-ledger) - Dhanam Admin (
dhanam-admin)
A self-hosted authentication platform built with FastAPI and modern web technologies. Think Auth0 or Clerk, but you run it on your own infrastructure and the source code is yours.
Every capability below is labeled against our GA claim matrix: "running today" means it powers MADFAM production SSO right now; "hardening" means the code is implemented and in daily use, but we are still filing the hosted proof (synthetics, E2E journeys, runbooks) we require before calling it generally available.
✅ Running in production today (Janua is the SSO for the MADFAM ecosystem):
- Self-hosted OAuth2/OIDC identity provider (authorization code + PKCE)
- OpenID Connect discovery (
/.well-known/openid-configuration) and published JWKS - RS256-signed JWTs — verify tokens anywhere against our public keys
- Email/password authentication with secure hashing
- OAuth 2.0 social login (Google, GitHub, Microsoft, Apple, Discord, Twitter, LinkedIn, Slack)
- Magic links (passwordless email authentication)
- Hosted health endpoints for operations
🔧 Implemented, hardening in progress (in daily use; GA evidence being filed):
- Multi-factor authentication: TOTP, WebAuthn/passkeys (FIDO2), backup codes
- Multi-tenancy with organization hierarchy
- RBAC with granular permissions (treat as beta until tenant-isolation proof is current)
- Audit logging (treat as beta until retention/export proof lands)
- Admin org/user/app operations
- Client-credentials token exchange, session refresh/logout journey evidence
- Webhooks and JIT (Just-In-Time) provisioning
🛠️ Developer experience:
- Extensive REST API with generated OpenAPI reference at
/docs - SDKs: React, Vue, Next.js, TypeScript, Python, Go, Flutter, React Native
- Auth0 migration tooling (beta — dry-run first; see below)
🗺️ Roadmap — not GA today (details in Roadmap):
- SAML 2.0 SSO — implementation exists in the tree; commercial support is roadmap/beta until per-customer proof exists
- SCIM 2.0 user provisioning
- Compliance exports, SOC 2 Type II program, HIPAA/BAA
- Uptime SLAs and enterprise support contracts
What we're improving:
⚠️ Documentation completeness (ongoing)⚠️ Scale testing beyond 100K users (planned)⚠️ UI component polish (ongoing)
Not available (by design):
- ❌ Managed SaaS hosting (self-host only - that's the point)
The problem: Auth0 charges $2,000+/month for SSO. Clerk is beautiful but SaaS-only. Keycloak is powerful but has terrible developer experience.
Our take: Authentication features shouldn't cost enterprise prices. Self-hosting shouldn't mean suffering through Keycloak's Java-era UI.
So we built this. All features are free and open source. AGPL v3 licensed.
We built a migration tool to help you escape Auth0's pricing.
Status: Beta. Per our GA claim matrix, migration assistance is offered after an import/export dry-run for your scope, with rollback and integrity evidence — we don't commit dates before that.
If you're paying $2,000-5,000/month for Auth0 (or more with SSO/SCIM), you can migrate to self-hosted Janua and run it for ~$170/month.
Estimated savings: $24,000-58,000/year, depending on your Auth0 plan.
- ✅ Export all users from Auth0 (via Management API)
- ✅ Import to Janua with automatic data mapping
- ✅ Preserve user data - email, name, phone, metadata
- ✅ Migration report showing success/failures
- ✅ Zero-downtime strategy guide included
Quick migration:
cd scripts/migration
pip install -r requirements.txt
python auth0_migrate.py --config config.json📖 Full guide: scripts/migration/README.md
Note: Password hashes can't be migrated from Auth0 (this is normal). Users reset passwords on first login.
# Clone the repository
git clone https://github.com/madfam-org/janua.git
cd janua
# Install dependencies (pnpm monorepo)
pnpm install
# Start infrastructure (PostgreSQL + Redis)
cd apps/api
docker-compose up -d postgres redis
# Setup Python environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
# Start API
uvicorn app.main:app --reload --port 8000
# In another terminal, start the website
cd apps/website
pnpm dev
# Open http://localhost:3001 (website) or http://localhost:8000/docs (API)That's it. You now have a working OAuth2/OIDC provider with MFA and passkeys.
This is a pnpm workspace monorepo. All apps and packages are managed together.
janua/
├── apps/
│ ├── api/ # FastAPI backend (Python)
│ ├── dashboard/ # User management UI (Next.js)
│ ├── website/ # Public website + demos (Next.js)
│ ├── admin/ # Internal admin tools
│ └── docs/ # Documentation site
├── packages/
│ ├── ui/ # Shared React components (@janua/ui)
│ ├── sdk/ # Client SDK (@janua/sdk)
│ ├── database/ # Database schemas
│ └── config/ # Shared configs
└── deployment/
└── production/ # Docker, nginx, monitoring
# Install all dependencies
pnpm install
# Build all packages
pnpm build
# Run all apps in dev mode
pnpm dev
# Run specific app
pnpm --filter @janua/website dev
pnpm --filter @janua/dashboard dev
# Lint/typecheck
pnpm lint
pnpm typecheck- Full REST API for auth, user, org, and MFA management
- Async Python with SQLAlchemy 2.x
- Redis caching for sessions and rate limiting
- JWT tokens with RS256 signing and published JWKS
- Audit logging for security events (beta)
- OpenAPI docs at
/docs
- React SDK - Hooks and components
- Vue SDK - Composables for Vue 3
- Next.js SDK - App Router support
- TypeScript SDK - Type-safe client
- Python SDK - For backend integration
- Go SDK - For Go services
- Flutter SDK - For mobile apps
- 15 pre-built components - SignIn, SignUp, MFA, etc.
- Radix UI primitives - Accessible by default
- Customizable styling - Bring your own CSS
Janua SDKs are published to MADFAM's private npm registry. Configure your .npmrc before installing:
# Add to your project's .npmrc or ~/.npmrc
@janua:registry=https://npm.madfam.io
//npm.madfam.io/:_authToken=${NPM_MADFAM_TOKEN}For CI/CD environments, set the NPM_MADFAM_TOKEN secret in your GitHub Actions or CI platform.
Docker Compose (Recommended):
# Clone and configure
git clone https://github.com/madfam-org/janua.git
cd janua
# Copy environment files
cp .env.example .env
cp apps/api/.env.example apps/api/.env
cp apps/dashboard/.env.example apps/dashboard/.env
cp apps/website/.env.example apps/website/.env
# Edit .env files with your settings
# Start all services
cd deployment/production
docker-compose -f docker-compose.production.yml up -d
# Run migrations
docker-compose exec janua-api alembic upgrade headBuild Docker Images:
# From project root
docker build -f Dockerfile.api -t janua/api:latest .
docker build -f Dockerfile.dashboard -t janua/dashboard:latest .
docker build -f Dockerfile.website -t janua/website:latest .Kubernetes:
# Helm chart available in deployment/helm
helm install janua ./deployment/helm/janua \
--set postgresql.enabled=true \
--set redis.enabled=trueConfiguration:
- See Production Deployment Guide for bare metal/VPS setup
- See Deployment Guide for cloud deployment
- See Environment Variables for options
# React SDK
npm install @janua/react-sdk
# Vue SDK
npm install @janua/vue-sdk
# Next.js SDK
npm install @janua/nextjs-sdk
# TypeScript SDK (core client)
npm install @janua/typescript-sdkimport { JanuaProvider, useAuth } from '@janua/react-sdk';
function App() {
return (
<JanuaProvider baseURL="https://your-api.com">
<YourApp />
</JanuaProvider>
);
}
function Profile() {
const { user, signOut } = useAuth();
return <div>Welcome, {user?.email}</div>;
}from janua import JanuaClient
client = JanuaClient(base_url="https://your-api.com")
# Authenticate
result = await client.auth.sign_in(
email="user@example.com",
password="password"
)
# Get user
user = await client.users.get_current_user()// app/api/auth/[...janua]/route.ts
import { JanuaNextAuth } from '@janua/nextjs-sdk';
export const { GET, POST } = JanuaNextAuth({
baseURL: process.env.JANUA_API_URL!,
});┌─────────────────────────────────────────┐
│ Your Application (React/Vue/Next.js) │
│ Uses: @janua/sdk │
└────────────────┬────────────────────────┘
│ HTTPS/JSON
▼
┌─────────────────────────────────────────┐
│ Janua API (FastAPI) │
│ • JWT authentication │
│ • OAuth/OIDC/WebAuthn │
│ • User/org management │
│ • Audit logging │
└─────┬──────────────────────┬────────────┘
│ │
▼ ▼
┌──────────┐ ┌─────────────┐
│PostgreSQL│ │ Redis │
│ (users, │ │ (sessions, │
│ orgs) │ │ cache) │
└──────────┘ └─────────────┘
You control everything. Your database, your infrastructure, your data.
Honest answer: it runs our production, and we hold ourselves to a written standard — the GA claim matrix — before claiming it can run yours.
What runs in production today:
- Janua is the identity provider for the MADFAM ecosystem (Enclii, Dhanam, and more) — OIDC discovery, JWKS, and hosted health checks are exercised daily
- Core authentication flows, covered by the unit/integration test suite
- MFA implementations (TOTP, WebAuthn/passkeys, backup codes)
What we require before calling a capability GA:
- Hosted synthetic or E2E journey evidence (login, session refresh/logout, admin operations)
- Tenant-isolation and role test matrices for RBAC
- Retention/export proof for audit logs
- A support runbook and named ownership
What we don't know yet:
- How it performs at 100K+ users (we haven't run it there)
- Every edge case in every browser (help us test!)
- Long-term upgrade paths (the project is young)
Our recommendation:
- ✅ Use it if you want to self-host and can debug issues
- ✅ Use it if you're okay filing bugs when you find them
- ✅ Talk to us about the design-partner program if you need SAML/SCIM/compliance on a committed timeline
⚠️ Don't use it if you need guaranteed uptime SLAs today⚠️ Don't use it if you can't troubleshoot Docker/PostgreSQL
We need help. This is a big project and we're a small team.
Where we need help most:
- 🐛 Testing - Run it, break it, file issues
- 📚 Documentation - Fill in gaps, fix errors
- 🎨 UI Polish - Make components more accessible
- 🔧 Bug Fixes - Pick an issue, submit a PR
- 💬 Support - Help others on GitHub issues
How to contribute:
- Read CONTRIBUTING.md
- Pick an issue or file a new one
- Submit a PR
- We'll review and merge
We're friendly to first-time contributors. Seriously.
What we're focused on now:
- Making setup easier (one-command installs)
- Improving documentation
- Fixing bugs as they're reported
- Testing the Auth0 migration tool with real users (beta)
Enterprise track — gated by the GA claim matrix; each item ships when its hosted proof is filed:
- SAML 2.0 SSO commercial support (implementation exists; needs per-customer IdP proof and a support runbook)
- SCIM 2.0 provisioning (needs create/update/deactivate synthetics)
- Compliance exports (needs export/delete evidence and a retention policy)
- SOC 2 Type II program; HIPAA/BAA legal review
- Published uptime SLA (needs 30-day evidence and a support schedule)
What we're NOT doing:
- Building a managed SaaS version (yet)
- Chasing every feature request
- Trying to be Auth0
What we just shipped:
- ✅ Auth0 migration tool (help us test it!)
Future (when we have >5K stars and prove this is valuable):
- Managed hosting option
- Clerk/Firebase migration tools
- Enterprise support contracts
We'll build what the community needs. Tell us what you need.
vs. Auth0/Okta:
- ✅ You own the infrastructure
- ✅ No per-user pricing (est. $24K-58K/year savings)
- ✅ Migration tool included (beta — export users from Auth0)
- ❌ No managed service (you run it)
- ❌ No compliance reports (SOC 2 is on the roadmap, not a current certification)
vs. Clerk:
- ✅ Self-hostable
- ✅ Direct database access (no webhooks)
- ❌ UI components are less polished
- ❌ No managed option (yet)
vs. Keycloak:
- ✅ Better developer experience
- ✅ Modern tech stack (FastAPI vs Java)
- ❌ Less mature (Keycloak is 10+ years old)
- ❌ Smaller community
vs. Better-Auth:
- ✅ Full backend included (not just SDK)
- ✅ UI components included
- ❌ More opinionated (FastAPI + PostgreSQL)
Bottom line: Use this if you want to self-host and modern DX matters to you.
AGPL-3.0 License - GNU Affero General Public License v3.0
Copyright (C) 2025 Innovaciones MADFAM SAS de CV
See LICENSE for details.
- 📖 Documentation: docs/
- 🐛 Bug Reports: GitHub Issues
- 💬 Questions: GitHub Discussions
- 📧 Security Issues: security@janua.dev
No Discord/Slack yet. We'll create them when we have enough users to justify it.
Janua provides llmstxt.org standardized documentation for AI agents:
- llms.txt — Quick navigation
- llms-full.txt — Complete reference
- Stars: Just getting started (star us if you find this useful!)
- Production users: Unknown (tell us if you're using it!)
- Contributors: Looking for more
- Funding: None (bootstrapped, AGPL v3 licensed)
We're building this in public. The good, the bad, and the bugs.
Built by developers who got tired of auth pricing and wanted to own their stack.