Now that we have registered a credential we can use it to authenticate with the Hanko API. The authentication operation is very similar to the registration operation - it's just three simple steps.
The authentication ceremony basically corresponds to logging in a user using a previously-registered credential.
- When a user requests authentication with an existing credential, your relying party application requests generation of credential request options, including a challenge to which the user must respond using a cryptographically signed statement identifying the user.
- The user provides consent through a local authorization gesture (e.g. through a PIN or biometrics) to use an existing credential's private key to create and cryptographically sign an assertion.
- The authenticator assertion response is sent to the Hanko Authentication API.
- The Hanko Authentication API validates the assertion using the stored credential public key.
Just like on registration, the first step to authenticating with a credential is to initialize the authentication ceremony. Initialization consists of retrieving credential request options from the Hanko API in order to trigger the discovery and use of an existing credential on an authenticator for generating an assertion.
In your frontend, trigger registration initialization by first making a request to your application backend. To process
the request you will need to implement a handler. In this case, we assume your backend handler responds to requests
issued to the
Your backend handler must then issue a POST request to the authentication initialization endpoint of the Hanko API
/v1/webauthn/authentication/initialize - see also the API
reference). Unlike in the case of registration, the only user data you need to provide is the user
When studying the authentication initialization endpoint description in the API reference you might have noticed
user is not required for the operation. In this case, provision of a user is necessary because the credential
registered in the previous guide was not registered as a resident key (learn more about resident keys here). :::
Just like on registration initialization, you can specify additional options for the authentication operation. For simplicity, this guide will not make use of these options. In a more advanced implementation relying parties can
- require a specific type of authenticator device (see also Platform vs. Roaming authenticators) to be used for authentication
- require that user verification (see also User verification vs. user presence) must be performed
In order create an assertion and authenticate with an existing credential, your application frontend must pass the
credentialRequestOptions obtained in the previous step to the browser through the Web Authentication API. To make
Like on registration, this will trigger a native browser dialog prompting the user to perform an authorization gesture. Once a user has given consent by performing the gesture, the authenticator generates an assertion.
The last step is to finalize the authentication with the Hanko API.
webAuthnResponse from the previous step to your application backend. Again, you will need a corresponding
backend handler. Implement a handler that processes requests issued to the
Finalize the authentication by forwarding the response sent by your frontend to the Hanko API using a
POST request to
the authentication finalization endpoint (
/v1/webauthn/authentication/finalize, see also the API
On successful finalization, the Hanko API returns a representation of the credential used for authentication and the user can be considered logged in.
Congratulations, you successfully authenticated a user using the Hanko API!
Are you looking for a more immersive learning experience? See how it all works by trying out our example application.