We are excited to release Hanko 1.0 today. After two years in Beta, the new Hanko is more user-friendly, more customizable and more mature than all previous releases in almost all areas and finally deserves the 1.0 version number.

Highlights

Options, options, options

• Identifiers and auth methods can be enabled individually and freely combined, no more implicit settings
• Optional passwords that can be deleted by the user, i.e. give users the choice to select a password or a passkey as their preferred authentication method
• Smooth migration of existing users, e.g. transition from a password-based system to passkeys, without overburdening all users at once

Usernames

• Usernames are now supported as identifiers, in addition to email addresses
• Emails and usernames can also be used simultaneously

Privacy

• Configurations that use the email identifier and require email verification now effectively prevent email enumeration, enabling a fully privacy-preserving implementation of login and registration
• A setting to disable "privacy mode" for situations where explicit feedback to the user (e.g. "An account using this email address already exists.") is more important than privacy is planned for a future release

Dedicated login and registration flows

• Login and registration flows have been separated to present only relevant actions to the user, e.g. "Sign in with a passkey" makes no sense for a user who wants to register a new account
• Introducing new elements <hanko-login> and <hanko-registration> that can be placed on separate pages, e.g. /login and /registration
• Combined <hanko-auth> element is still available, allowing users to toggle between login and registration on the same page

Introducing the all-new Flow API

This version contains a new API, which we call Flow API (#1532). With the previous RESTful API of the Hanko backend, it had become very complex to extend the functionality of Hanko. This was mainly due to the fact that most of the state handling was done in Hanko Elements and each endpoint had to be called in a specific order to work properly. The Flow API takes over this complexity completely in the backend and thus enables us to further develop the Hanko system at a higher speed than ever before.

• This 1.0 release includes the Flow API as well as the completely redesigned Hanko Elements to match the Flow API
• Flow API consists of three new endpoints: /registration, /login, and /profile
• A number of new email templates have been introduced to provide better context for users
• Old API endpoints handling login and registration will be deprecated, but will continue to work for the foreseeable future to allow a smooth transition to the Flow API
• A frontend SDK and documentation for the creation of custom frontends for the Flow API will follow shortly

New config options

Flow API supports much more granular settings to control the login and registration flows. The following is a sample configuration containing the most important new settings:

debug: false
convert_legacy_config: false

email:
  enabled: true
  optional: false
  acquire_on_registration: true
  acquire_on_login: true
  require_verification: true
  use_as_login_identifier: true
  use_for_authentication: true
  limit: 5
  max_length: 100
  passcode_ttl: 300

username:
  enabled: false
  optional: true
  acquire_on_registration: true
  acquire_on_login: false
  use_as_login_identifier: true
  min_length: 3
  max_length: 32

password:
  enabled: true
  optional: false
  acquire_on_registration: always
  acquire_on_login: never
  recovery: true
  min_length: 8

passkey:
  enabled: true
  optional: true
  acquire_on_registration: always
  acquire_on_login: always
  user_verification: preferred
  attestation_preference: direct
  limit: 10

Migration

Config

With the introduction of the new configuration parameters, some old parameters have become obsolete and the new parameters should be used in future if the default values are not sufficient (default values have not changed):

Old config files can still be used, but the convert_legacy_config parameter must be set to true.

Frontend

Events

• onAuthFlowCompleted events have been removed (use onSessionCreated instead)
• onSessionCreated contains the session JWT, but not the user ID anymore

Check session state

The element will no longer check if a session has already been established, and the "You're already logged in" page has been removed. This change was necessary to enable re-authentication in future versions. You can check if a user is already logged in using the following code:

import {register} from "https://cdn.jsdelivr.net/npm/@teamhanko/hanko-elements/dist/elements.js"

const {hanko} = await register("https://...");

if (hanko.session.isValid()) {
	// user is already logged in
} else {
	// show auth component
}

What's Changed

• feat: add webhook env var decoder by @lfleischmann in #1515
• Update package.json by @Fohlen in #1504
• ci: suspend e2e test automation by @lfleischmann in #1550
• Introduce Flowpilot - integration by @bjoern-m in #1532
• Update roadmap by @FlxMgdnz in #1541
• fix: don't show onboarding for already existing credentials by @bjoern-m in #1559
• docs: update config reference links by @lfleischmann in #1557
• fix: respect length requirements username by @FreddyDevelop in #1560
• chore: update default config, adjust and re-generate json schema by @bjoern-m in #1556
• fix: hopefully fix thirdparty for cross-domain by @FreddyDevelop in #1562
• Chore change database parameters by @FreddyDevelop in #1564

New Contributors

• @Fohlen made their first contribution in #1504

Full Changelog: backend/v0.12.0...backend/v1.0.0