FIDO passwordless authentication - REST flow example

Requirements

Component

Requirement

Comments

Airlock IAM

  • Airlock IAM 7.4 or newer.
  • The IAM bundle Enhanced Authentication must be licensed.

For licensing:
Contact order@airlock.com.

Intended solution environment

This example shows how to configure and use the REST authentication flow for authentication with:

  1. FIDO passwordless as the only authentication factor in the authentication flow.

Goal

  • Understand how to configure the Loginapp REST API for FIDO passwordless authentication.
  • Understand how to use the Loginapp REST API for FIDO passwordless authentication using an example.
 
Notice

All following procedures are exemplary and will vary according to your setup or needs.

Prerequisites

  • An end-user account exists in IAM.
  • The end-user has FIDO enabled as a possible authentication method.
  • The FIDO passkey has been registered as a resident key. This is guaranteed if the FIDO configuration setting Require resident keys was enabled during the registration.
  • The end-user has a supported FIDO passkey capable of storing resident keys.
  • The FIDO passkey complies with the settings in the FIDO configuration.
  • The end-user's browser or mobile app supports FIDO passwordless (i.e. support CTAP2).
  • The FIDO passkey has been registered with the end-user's account.
  • The Loginapp REST API is configured and ready to use.
  • The FIDO Settings (basic settings) are configured. Especially, the configured relying party ID matches the browser domain when accessing the Loginapp.

Configuration

  1. Go to:

  2. Loginapp >> Applications and Authentication

  3. Create a new Target Application with display name FIDO passwordless authentication.
  4. Set a new Application ID with fido-passwordless as the value in its ID property.
  5. Add new empty authentication flow.
  6. In the application flow, add the plugin FIDO Passwordless Authentication Step as the first (and only) step.
  7. Make sure the FIDO Settings are connected within the authentication step.
  8. Activate the configuration.
  9. The REST authentication API is now ready to use.
 
Info

Since FIDO passwordless authentication begins with getting a FIDO challenge, we chose to use a separate target application to be able to better illustrate how it works.

The example calls, therefore, start with selecting the correct target application.

Step 1 - Select the FIDO passwordless authentication flow

Call the access end-point of the application with id fido-passwordless to start the correct authentication flow.

 
Example
POST /rest/public/authentication/applications/fido-passwordless/access

The result - unless the session is already authenticated - will be a 401 Not Authorized response asking the REST client to get a FIDO challenge:

 
Example
401 Not Authorized
  {
   "meta":{
      "type":"jsonapi.metadata.document",
      "timestamp":"2021-02-10T09:48:31.606+01:00",
      "nextAuthStep":"FIDO_AUTHENTICATION_CHALLENGE_RETRIEVAL_REQUIRED"
   },
   "errors":[
      {
         "id":"1606:1501",
         "status":401,
         "code":"NOT_AUTHORIZED"
      }
   ]
}

Step 2 - Get FIDO authentication challenge

To get the challenge, the REST client sends the following requests:

 
Example
POST /rest/public/authentication/fido/challenge/retrieve

The following example response sends back a challenge. Note that, in contrast to using FIDO as 2nd factor, no information about acceptable FIDO passkeys are included in the response. This is because no information about the end-user to be authenticated is known at this moment.

 
Example
HTTP/1.1 200 OK
{
   "meta":{
      "type":"jsonapi.metadata.document",
      "timestamp":"2021-02-10T09:50:13.348+01:00"
   },
   "data":{
      "type":"authentication.fido.challenge",
      "id":"4002715863",
      "attributes":{
         "publicKeyCredentialRequestOptions":{
            "challenge":"yvDoTEFX594MCvGDdu95URySWj4OwAGf0jNCde_dv1M",
            "timeout":60000,
            "rpId":"localhost",
            "userVerification":"preferred"
         }
      }
   }
}

The REST client then uses the CTAP protocol to communicate with the FIDO passkey and uses the following call to send the response to the challenge back to IAM for verification. Before sending back the response, the FIDO client (browser or mobile app) usually interacts with the end-user, i.e., asks permission to use the FIDO passkey and/or assures user presence.

 
Example
POST /rest/public/authentication/fido/assertion-response/check
{
   "publicKeyCredential":{
      "id":"AbXIsHnKwe9Rf… 54g",
      "response":{
         "clientDataJSON":"{\"type\":\"webauthn.get\",\"challenge\":\"yvDoTEFX594MCvGDdu95URySWj4OwAGf0jNCde_dv1M\",\"origin\":\"https://localhost:8443\",\"crossOrigin\":false, … }",
         "authenticatorData":"SZYN5YgOjGh0NBcP… .eaw",
         "signature":"MEQCIA8xWnzpfphTs… Fvg",
         "userHandle":"zBcyYsonWQgxZ9NbeZz9n_N0G6Pu5DaF_D3E"
      },
      "type":"public-key"
   }
}

The userHandle included in the response allows Airlock IAM to find the corresponding user account and perform all further checks required, i.e., check if the account is locked.

Successful authentication is confirmed by the usual response:

 
Example
HTTP 200 OK 
 {
   "meta":{
      "type":"jsonapi.metadata.document",
      "timestamp":"2021-02-09T16:00:20.514+01:00"
   },
   "data":{
      "type":"authentication.session",
      "id":"168878204328802317",
      "attributes":{
         
      }
   }
}