Hanko: self-hosted authentication with passkeys, MFA and SAML SSO

What Hanko actually solves, and who it is aimed at

Authentication is the part of a product that nobody wants to build twice and nobody can afford to build badly. Hanko targets that gap with a Go backend that issues JWTs, manages users and sessions, and speaks the protocols behind passwords, passcodes, passkeys, OAuth SSO and SAML enterprise SSO. The README frames the project as an open source alternative to Auth0, Clerk, WorkOS and Stytch, and lists self-hosting and Hanko Cloud as the two deployment routes.

The audience is narrower than "anyone who needs login". The repository ships a backend, a set of web components called Hanko Elements, a frontend SDK, a quickstart app, and framework examples. That layout assumes an engineering team that can run a service and a database, and that wants either drop-in components or direct API access. If you are a solo developer who wants a hosted dashboard and nothing else, the self-hosted path asks more of you than the managed one. If you are a platform team that has been told to stop sending user records to a third party, the pitch is more obvious.

The privacy framing in the README is specific rather than decorative: data minimalism and phishing resistance. Passkeys are the mechanism behind the second claim, since a WebAuthn credential is bound to an origin and cannot be replayed against a lookalike domain the way a password can. Data minimalism is a design stance rather than a feature you can switch off, and the README does not enumerate which fields the backend stores, so treat that as something to check in the API reference before you commit.

The three building blocks and how a login flows through them

The README splits the project into a backend, Hanko Elements, and the frontend SDK. The backend is described as an authentication API for passwords, passkeys, email passcodes, OAuth SSO, user and session management, and JWT issuing. Hanko Elements are web components that provide onboarding, login and user profile screens, styled with CSS. The frontend SDK is the client package the components are built on, and the README says it handles communication with the backend API and saves you from writing that layer yourself.

The data flow follows from that split. A browser loads a web component, the component calls the backend through the SDK, and the backend returns a JWT and establishes a server-side session. Sessions are server-side and the README lists remote session revocation, which means an operator can invalidate a session without waiting for a token to expire. That is a meaningful difference from stateless-only designs, where revocation means rotating signing keys or maintaining a denylist.

The README also states that the API handles all authentication and onboarding flow states, which is the part that matters if you plan to build your own UI. Flow state on the server means the client does not have to reconstruct where a user is in a multi-step process such as passcode verification followed by MFA enrollment. The cost is that your frontend is coupled to the backend's notion of a flow, so a custom UI is a supported path but not a free one.

MFA covers TOTP and security keys. Webhooks are listed as available, which is the usual way to react to user creation or login events without polling. i18n and custom translations are available too, so the component strings are not fixed to English.

Installing Hanko and running the quickstart stack

The README gives two local options. Bare metal means following the backend README to get the API running for your own project, or using Hanko Cloud for a hosted backend. Docker means running the quickstart, which the README says creates everything including frontend and backend components.

Start with the quickstart, because it is the only path the README describes end to end. From the repository root, the quickstart README is the entry point:

cd quickstart
cat README.md

The README points at deploy/docker-compose/quickstart.yaml for the compose file and deploy/docker-compose/config.yaml for the backend configuration. If you want only the backend, the README says you can edit quickstart.yaml to remove the services you do not need. That is the moment to make decisions about your database, since the compose file is what wires the backend to its dependencies.

Once the stack is up, the integration step is the web component. The README directs you to Hanko Elements and to the framework guides in the documentation. The component package is published on npm as @teamhanko/hanko-elements, and the SDK as @teamhanko/hanko-frontend-sdk, both named in the README's badge section. If you prefer your own UI, the README says you can skip the components and use the frontend SDK directly against the backend API.

The quickstart app itself lives in quickstart/ and the README describes it as a reference implementation showing the login experience. That is the honest way to read it: a working example to copy patterns from, not a production deployment. The README does not describe a hardened production topology, so treat the compose file as a starting point and review it against your own requirements.

Where Hanko is the wrong tool

The feature table is the clearest limitation. Organizations, roles and permissions are marked as in progress, along with a hanko-menu web component and iOS, Android, React Native and Flutter SDKs. If your product needs multi-tenant role models today, Hanko's own README says that work is not finished. You would be building authorization on top of an authentication system that does not model it yet.

The second constraint is the licence split. Hanko Elements and the frontend SDK are MIT. Everything else in the repository, including the backend, is AGPL-3.0, with non-copyleft commercial licensing available on request. That is a deliberate boundary: the client-side code is permissive so it can sit in any frontend, while the server is copyleft. If your plan is to embed a modified backend in a closed product, the README's answer is to ask about commercial licensing rather than to assume the AGPL will not apply. This is not legal advice, and the terms that matter are in the LICENSE file and whatever agreement you sign.

The third constraint is operational. A server-side session store and a user database are state. The README does not describe a stateless deployment mode, so you are signing up to run and back up a database, not just a container. Teams that picked a hosted identity provider precisely to avoid that obligation will not find relief here.

Finally, the README's own framing is a caution. It advertises an easy integration and a demo booking link in the same breath. The engineering documentation lives at docs.hanko.io, moved to its own repository. If you need depth on a specific flow, the main README will not provide it.

Hanko versus Keycloak, and versus a hosted identity provider

The comparison people search for is Hanko against Keycloak. Both are self-hostable and both cover SSO, but the architectural emphasis differs. Keycloak is a general identity and access management server that has historically centered on OIDC and SAML federation, with a Java runtime behind it. Hanko is written in Go, and the README positions it around modern authentication methods first: passkeys, passcodes, MFA with TOTP and security keys, and OAuth SSO, with SAML enterprise SSO listed as available. Hanko also ships opinionated frontend components, which Keycloak does not; with Keycloak you supply the login UI or theme its own.

The practical difference shows up in what you write. With Hanko, the README's path is to drop in Hanko Elements or call the frontend SDK against a backend that tracks flow state. With Keycloak, the integration is a standards-based redirect flow and the customization work sits in themes and realm configuration. Neither is strictly better; they optimize for different starting points.

Against hosted providers such as Auth0, Clerk, WorkOS or Stytch, the difference is where the data and the operational burden live. Hanko Cloud exists for teams that want the managed route, but the repository's core offer is the self-hosted backend. That means you own the database, the upgrades and the incident response. In exchange, user records stay on your infrastructure, which is the reason most teams consider this class of tool in the first place. The README's data minimalism claim is part of that trade, though as noted it is a stance rather than a documented field-by-field guarantee.

Maintenance, releases and the cost of upgrading

The repository is not archived and the last push was on 2026-09-18, three days before this writing, so the project is being worked on. Releases are versioned per component: backend/v3.0.4 landed on 2026-07-27 and is titled "Hanko v3: Multitenancy", backend/v2.7.0 on 2026-06-05 covers Firebase user and password hash import, and backend/v2.6.0, also 2026-06-05, adds inactivity logout.

Two things follow from that list. First, the backend carries its own version line, so upgrade planning happens at the backend level rather than the repository level. Second, a major version boundary between v2 and v3 is where you should expect the real work, and the v3 title suggests the multitenancy change is structural rather than cosmetic. The README does not document the v2 to v3 upgrade path, so check the release notes before planning it.

The import feature in v2.7.0 is worth noting for a different reason. Migrating password hashes out of Firebase is the kind of task that usually blocks an identity migration, and having it as a named release suggests the project treats migration as a first-class concern. Whether the import covers every hash format you have is not something the README answers.

The licence cost is the other recurring expense. AGPL-3.0 on the backend means the obligations attach to the server component, not the MIT-licensed frontend packages. If your distribution model interacts with that, the README's stated route is to request non-copyleft commercial licensing. Budget for that conversation early rather than after a launch.

Editorial conclusion

Hanko fits teams that want to keep authentication data on their own infrastructure and are willing to run a Go service and a Postgres-compatible database. It is the wrong choice if you need organizations, roles and permissions today, since the feature table lists them as in progress, or if the AGPL-3.0 licence on the backend conflicts with how you ship. Before adopting, verify the licence terms for your distribution model, check the backend README for the database and configuration requirements, and confirm that the authentication methods you need are marked as available rather than planned.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. teamhanko/hanko on GitHub