Skip to main content

Introduction

This implementation guide will teach you how to quickly get up an running with WebAuthn and the Hanko API. You will learn how to

Prerequisites#

Before you begin, there are some prerequisites that must be met.

Setting up your account#

First, you need to set up an account with Hanko. This includes setting up an organization and a relying party. Head over to our getting started section to learn how to set these up.

Accessing the Hanko API#

In order to use the Hanko API you need your relying party API base URL and an API Key. Head over to our "Getting started" section to learn how to obtain your API base URL and to generate an API Key. API keys are required to make authenticated calls to the Hanko API. In order to do so, you must provide an authorization header as described in the API reference.

Authenticator device#

You will also need a FIDO2/WebAuthn capable authenticator device. This can either be

  • a roaming authenticator (e.g. Yubikey)
  • a platform authenticator or (e.g. a Windows 10 device with Windows Hello, or a MacBook with Touch ID)
  • a virtual authenticator (e.g. Google Chrome's WebAuthn tools, see the official Chrome DevTools documentation for usage instructions)

Application architecture overview#

The core participants of an application that leverages the Hanko Authentication API for FIDO2/WebAuthn based authentication include:

  • The relying party: this is the website, service, or application that wants to authenticate users. A relying party environment consists of both a relying party application's frontend and backend. The frontend requires JavaScript and communicates with the Web Authentication API, the backend communicates with the Hanko API. Because the Hanko API does not manage core user entity data, the environment also includes an existing user store in order to provide user data for associating credentials with individual users.
  • The client/platform: this is the underlying platform that runs the relying party (frontend) application, e.g. a browser. It serves as a mediator between an authenticator and the relying party. The platform implements the CTAP2 protocol (the other central protocol of the FIDO2/WebAuthn protocol stack). Using CTAP2, it communicates with external authenticators via USB, NFC or Bluetooth while communication with built-in platform authenticators is accomplished through a platform specific API.
  • An authenticator: this is a hardware device that processes user input to create a credential or authenticate with a relying party using an existing credential. An authenticator can be either an external device (i.e. a roaming authenticator) or built into the platform (i.e. a platform authenticator).

The following figure shows an architectural overview of the application:

Building blocks of an application using the Hanko API
Figure 1: Architectural overview of an application leveraging the Hanko API for FIDO2/WebAuthn based authentication

In the next sections of this guide, you will learn how to implement the two ceremonies central to a WebAuthn based application: registration of a credential and authentication with a credential. Furthermore, you will also learn how to manage credentials (i.e. retrieve credentials, deregister credentials and update credentials).