Skip to content

Releases: teamhanko/hanko

Hanko 2.5

03 Mar 08:17
@FlxMgdnz FlxMgdnz
backend/v2.5.0
93ddddc
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Hanko 2.5 Latest
Latest

This release improves user profile handling, enhances session token transparency, and includes important security fixes.

New Features

Name and Picture Attributes for Users (#2417)

Users can now store name and picture attributes directly in Hanko.

This allows:

  • Richer user profiles
  • Better OIDC compatibility
  • Easier frontend integrations that expect display name and avatar fields

These attributes follow standard OIDC conventions, are available via the API, and can be managed like other user properties. The main source for these properties will be 3rd-party accounts like Google or GitHub for now. We will add the required functionality to manage these fields to the profile element in a later update.

AMR Values in Session Tokens (#2429)

Session tokens now include AMR (Authentication Methods References) values.

This enables relying parties to:

  • Inspect how a user authenticated (e.g. passkey, password, MFA)
  • Improve auditability and policy decisions

The AMR claim follows standard OIDC conventions.

Extended /me Endpoint (#2442)

The /me endpoint has been extended to return additional user information.

This reduces the need for follow-up requests and simplifies frontend integrations that rely on a single user introspection endpoint.

Bug Fixes

Prevent SQL Injection in audit_logs Queries

Replaced string concatenation with prepared statements when querying audit_logs.
This prevents potential SQL injection attacks and strengthens overall security.

Security Notification Webhooks Fixed

Security notification webhooks were not triggering correctly in certain scenarios.
This has been fixed and webhooks now work as expected.

What's Changed

New Contributors

Full Changelog: backend/v2.4.0...backend/v2.5.0

Contributors

FreddyDevelop, lfleischmann, and jaffarkeikei
Assets 10
Loading

Hanko 2.4

20 Jan 14:59
@FlxMgdnz FlxMgdnz
backend/v2.4.0
17375e5
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Hanko 2.4

This release brings several security, reliability, and usability improvements across Hanko’s authentication stack. It includes stronger passcode options, better key management integration, more robust auth flows in Hanko Elements, improved device trust handling, and expanded localization support:

Alphanumeric passcodes

In addition to numeric passcodes, Hanko now supports optional alphanumeric passcodes. This increases entropy and makes passcode-based authentication more resilient against brute-force and guessing attacks.

External key providers (AWS KMS)

Hanko’s token signing engine can now be configured to use external HSMs and Key Management Systems, currently only AWS KMS is supported. This allows teams with higher security requirements to keep signing keys fully managed outside of Hanko.

Security notifications

Hanko now optionally sends email notifications for security-relevant actions (enabled by default), for example when a new passkey is added to an account. These notifications help users detect suspicious activity early and improve overall account security.

PKCE by default in Hanko Elements

Hanko Elements now uses PKCE-based flows by default. This resolves several issues with third-party integrations, especially in setups where the backend is not running on the same domain as the frontend.

Multi-user device trust support

Device trust cookies are no longer overwritten on shared machines or when multiple users log into the same application. This improves reliability for shared computers and multi-account setups while keeping device trust intact per user.

Dutch localization

Hanko now officially supports Dutch (NL). This includes UI text, backend mailing templates, and security notification emails, providing a more complete localized experience for Dutch-speaking users.

What's Changed

New Contributors

Full Changelog: backend/v2.3.0...backend/v2.4.0

Contributors

fadlikadn, irby, and 3 other contributors
Loading
0 Join discussion

Hanko 2.3

03 Dec 09:01
@FlxMgdnz FlxMgdnz
backend/v2.3.0
721dd2b
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Hanko 2.3

This release brings several updates to Hanko’s 3rd party (OAuth, OIDC) integration:

  • Authenticated users can now connect and manage configured 3rd party identities directly in the profile
  • Added support for OIDC ACR request parameter to enable custom communication between the 3rd party and Hanko
  • 3rd party identities no longer have to return an email address

What's Changed

Full Changelog: backend/v2.2.1...backend/v2.3.0

Contributors

FreddyDevelop
Loading

Hanko 2.2.1

13 Nov 14:28
@FlxMgdnz FlxMgdnz
backend/v2.2.1
3a04cef
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Hanko 2.2.1

A smaller release, but with some important fixes and improvements. Most notably:

  • Flow locking mechanism to prevent concurrent execution of the same flow, addressing possible race conditions and side effects in actions (setting header tokens, sending emails, ...) in concurrent request scenarios
  • Option to configure (or omit) the 3rd-party prompt parameter to fine-tune the social SSO UX
  • Hanko Elements attributes working again (e.g. prefilled email or the mode attribute)
  • Hanko Elements UI fixes

What's Changed

Full Changelog: backend/v2.2.0...backend/v2.2.1

Contributors

FreddyDevelop and lfleischmann
Loading

Hanko 2.2: PKCE

28 Oct 15:18
@FlxMgdnz FlxMgdnz
backend/v2.2.0
64abc8f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Hanko 2.2: PKCE

PKCE (Proof Key for Code Exchange)

The main feature of this release is PKCE support for 3rd-party OAuth flows of the Hanko API. When using Hanko with a mobile app, the oauth_state cookie might not be stored, so the thirdparty_oauth action now accepts a code_verifier. When the code_verifier ist set, the state cookie is optional, but the code_verifier is required when exchanging the Hanko token with the exchange_token action.

What's Changed

Full Changelog: backend/v2.1.1...backend/v2.2.0

Contributors

FreddyDevelop and lfleischmann
Loading

Hanko 2.1.1

28 Aug 07:35
@FlxMgdnz FlxMgdnz
backend/v2.1.1
2a1f259
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Hanko 2.1.1

This release includes a license change along with several improvements and fixes.

License change

  • The proprietary enterprise license in the /ee folder has been removed.
  • Hanko Backend is now fully licensed under AGPLv3.

Hanko Elements visual improvements

We’ve refined the look and feel of <hanko-auth>, <hanko-login>, and <hanko-registration>:

  • Passcode views: user’s email address is now highlighted.
  • Social SSO buttons:
    • Logos and text (e.g. “Sign in with Google”) are now centered.
    • Order updated: SSO buttons now appear first, with the passkey option listed last.
    • Passkey button icon removed for clearer visual separation from SSO options.
  • Login/registration switch UI in :
    • Now centered at the bottom of the element (previously right-aligned).
    • Text and link split for clarity — the prompt (e.g. “Already got an account?”) is separate from the action link (e.g. “Sign in”), making the link more prominent.

Hanko Elements nonce property added

  • Added an optional nonce property to Hanko Elements.
  • This enables a stricter Content Security Policy (CSP) without requiring unsafe-inline.
  • Improves overall security posture by allowing Hanko Element's inline styling in combination with a stricter CSP when a valid nonce is provided.

What's Changed

Full Changelog: backend/v2.1.0...backend/v2.1.1

Contributors

loeffert, FlxMgdnz, and FreddyDevelop
Loading

Hanko 2.1: User Metadata

21 May 10:05
@FlxMgdnz FlxMgdnz
backend/v2.1.0
891cc2c
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Hanko 2.1: User Metadata

We are excited to announce the release of Hanko 2.1!

This release builds on the foundation laid by Hanko 2.0 and introduces new customization capabilities, component enhancements, and bug fixes to improve the overall developer experience.

New: Customizable User Metadata

Hanko now supports user metadata that can be attached to user profiles and managed via the Admin API. Metadata is organized into three categories:

Metadata type Public API Admin API
Private No read or write access Read and write access
Public Read access Read and write access
Unsafe Read access and write access Read and write access

Metadata can be accessed in session JWT templates to map metadata to claims in a session token.

See backend README for full details and examples.

<hanko-auth> Mode Attribute

The <hanko-auth> Web Component now supports a mode attribute, allowing you to explicitly control whether it starts in login or registration mode.

Example:

<hanko-auth mode="registration"></hanko-auth>

This makes it easier to integrate the <hanko-auth> Element into a range of different onboarding flows.

Bug Fixes and Improvements

  • Cross-tab communication fix: Cross-tab session events are now reliably synchronized. A bug caused by a mismatched broadcast channel name has been resolved.
  • User type consistency fix: The /user REST endpoint now returns the correct structure expected by the frontend SDK.
  • General improvements: Minor fixes and internal enhancements to improve stability and maintainability.

Full Changelog: backend/v2.0.0...backend/v2.1.0

Loading

Hanko 2.0

29 Apr 15:40
@FlxMgdnz FlxMgdnz
backend/v2.0.0
404e52f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
Hanko 2.0

We are excited to announce the release of Hanko 2.0!

The main highlight of this release is the completely redesigned JavaScript SDK, built to work seamlessly with our Flow API introduced in version 1.0. This new SDK brings major improvements in flexibility, developer experience, and frontend state management when building custom UI using the Hanko API.

New JavaScript SDK

  • New State Management: Introduces the State class for handling flow states, complete with event hooks (onBeforeStateChange, onAfterStateChange), serialization to localStorage, and auto-stepping through flows.
  • Action Execution: Provides a new Action class for type-safe action invocation within authentication flows.
  • Passkey Autofill Support: Integrates passkey autofill activation handlers for supported states.
  • Persistence: Flow state persistence via localStorage, improving UX across sessions.

Example usage:

const hanko = new Hanko(/* params */);
const state = await hanko.createState("login");

await state.actions.continue_with_login_identifier.run({
  username: "user",
});

hanko.onBeforeStateChange(({state}) => {
  console.log(`Action invoked: ${state.invokedAction.name}`);
});

hanko.onAfterStateChange(({state}) => {
  console.log(`Action finished: ${state.previousAction.name}`);

  if (state.name == "login_init") {
    state.passkeyAutofillActivation();
  }
});

Note

The new frontend SDK introduces breaking changes: If you are using a custom frontend based on the previous SDK, please review the SDK docs carefully. We also provide a guide on how to use the SDK to build a custom UI for the Flow API.

Updated Session Management Access

  • The session management functions are now directly available on the top-level Hanko instance:
    • getUser()
    • validateSession()
    • getSessionToken()
    • logout()
  • Previously, these functions were accessed through individual clients, which have now been removed.
  • This change simplifies session handling and aligns with the overall SDK cleanup.
  • Example code and documentation have been updated accordingly.

SDK Cleanup

  • Removed deprecated clients (EmailClient, ThirdPartyClient, EnterpriseClient, TokenClient) and outdated session handling logic.
  • Simplified configuration management by unifying internal options.
  • Removed obsolete DTOs and related tests.

Backend Compatibility

There are no major changes to the backend compared to version 1.5.2. Updating the backend to use the new JavaScript SDK is not mandatory if you are currently on v1.5.2. However, we recommend upgrading to the latest backend version, as running the new frontend SDK with an older backend version is not officially supported and may lead to unexpected issues.

Custom Session Claims

Custom claims can now be added to the session token. A new configuration option, session.jwt_template, has been added that allows defining session.jwt_template.claims. Values can be arbitrarily nested and can use Go text templates.

The custom claims are also added to sessions/validate endpoint responses.

New Session Token Storage Option

A new option sessionTokenLocation was added to the HankoOptions configuration. You can now choose where the session token is stored on the client:

  • cookie (default) — persists across tabs and sessions.
  • sessionStorage — session ends automatically when the browser tab is closed.

This allows finer control over session lifetime, improving security for sensitive applications.

Tip

Use sessionStorage if you want user sessions to automatically end when a tab or browser window is closed.

Example configuration:

const hanko = new Hanko("https://your-hanko-instance", {
  sessionTokenLocation: "sessionStorage", // ends session on tab close
});

Note

This setting only works when session.enable_auth_token_header: true is set.

New Contributors

Full Changelog: backend/v1.5.2...backend/v2.0.0

Thanks to everyone who contributed to this release! 🫶
We are looking forward to your feedback and contributions.

Contributors

franklinkim
Loading
0 Join discussion

v1.5.1

31 Mar 13:22
@FlxMgdnz FlxMgdnz
backend/v1.5.1
caa46a0
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v1.5.1

This release introduces more changes to the way the login flow reacts to the new privacy settings.

If onlyShowActualLoginMethods is enabled:

  • Existing passkeys also show up as an option in login method chooser that is displayed after a user enters their email address or username in the login form
  • If a passkey is the only available option for a user, the device's passkey UI flow is automatically triggered
  • In contrast to the “Sign in with a passkey” button on the main login page, where all passkeys available on the device are displayed, the passkey selection triggered from the login method chooser is limited to the passkeys assigned to the user for whom the email address or user name was entered in the first step

What's Changed

Full Changelog: backend/v1.5.0...backend/v1.5.1

Contributors

FreddyDevelop and lfleischmann
Loading
0 Join discussion

v1.5: Privacy settings, HTML emails, improved sessions

14 Mar 13:43
@FlxMgdnz FlxMgdnz
backend/v1.5.0
09adeb1
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v1.5: Privacy settings, HTML emails, improved sessions

This release contains new features and a handful of important bug fixes.

Privacy settings

Two new settings have been added to control whether the disclosure of information about user accounts should be accepted for the sake of usability:

  • showAccountExistenceHints: When registering or trying to log in, feedback is displayed indicating whether or not an email address already exists (e.g. “The email is already taken.” or “The email address is unknown.”). When disabled, the system hides this information and behaves identically in both cases to avoid disclosing information about existing email addresses (this has previously been the default behavior).
  • onlyShowActualLoginMethods: Only display the authentication methods that are actually available to a user during the sign-in process (e.g. after the user enters an e-mail address as the identifier in the sign-in form, only prompt the user for a password if they actually have one). If disabled, all theoretically possible authentication options are always displayed to avoid disclosing information about existing email addresses (this has previously been the default behavior).

Please note: Full protection against email enumeration attacks is only provided if both settings, “Show account existence hints” and “Hide unavailable login methods” are disabled. Please note that this may result in a poorer user experience, as users will no longer receive direct feedback if, for example, they have entered an incorrect email address, or if they are suggested the option to enter a password even though they do not have one.

HTML emails

This version adds support for HTML email rendering and delivery alongside plain text emails. The changes ensure that both plain text and HTML versions of passcode and notification emails are generated and sent, improving email formatting and readability across different clients. We will further improve the styling of the HTML emails in a future patch.

Improved session handling in Hanko Elements

  • Session management overhaul
    • Added periodic session validation with customizable intervals.
    • Added inter-tab communication for session events.
    • Enhanced tracking of window focus and visibility to ensure session validation occurs only in active tabs, improving performance.
  • Session created event updates
    • Removed optional jwt field and deprecated expirationSeconds.
    • Token claims are now included in "session-created-event" and shared across tabs/windows.
    • The JWT remains accessible via the session cookie if httpOnly is set to false.
  • Deprecation notice
    • Deprecated hanko.session.is_valid() (now blocking, mimics await hanko.sessionClient.validate()).
    • Recommend using non-blocking hanko.sessionClient.validate() instead.
  • Local storage optimization
    • Eliminated the need to store the JWT to the local storage.

Updated Go version

Hanko is now using Go version 1.24. Please note this if you want to compile the Hanko backend code.

What's Changed

Full Changelog: backend/v1.4.0...backend/v1.5.0

Contributors

FreddyDevelop, bjoern-m, and lfleischmann
Loading
0 Join discussion