FIDO passwordless authentication - REST flow example

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.

• 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.

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

• An end-user account exists in IAM.

• The end-user has FIDO enabled as a possible authentication method.

• The FIDO authenticator 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 authenticator capable of storing resident keys.

• The FIDO authenticator complies with the settings in the FIDO configuration.

• The end-users browser or mobile app supports FIDO passwordless (i.e. support CTAP2).

• The FIDO authenticator has been registered with the end-users 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.

1. Go to:

Loginapp >> Applications and Authentication

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

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.

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

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:

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"
      }
   ]
}

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

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 authenticators are included in the response. This is because no information about the end-user to be authenticated is known at this moment.

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 Authenticator 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 authenticator and/or assures user presence.

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:

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

• FIDO configuration overview
• Use case: FIDO passwordless authentication in IAM