Hanko 1.0

[FlxMgdnz]

We are excited to release Hanko 1.0 today. 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 e-mail 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	New
emails.max_num_of_addresses	email.limit
emails.require_verification	email.require_verification
passcode.ttl	email.passcode_ttl
smtp	email_delivery.smtp
passcode.email.from_name	email_delivery.from_name
passcode.email.from_address	email_delivery.from_address
password.min_password_length	password.min_length
webauthn.user_verification	passkey.user_verification
webauthn.timeout	webauthn.timeouts.registration
webauthn.timeout	webauthn.timeouts.login

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

Caution

Some of the new configuration parameters are not compatible with older versions of Hanko Elements (< v1.0). To ensure smooth operation, Hanko Elements v1.0 or higher should be used with the new configuration parameters.

Caution

The new configuration parameters email.enabled, email.use_for_authentication and passkey.enabled also disable the REST API endpoints if set to false, but Hanko Elements before v1.0 does not know how to deal with that and will throw an error.

Frontend

Events

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

What's Changed

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

New Contributors

• @Fohlen made their first contribution in Update package.json #1504

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

---

This discussion was created from the release Hanko 1.0.