README
¶
An open-source, self-hostable identity and access platform. Delivers identity and access management (IAM) for applications, services, and APIs — from authentication and federation to fine-grained authorization.
Features
- Full OAuth 2.0 + OIDC — authorization code (PKCE), client credentials, device, token exchange, PAR, CIBA, dynamic client registration, DPoP
- JWT (RS256) with multi-key JWKS and automatic key rotation
- Multi-factor authentication — TOTP, WebAuthn/passkeys, SMS OTP, backup codes, step-up auth
- Federation — OIDC upstream connectors (Google, Microsoft, Apple, GitHub, GitLab), JIT provisioning, identity linking, home-realm discovery
- Fine-grained access control — RBAC with granular permissions, plus IAM services, APIs, permissions, policies, service-token policy bundles, and service-to-service authorization
- Multi-tenant — full tenant isolation, API keys, invite flows
- Session management — refresh token rotation, family revocation, reuse detection, concurrent session limits
- Webhook delivery — auth event notifications with HMAC-SHA256 signatures and replay protection
- Audit logging — structured auth events with retention, per-tenant isolation, and PII redaction
- Pluggable secret management — env vars, AWS Secrets Manager, SSM, HashiCorp Vault, Azure Key Vault, GCP Secret Manager
- Pluggable email providers — SMTP, SES, SendGrid, Postmark, Mailgun, Resend
- OpenTelemetry — traces, metrics, and Prometheus endpoint
Quick Start
git clone https://github.com/maintainerd/maintainerd-auth.git
cd maintainerd-auth
cp .env.example .env
# Edit .env with your database, Redis, and JWT key settings
docker compose up --build -d
The management API is available at http://localhost:8080/api/v1 and the public auth API at http://localhost:8081/api/v1.
JWT keys
./scripts/generate-jwt-keys.sh
cat keys/jwt_env_vars.txt >> .env
Documentation
| Document | |
|---|---|
| Getting Started | Set up your local development environment |
| Environment Variables | All configuration variables |
| API Reference | Full OpenAPI 3.1 spec (also served at /openapi.json) |
| Service-to-Service Authorization | IAM policy bundles, local authorization, and service integration |
| Architecture | System design and data flow |
| Operator Runbook | Install, configure, first-run bootstrap, backups, and upgrades |
Contributing
Contributions are welcome. Please read CONTRIBUTING.md and the getting started guide before opening a pull request.
# Fork the repo, then:
git clone https://github.com/<your-username>/maintainerd-auth.git
cd maintainerd-auth
./scripts/dev.sh start # start the full local stack
go test ./... # run tests
Related Projects
maintainerd/auth-console— Admin console UImaintainerd/auth-identity— End-user identity portal
License
Copyright 2026 Reyco Seguma.
Licensed under the Apache License 2.0. See LICENSE for the license terms and NOTICE for attribution.
Built by Reyco Seguma (@xreyc) and the Maintainerd community.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
server
command
|
|
|
internal
|
|
|
event
Package event implements the integration event plane for maintainerd-auth.
|
Package event implements the integration event plane for maintainerd-auth. |
|
platform/apperror
Package apperror defines structured error types for the service layer.
|
Package apperror defines structured error types for the service layer. |
|
platform/dpop
Package dpop implements Demonstrating Proof of Possession (DPoP) for OAuth 2.0 per RFC 9449.
|
Package dpop implements Demonstrating Proof of Possession (DPoP) for OAuth 2.0 per RFC 9449. |
|
platform/geoip
Package geoip resolves IP addresses to a coarse, human-readable location for display in device/session lists.
|
Package geoip resolves IP addresses to a coarse, human-readable location for display in device/session lists. |
|
platform/retry
Package retry provides a simple exponential-backoff helper for startup dependency probes (database, Redis, AMQP, etc.).
|
Package retry provides a simple exponential-backoff helper for startup dependency probes (database, Redis, AMQP, etc.). |
|
platform/security
Package security provides comprehensive security utilities for authentication and authorization.
|
Package security provides comprehensive security utilities for authentication and authorization. |
|
platform/signedurl
Package signedurl provides signed URL utilities for secure link generation and validation.
|
Package signedurl provides signed URL utilities for secure link generation and validation. |
|
platform/valid
Package valid provides input validation helpers.
|
Package valid provides input validation helpers. |
|
webui
Default build (dev + `go test`): no assets embedded.
|
Default build (dev + `go test`): no assets embedded. |
Click to show internal directories.
Click to hide internal directories.