Skip to main content

Authentication Methods

One of the core features of Hanko Identity is that authentication flows are entirely passwordless. Instead, authentication with Hanko Identity relies on Passlinks and FIDO®2/Web Authentication.

Passlinks are a form of passwordless authentication that is similar to the use of one-time passwords (OTP) in common password recovery flows. Users provide an email address and request an operation that requires authentication - this can be a login or verification after account creation. After the user clicks the Passlink that is sent to her email is then immediately authenticated - no (one-time) password use and no need for password resets.

FIDO®2/Web Authentication

FIDO®2/Web Authentication provides strong multi-factor authentication based on public-key-cryptography. Rather than using shared secrets like passwords, cryptographically-backed hardware devices, called authenticators, generate public/private key pairs. Private key material stays on the authenticator device in possession of the end-user and only public key information is stored on the server side. The authentication flow itself is based on a challenge-response mechanism where the server issues a cryptographic challenge that is then signed by the authenticator. Private keys used for this signing process can be used only after they are unlocked locally on the device by the user by, for example, providing a PIN, fingerprint, or a face scan.

There are two requirements for authenticating with Hanko Identity using WebAuthn:

  1. The user must be in possession of a device that can serve as an authenticator which is able to store key material and perform the necessary cryptographic operations. Almost all modern end-user devices nowadays have built-in hardware elements (e.g. TPMs, Secure Elements) and implementations (Windows Hello, Apple's Touch ID/Face ID, Android Biometrics) that provide and leverage these capabilities.
  2. The user must use a browser that implements the Web Authentication API. Luckily, WebAuthn adoption has come a long way and most browsers now support the API.
  3. The user must first register WebAuthn credentials with Hanko Identity using an authenticator and browser.

The following sections provide an overview of how Hanko Identity uses Passlinks and FIDO®2/Web Authentication in the context of Registration and Login flows.

Registration

Create an account

To register an account in a self-service manner users first provide basic identity information (first name, last name and email address) through an account creation form:

Hanko Identity account creation form
Figure 1: Creating an account with Hanko Identity

After submitting the account creation form, Hanko Identity can send an account verification message containing a Passlink to the provided email address. By default this feature is deactivated.

Hanko Identity account creation form
Figure 2: Creating an account with Hanko Identity
Verification email for activating account with Hanko Identity
Figure 3: Verification email for activating account with Hanko Identity

Opting into WebAuthn-based authentication

After using/clicking the Passlink in the account verification message, Hanko Identity considers the user authenticated, creates a session and issues a session cookie. It then automatically performs a check on the user's browser's WebAuthn capability. If it supports WebAuthn, an opt-in view that allows registration of a WebAuthn credential will be shown.

WebAuthn intercept
Figure 3: Opt-in view for registering a WebAuthn credential

If the user decides to register a WebAuthn credential with her device a browser prompt asks for interaction with the authenticator device (PIN, fingerprint, or the like) to complete credential registration.

WebAuthn prompt
Figure 4: WebAuthn authentication prompt in Google Chrome browser on a MacOS

Once a user has registered a WebAuthn credential via opt-in view (or through their Hanko Identity profile page) the browser will remember credential data so that it is automatically used during the next login.

WebAuthn credentials and browser cookies

Remembering credentials is handled through browser cookies. This means that

  • Registered credentials are only automatically used on future logins when using the exact same browser that was used for registering the credentials.
  • Clearing browser cookies removes the credential data and, even though the user still might have a registered credential (i.e. has not removed this credential in the Hanko Identity user profile), available credentials can no longer be identified and used to automatically trigger login with the credential.

To re-enable WebAuthn login, the user needs to remove the device and re-register it on their profile page in Hanko Identity.

Users can also choose to

  • Skip WebAuthn credential registration at this point. When skipping, the opt-in view will be shown again on future logins to remind the user of the availability of the possibility to use WebAuthn.
  • Permanently disable the WebAuthn opt-in view (Don't ask again). This does not prevent users from registering WebAuthn credentials but only disables the opt-in view. Users will be able to register credentials in their Hanko Identity profile.
Opt-in view choices and browser local storage

Hanko Identity uses the browser's local storage to remember user choices regarding the display of the WebAuthn opt-in view. If the user clears the local storage, this information is lost and the opt-in view will be shown to the user again, regardless of past choices.

Login

To log in with Hanko Identity users must provide their email address through a simple login form:

Hanko Identity login form
Figure 5: Hanko Identity login form

Login with WebAuthn

If the user has registered a WebAuthn credential (either through the opt-in or through the Hanko Identity profile page) and WebAuthn credential data is available through the user's browser's cookies, then a WebAuthn based authentication will be triggered and the user will be shown a browser prompt for interacting with their device to complete the login process.

If the user has not yet registered a WebAuthn credential or WebAuthn credential data is available through the user's browser's cookies (e.g. if cookies were cleared manually), then Hanko Identity will automatically trigger delivery of an email that contains a Passlink.

Hanko Identity passlink login mail
Figure 6: Hanko Identity passlink login mail
On Passlink message templates

You might have notice that contents of Passlink login and verification messages slightly differ. Hanko currently provides default message templates for login and verification. Template customization is planned for a future release of Hanko Identity.