This implementation guide will teach you how to quickly get up an running with WebAuthn and the Hanko API. You will learn how to
- register a credential
- authenticate with a registered credential and
- manage credentials with the Hanko API
Before you begin, there are some prerequisites that must be met.
Setting up your account & project
First, you need to set up an account with Hanko. This includes setting up an organization and an Authentication API project. 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 Authentication API tenant 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.
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 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:
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).