v1.3: Custom OAuth, device trust, stay signed in

This update contains a variety of frequently requested features and improvements.

Custom OAuth providers

In addition to the preconfigured providers such as Apple, Google, and GitHub, we have now added the option to configure custom OpenID Connect or OAuth providers so that they appear as “Sign in with...” buttons on the login and registration pages.

Device trust

A new device trust feature offers users the option of not having to perform 2FA again for a certain period of time after successful 2FA. Administrators can specify whether to automatically trust the device, prompt the user to trust the device, or never allow trusted devices and always enforce 2FA.

Stay signed in

This new option can be used to control whether a persistent cookie or a session cookie should be issued when the user is logging in. Persistent cookies (default) remain valid for the set session duration, i.e. the user remains logged in even if the browser is closed. Session cookies are usually deleted when the browser or browser tab is closed, so users have to log in again the next time they visit the app. A third option adds a “Stay signed in” checkbox to the login screen, which allows the user to determine the type of cookie themselves.

Last used indicators

Social SSO buttons (e.g., "Sign in with Google") now display a "Last used" label to help users remember which provider they chose on their last visit and avoid creating redundant accounts. Note that active Account Linking still allows users to change the login method to some extent, but only if the email address matches.

New admin API endpoints

The Admin API has been extended with the following new endpoints:

• password
  • get
  • create
  • update
  • delete
• webauthn
  • list
  • get
  • delete
• otp
  • get
  • delete
• sessions
  • list
  • create
  • delete

User import improvements

User import functionality has been improved. Now, more user data and credentials can be imported, e.g.:

• Usernames
• Passwords (bcrypt hashes)
• WebAuthn credentials
• OTP secrets

What's Changed

• chore: re-generate example css by @bjoern-m in #1970
• feat: add session creation endpoint by @FreddyDevelop in #1969
• fix: add missing third party provider defaults by @lfleischmann in #1976
• feat: trusted devices and 'remember me' by @bjoern-m in #1982
• feat: add last used indicator to the login page by @bjoern-m in #1957
• Admin api changes by @FreddyDevelop in #1974
• chore: autogenerate config JSON schema by @github-actions in #1986
• feat: third party custom providers by @lfleischmann in #1984
• chore: autogenerate config JSON schema by @github-actions in #1989
• fix: check server side session for REST API endpoints by @FreddyDevelop in #1988
• feat: enhance jsonschema for third_party config by @lfleischmann in #1990
• chore: autogenerate config JSON schema by @github-actions in #1991
• Fix cookie name in passcode handler by @loeffert in #1625
• Feat custom user by @FreddyDevelop in #1978
• fix: remove session id from jwt on disabled server side sessions by @lfleischmann in #1993
• chore: add missing tags by @FreddyDevelop in #1994
• Feat extend user import by @FreddyDevelop in #1992
• chore: autogenerate import JSON schema by @github-actions in #1996
• chore: update versions to 1.3.0 by @FreddyDevelop in #1998
• fix: return after suspending delete session action by @lfleischmann in #2000
• chore: add same site attribute to the device trust cookie by @bjoern-m in #2006

New Contributors

• @loeffert made their first contribution in #1625

Full Changelog: backend/v1.2.1...backend/v1.3.2

v1.2: MFA

This release contains Multi-Factor Authentication (MFA) capabilities for Hanko backend and Hanko Elements.

Hanko has been optimized for WebAuthn and passkey authentication from the very beginning. However, the additional implementation of other, potentially weaker authentication methods such as passwords and email passcodes meant that we also had to add MFA (or 2FA). And here it is: TOTP authenticator apps as well as FIDO security key support.

As a bonus feature, we added the option for MFA enrollment during registration and login flows, allowing admins to easily enforce MFA adoption among their user base if required.

TOTP authenticator apps

As the de facto standard for 2FA, the most obvious benefit of Time-based One-Time Passcodes (TOTP) is their universality. Users can choose from a myriad of authentication apps such as Google Authenticator, Microsoft Authenticator and many more to generate the one-time codes – no special hardware required.

Security keys

We just had to support security keys as second factors due to their unmatched security benefits. No other MFA method can protect users as reliably against phishing and most other known account takeover attacks.

What's Changed

• fix: session delete action by @lfleischmann in #1793
• feat: introduce mfa by @bjoern-m in #1645
• chore: autogenerate config JSON schema by @FreddyDevelop in #1959

Full Changelog: backend/v1.1.0...backend/v1.2.0

v1.1: Sessions

This release introduces server-side sessions as an alternative to the previous approach of just issuing JWTs, and a bunch of smaller improvements and bug fixes.

• New config options

session:
  server_side:
    enabled: true
    limit: 5

• Sessions are stored in the DB, the JWT contains the session ID
• New /sessions endpoint to verify the JWT (instead of retrieving the JWKS and verifying the JWT yourself)
• Remote session revocation
• Sessions list in <hanko-profile>

What's Changed

• fix: chinese email template corrected by @bjoern-m in #1627
• fix(admin-api): return webauthn transports in users endpoints by @lfleischmann in #1652
• feat(admin-api): get users by multiple ids by @lfleischmann in #1653
• chore(webhooks): update webhook.go by @eltociear in #1666
• fix: password update, password service transaction handling by @lfleischmann in #1669
• ci: fix schema and markdown generation workflows by @lfleischmann in #1603
• Server side sessions by @FreddyDevelop in #1673
• chore: update versions to 1.1.0 by @FreddyDevelop in #1748
• chore: autogenerate config JSON schema by @FreddyDevelop in #1754

Full Changelog: backend/v1.0.3...backend/v1.1.0

v1.0.2

Another bug fix release. Most importantly, changing the way DB connections are used during flow transactions to avoid potential deadlocks when a large number of users initiate certain flow actions simultaneously.

What's Changed

• fix: passcode invalid error not shown by @bjoern-m in #1594
• fix: only use transaction connection in a transaction by @FreddyDevelop in #1598
• chore: update versions to 1.0.2 by @FreddyDevelop in #1599

Full Changelog: backend/v1.0.1...backend/v1.0.2

v1.0.1

This release contains some important fixes and additions to the recently released Hanko v1.0.

The most important changes are:

• Added webhook support to Flow API
• Username property is now included when retrieving the user from the SDK or the admin API
• Fixed a potential concurrency issue when new flows are created

What's Changed

• ci: no jekyll by @lfleischmann in #1568
• ci: do not create cname file on docs publish by @lfleischmann in #1569
• ci: move nojekyll file by @lfleischmann in #1570
• chore: correct broken links by @bjoern-m in #1567
• fix: fix faulity migration by @FreddyDevelop in #1571
• chore: add linkedin provider guide link in readme by @lfleischmann in #1572
• chore: add webhooks to flow-api by @bjoern-m in #1574
• Fix/email delivery by @FreddyDevelop in #1575
• fix: fix links by @FlxMgdnz in #1576
• Minor text changes and typo fixes by @FlxMgdnz in #1579
• feat: update DTO with username field by @bjoern-m in #1583
• docs: backend config and user import schema and markdown generation improvements by @lfleischmann in #1582
• feat: return complete user in admin API by @FreddyDevelop in #1581
• fix: fix email verified check for saml by @FreddyDevelop in #1589
• fix: create new flow for every request by @FreddyDevelop in #1591

Full Changelog: backend/v1.0.0...backend/v1.0.1

Hanko 1.0

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

• 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

v0.12: Sign in with LinkedIn

Highlights

• LinkedIn is now available as 3rd-party identity provider.

What's Changed

• chore(deps): bump golang.org/x/oauth2 from 0.19.0 to 0.20.0 in /backend by @dependabot in #1454
• chore(deps): bump golang.org/x/text from 0.14.0 to 0.15.0 in /backend by @dependabot in #1455
• chore(deps): bump github.com/go-playground/validator/v10 from 10.19.0 to 10.20.0 in /backend by @dependabot in #1449
• chore(deps): bump golang.org/x/crypto from 0.22.0 to 0.23.0 in /backend by @dependabot in #1456
• feat(thirdparty): add linkedin to social providers by @shentschel in #1463
• chore(deps): bump github.com/go-playground/validator/v10 from 10.20.0 to 10.21.0 in /backend by @dependabot in #1475
• chore(deps): bump github.com/rs/zerolog from 1.32.0 to 1.33.0 in /backend by @dependabot in #1465
• chore(deps): bump github.com/go-jose/go-jose/v3 from 3.0.1 to 3.0.3 in /backend by @dependabot in #1469
• chore(deps): bump golang.org/x/text from 0.15.0 to 0.16.0 in /backend by @dependabot in #1481
• chore(deps): bump golang.org/x/oauth2 from 0.20.0 to 0.21.0 in /backend by @dependabot in #1480
• feat(saml): make getting providers from metadata non-panic by @shentschel in #1464
• fix: improve passcode email text by @FlxMgdnz in #1170
• fix: mail renderer tests after text updates by @lfleischmann in #1489
• chore(deps): bump github.com/go-playground/validator/v10 from 10.21.0 to 10.22.0 in /backend by @dependabot in #1487
• chore(deps): bump goreleaser/goreleaser-action from 5 to 6 by @dependabot in #1486
• chore(deps): bump golang.org/x/crypto from 0.23.0 to 0.24.0 in /backend by @dependabot in #1478
• chore(deps): bump docker/build-push-action from 5 to 6 by @dependabot in #1494
• chore(deps): bump github.com/spf13/cobra from 1.8.0 to 1.8.1 in /backend by @dependabot in #1493
• chore(deps): bump github.com/lestrrat-go/jwx/v2 from 2.0.21 to 2.1.0 in /backend by @dependabot in #1497

Full Changelog: backend/v0.11.0...backend/v0.12.0

v0.11: Sign in with Microsoft, custom email sending

Highlights

• Microsoft is now available as 3rd-party identity provider. Admins can set up a "Sign in with Microsoft" authentication option for users in the backend config. Both personal and work accounts are supported. Learn more here.
• Custom email sending is now supported by a new webhook and the option to disable email sending through the Hanko backend. Apps can subscribe to the webhook and implement their own email sending (e.g. passcode emails).

What's Changed

• docs: add link to discord guide in backend readme by @lfleischmann in #1424
• feat(thirdparty): add microsoft provider by @lfleischmann in #1409
• Update LICENSE by @FlxMgdnz in #1432
• Update README.md by @FlxMgdnz in #1433
• chore(deps): bump github.com/labstack/echo/v4 from 4.11.4 to 4.12.0 in /backend by @dependabot in #1436
• fix: fix saml login for existing users by @FreddyDevelop in #1434
• [FEAT] disable email delivery by @FreddyDevelop in #1419
• chore(deps): bump golang.org/x/net from 0.21.0 to 0.23.0 in /quickstart by @dependabot in #1440
• chore(deps): bump github.com/labstack/echo-contrib from 0.15.0 to 0.17.1 in /backend by @dependabot in #1441
• fix: don't override error before return by @FreddyDevelop in #1447

Full Changelog: backend/v0.10.2...backend/v0.11.0

v0.10.2

Highlights

• Fix that ensures email JWT claim is present on user creation.
• Change that sets the default Passkey/WebAuthn attestation conveyance preference from 'none' to 'direct' for better AAGUID handling on Windows.

What's Changed

• fix(jwt): add updated email on user create by @shentschel in #1416
• chore(deps): bump github.com/jackc/pgconn from 1.14.1 to 1.14.3 in /backend by @dependabot in #1380
• chore(deps): bump jose from 4.15.4 to 4.15.5 in /frontend by @dependabot in #1385
• chore(deps): bump softprops/action-gh-release from 1 to 2 by @dependabot in #1389
• chore(deps): bump github.com/jackc/pgx/v4 from 4.18.1 to 4.18.2 in /backend by @dependabot in #1391
• chore(deps): bump google.golang.org/protobuf from 1.31.0 to 1.33.0 in /backend by @dependabot in #1395
• chore(deps): bump github.com/docker/docker from 24.0.7+incompatible to 24.0.9+incompatible in /backend by @dependabot in #1402
• chore(deps): bump github.com/go-sql-driver/mysql from 1.7.1 to 1.8.1 in /backend by @dependabot in #1410
• chore(deps): bump follow-redirects from 1.15.4 to 1.15.6 in /docs by @dependabot in #1399
• chore(deps): bump follow-redirects from 1.15.4 to 1.15.6 in /frontend by @dependabot in #1400
• chore(deps): bump webpack-dev-middleware from 5.3.3 to 5.3.4 in /docs by @dependabot in #1406
• chore(deps-dev): bump webpack-dev-middleware from 5.3.3 to 5.3.4 in /frontend by @dependabot in #1405
• Update README.md by @FlxMgdnz in #1408
• chore(deps): bump express from 4.18.1 to 4.19.2 in /docs by @dependabot in #1413
• chore(deps): bump express from 4.18.2 to 4.19.2 in /frontend by @dependabot in #1414
• chore(deps): bump peaceiris/actions-gh-pages from 3 to 4 by @dependabot in #1422
• Roadmap updates by @FlxMgdnz in #1411
• chore(deps): bump golang.org/x/crypto from 0.21.0 to 0.22.0 in /backend by @dependabot in #1425
• chore(deps): bump github.com/go-webauthn/webauthn from 0.10.1 to 0.10.2 in /backend by @dependabot in #1426
• chore(deps): bump golang.org/x/oauth2 from 0.18.0 to 0.19.0 in /backend by @dependabot in #1428
• enhance(webauthn): change default attestation mode by @shentschel in #1421
• chore: update versions to v0.10.2 by @lfleischmann in #1430

Full Changelog: backend/v0.10.1...backend/v0.10.2

v0.10.1

Highlights

• Email claim added to session JWT, allowing developers to quickly retrieve the user's primary email address
• New Social SSO provider: Discord

What's Changed

• chore(deps): bump github.com/go-playground/validator/v10 from 10.17.0 to 10.18.0 in /backend by @dependabot in #1342
• chore: update debug dockerfile by @lfleischmann in #1352
• chore(webhooks): improve webhook docs by @shentschel in #1351
• feat(thirdparty): add discord provider by @lfleischmann in #1353
• fix(webhooks): fix HasEvent logic by @shentschel in #1355
• chore(deps): bump github.com/lestrrat-go/jwx/v2 from 2.0.19 to 2.0.20 in /backend by @dependabot in #1358
• chore(deps-dev): bump ip from 2.0.0 to 2.0.1 in /frontend by @dependabot in #1359
• Roadmap updated by @FlxMgdnz in #1363
• feat(webhooks): add webhooks trigger to thirdparty auth by @shentschel in #1367
• chore(deps): bump golang.org/x/crypto from 0.19.0 to 0.21.0 in /backend by @dependabot in #1378
• chore(deps): bump github.com/go-playground/validator/v10 from 10.18.0 to 10.19.0 in /backend by @dependabot in #1377
• chore(deps): bump github.com/stretchr/testify from 1.8.4 to 1.9.0 in /backend by @dependabot in #1375
• chore(deps): bump github.com/gomodule/redigo from 1.8.9 to 1.9.2 in /backend by @dependabot in #1365
• chore(deps): bump golang.org/x/oauth2 from 0.17.0 to 0.18.0 in /backend by @dependabot in #1379
• chore(deps): bump github.com/lestrrat-go/jwx/v2 from 2.0.20 to 2.0.21 in /backend by @dependabot in #1386
• chore(deps): bump github.com/lestrrat-go/jwx/v2 from 2.0.19 to 2.0.21 in /quickstart by @dependabot in #1387
• Fix links in README.md by @wttw in #1407
• feat(jwt): add email claim to session JWT by @shentschel in #1404

New Contributors

• @wttw made their first contribution in #1407

Full Changelog: backend/v0.10.0...backend/v0.10.1