Skip to content

Hanko 1.0
Compare
Choose a tag to compare
@FlxMgdnz FlxMgdnz released this 08 Aug 14:15
· 74 commits to main since this release
backend/v1.0.0
d734785
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.

release1 0_small

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 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

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

New Contributors

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

Contributors

Fohlen, FlxMgdnz, and 3 other contributors
Assets 10
Loading
0 Join discussion