Hanko

Hanko is an open source authentication and user management platform built for developers who want modern, secure auth without vendor lock-in. It supports the full spectrum of authentication methods — passkeys (WebAuthn/FIDO2), email passcodes, passwords, MFA (TOTP and security keys), OAuth SSO with social providers, and SAML 2.0 for enterprise identity providers — all configurable through a single, lightweight API.

At its core, Hanko uses a custom state machine engine called FlowPilot that models authentication journeys as discrete, resumable flows persisted in the database. This architecture makes login and registration experiences configurable and reliable across distributed environments, with built-in flow locking via Redis to prevent race conditions. The backend is written in Go and designed for cloud-native deployment via Docker or Kubernetes.

Hanko ships Preact-based web components (Hanko Elements) that register as standard custom elements, making them framework-agnostic and embeddable in any frontend stack with two lines of code. A companion JavaScript SDK handles API communication and session state for teams building fully custom UIs. Available for self-hosting or as a fully managed service via Hanko Cloud.

What You Get

• FlowPilot Authentication State Machine - A custom finite state machine engine that models login, registration, MFA, and profile flows as named states and actions persisted to the database, making flows resumable across requests and distributed-safe with Redis-based flow locking.
• Passkeys and WebAuthn Support - Full FIDO2/WebAuthn implementation using go-webauthn enabling biometric logins, hardware security keys, and device-bound passkeys with automatic credential management and fallback to email passcodes.
• Hanko Elements Web Components - Framework-agnostic Preact components compiled as native browser custom elements (<hanko-auth>, <hanko-profile>) that integrate with any frontend framework using two lines of code, with CSS variable customization.
• SAML Enterprise SSO - Complete SAML 2.0 service provider implementation supporting Okta, Azure AD, and custom enterprise identity providers, with IdP metadata discovery and certificate management.
• OAuth / Social Login Providers - Built-in integrations for Apple, Google, GitHub, Discord, LinkedIn, and custom OIDC providers, with PKCE-by-default for mobile compatibility and ACR value support.
• MFA with TOTP and Security Keys - Time-based one-time password (TOTP) and WebAuthn security key support for multi-factor authentication, with configurable enforcement policies and device trust for trusted devices.
• Server-Side Sessions with Remote Revocation - JWT-based session tokens with server-side tracking, AMR claim support for inspecting authentication method references, and remote revocation for security compliance.
• AWS KMS External Key Management - Configurable external HSM/KMS integration for JWT signing keys, keeping cryptographic material fully managed outside the Hanko process for high-security deployments.
• Webhooks and Audit Logging - Real-time webhook delivery for all auth events (signup, login, session, password change), with SQL-injection-safe audit log queries and security notification emails for credential changes.
• JavaScript Frontend SDK - TypeScript SDK that manages API communication, session state, and authentication flow execution for teams building fully custom login interfaces without the web components.

Common Use Cases

• Passwordless SaaS product launch - A developer team replaces password-based registration with passkeys and email passcodes using Hanko Elements, cutting authentication friction to zero while keeping all user data on their own infrastructure.
• B2B app with enterprise SSO requirements - A company adds SAML 2.0 SSO via Hanko so enterprise customers can sign in through Azure AD or Okta, satisfying procurement requirements without building IdP integrations from scratch.
• GDPR-compliant app for EU markets - A startup self-hosts Hanko in a European data center to ensure user authentication data never leaves the EU, with data minimalism by design and no third-party auth vendor in the processing chain.
• Auth0 or Clerk migration - A team replaces a SaaS auth provider to eliminate per-MAU pricing and vendor dependency, using Hanko Elements for UI parity and the FlowPilot API to replicate existing flow configurations.
• Mobile app with PKCE OAuth flows - A mobile development team configures Hanko’s PKCE-by-default OAuth flows for iOS and Android clients, where cookie-based state parameters are unreliable, using the frontend SDK directly.
• High-security platform with external KMS - A fintech or healthcare company configures Hanko to sign JWTs using AWS KMS, ensuring session signing keys are managed in a hardened key management system with full audit trails.

Under The Hood

Architecture

Hanko is structured as a Go monorepo with a layered backend that uses a custom state machine framework called FlowPilot to model all authentication interactions. Rather than routing login logic through procedural HTTP handlers, every user-facing flow — login, registration, MFA creation, profile management, device trust — is defined as a set of named States and Actions that FlowPilot orchestrates. Flow state is serialized and persisted to the database with optional compression, making flows resumable across requests. A distributed flow locking layer using Redis prevents concurrent execution of the same flow session. HTTP handlers (via echo v4) act as thin dispatchers that hand requests to FlowPilot, which coordinates action execution, stash management, and JWT issuance. The persistence layer is abstracted behind typed persister interfaces, enabling clean substitution of the underlying database without touching business logic.

Tech Stack

The backend is written in Go 1.26 using echo v4 as the HTTP framework, gobuffalo/pop v6 as the ORM with support for PostgreSQL, MySQL, and SQLite, and go-webauthn/webauthn v0.10 for FIDO2/WebAuthn. JWT session tokens are issued with configurable signing via an internal key manager or AWS KMS for external key management. Redis is used for distributed rate limiting (go-redsync) and flow locking. Frontend elements are built with Preact — not React — compiled as native browser custom elements via @teamhanko/preact-custom-element, with @denysvuika/preact-translate handling contextual i18n. The frontend SDK is plain TypeScript. The build system uses Go toolchain for the backend and Turborepo for the frontend monorepo. CI/CD runs via GitHub Actions including CodeQL analysis.

Code Quality

The backend has extensive test coverage with more than fifty test files using Go’s native testing package with testify suites, database fixtures, and HTTP-level mocking via h2non/gock. Handler tests cover success and error paths, and flow action tests validate state transitions. The flow_api shared package defines structured error types and named constants for all state, action, and stash key names, reducing magic strings. Error handling is explicit throughout, with zerolog providing structured, leveled logging. The frontend includes Jest-based tests for the SDK. CI runs CodeQL for security scanning and automated config JSON schema generation ensures documentation stays in sync with configuration structs.

What Makes It Unique

FlowPilot is genuinely novel in the authentication space — modeling authentication as a serializable, resumable state machine means that flows are not just HTTP request sequences but first-class database objects with defined transitions, making them distributable, auditable, and configurable at runtime. The Preact web component approach allows Hanko Elements to be used in any framework without wrapper libraries, with Shadow DOM encapsulation and CSS variable theming. The composite device trust system stores multiple user-device bindings per cookie without server-side session records, with automatic legacy format migration. The AMR (Authentication Methods References) claim in session JWTs lets relying parties inspect exactly how a user authenticated — passkey, TOTP, password, SSO — enabling fine-grained access policy enforcement downstream.

Self-Hosting

Hanko’s backend is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), while the frontend elements and SDK are MIT-licensed. The AGPL is a strong copyleft license — you can use it commercially and modify it freely, but if you run it as a network service and distribute a modified version, you must release your modifications under the same license. For teams that cannot comply with AGPL’s copyleft terms, the Hanko team offers non-copyleft commercial licensing on request, making it viable for proprietary SaaS use cases.

Self-hosting Hanko requires running the Go backend alongside a supported database (PostgreSQL recommended for production, MySQL or SQLite for development) and optionally Redis for distributed rate limiting and flow locking. SMTP must be configured for email delivery. Infrastructure needs are modest by authentication platform standards — a single backend container handles significant traffic — but you own all operational concerns: uptime, database backups, certificate rotation, security patching, and capacity planning. Docker Compose configurations and Kubernetes manifests with Helm charts are provided, easing initial deployment.

The managed Hanko Cloud offering handles all infrastructure, including high availability, automatic updates, managed database backups, and support SLAs. Self-hosters trade this operational convenience for full data ownership and no per-MAU pricing. Cloud also provides a more streamlined onboarding experience and faster access to new features before they reach official releases. Security notification and webhook delivery reliability in self-hosted setups depends on your own email and networking infrastructure, whereas Cloud manages these reliably out of the box.