Authenticate with autofill UI

Once a FIDO2-capable authenticator is registered, it can be used for authentication. To integrate the Authentication Cloud functions into your application, you must send an HTTP request to the approval endpoint, then use the approval response to prepare an input element for the user that will prompt an authentication dialog. Our JavaScript solution can handle the communication between the WebAuthn API and the Authentication Cloud API.

info

We suggest testing the autofill UI function on a wide variety of platforms and browsers, before deploying to a live application, as subtle differences between different platforms can mean slightly different implementation requirements.

Prerequisites of autofill UI

Your website should contain an <input> element with the autocomplete="webauthn" attribute. This attribute is required to trigger the native browser dialog for the user to interact with the authenticator.

Autofill UI flow

The following diagram shows the end-to-end sequence of an authentication operation using a FIDO2 authenticator. The steps that must be performed to integrate the Authentication Cloud into your application are in bold. Some steps are included in the JavaScript solution.

Send an HTTP request to the approval endpoint

For detailed information on the HTTP request parameters and response fields, see the Approval endpoint page of the API reference documentation.

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/approval call with your instance ID, and configure the HTTP request as follows:

1. Send your access key or intent token in the Authorization Bearer token header. For more information on the intent token, see Intent endpoint.
2. Set the channel parameter to fido2.
3. Optionally, set the fido2Options.userVerification to preferred, required, or discouraged. With these settings you can customize the requirement for user verification. The default value is preferred.

HTTP request example

cURL code sample for approval with custom FIDO2 options

curl "https://$instance.mauth.nevis.cloud/api/v1/approval"  \
  -XPOST \
  -H "Authorization: Bearer $access_key"    \
  -H 'Content-Type: application/json;charset=utf-8'     \
  -d "{ \"channel\":\"fido2\",
        \"fido2Options\": {
            \"userVerification\":\"required\"
        }
      }"

HTTP response example

201 Created: Approval using a FIDO2 device

{
  "statusToken": "eyJ...iJ9.ey...fVag0LMfTMX5kQ",
  "transactionId": "8b2373-...-9698e35e",
  "credentialRequestOptions": {
    "challenge": "2LpI-1C...drA",
    "rpId": "nevis-latest-dev-cbbc98.mauth.nevis.cloud",
    "timeout": 60000,
    "userVerification": "required"
  }
}

Forward the credentialRequestOptions object

The approval response contains the credentialRequestOptions object, which is required by the WebAuthn API for authentication with the FIDO2 credential.

Authenticate with the WebAuthn credential using the JavaScript solution

Once the credentialRequestOptions is forwarded to the browser, apply the Authentication Cloud JavaScript template to forward the WebAuthn credential. The frontend of the relying party must include a JavaScript solution to connect to the Authentication Cloud API.

The template includes the following WebAuthn calls:

0. Using the native browser WebAuthn JSON APIs (PublicKeyCredential.parseRequestOptionsFromJSON() and PublicKeyCredential.prototype.toJSON()). No external library is required.
1. Checking if WebAuthn and Autofill UI is supported by the browser.
2. Creating the authenticateOptions object with the mediation: "conditional" property: credentialRequestOptions is parsed with PublicKeyCredential.parseRequestOptionsFromJSON() and the result is assigned to the publicKey property.
3. Calling navigator.credentials.get() to authenticate with the WebAuthn credential. After a user interaction, a serverPublicKeyCredential object is returned.
   note

   A native browser dialog prompts the user when it interacts with the proper <input autocomplete="webauthn"> element to perform the authorization gesture. Once a user has given consent by doing so, the authenticator generates an assertion and a ServerPublicKeyCredential object is returned.

4. Extending ServerPublicKeyCredential with the userAgent attribute to provide Authentication Cloud with vital information.
5. Sending the updatedServerPublicKeyCredential to your application backend.
6. Handling the success or failure response, based on the assertion endpoint response.

Browser compatibility

The native WebAuthn JSON APIs (PublicKeyCredential.parseCreationOptionsFromJSON(), PublicKeyCredential.parseRequestOptionsFromJSON(), and PublicKeyCredential.prototype.toJSON()) are available in Chrome 129+, Firefox 119+, and Safari 18.4+. They are not supported in Android WebView. To support older browsers, you can still use the @github/webauthn-json library as a convenience wrapper.

JavaScript template

JavaScript template for forwarding the credential

// 0
// The native browser WebAuthn JSON APIs are used; no library import is required.

...
function defaultHeaders() {
  return {
    'Accept': 'application/json',
    'Content-Type': 'application/json;charset=utf-8',
  };
}

function isWebAuthnSupportedByTheBrowser() {
   if (!window.PublicKeyCredential || typeof window.PublicKeyCredential !== 'function') {
      console.error('Oh no! This browser doesn\'t currently support WebAuthn.');
      return false;
   }
   if (window.location.protocol === 'http:' && (window.location.hostname !== 'localhost' && window.location.hostname !== '127.0.0.1')){
      console.error('WebAuthn only supports secure connections. For testing over HTTP, you can use the origin "localhost".');
      return false;
   }
   if (typeof PublicKeyCredential.parseCreationOptionsFromJSON !== 'function'
         || typeof PublicKeyCredential.parseRequestOptionsFromJSON !== 'function') {
      console.error("This browser doesn't support the WebAuthn JSON parsing APIs. Please use Chrome 129+, Firefox 119+, or Safari 18.4+.");
      return false;
   }
   return true;
}

async function isAutofillUIAvailable() {
   if (isWebAuthnSupportedByTheBrowser()
           && typeof window.PublicKeyCredential.isConditionalMediationAvailable === 'function'
           && await PublicKeyCredential.isConditionalMediationAvailable()) {
      return true;
   } else {
      console.warn('Conditional mediation (Autofill UI requirement) is not available.')
      return false;
   }
}


// 1
if (!await isAutofillUIAvailable()) {
  // case when the browser does not support Autofill UI
}

// 2
const authenticateOptions = {
  mediation: "conditional",
  publicKey: PublicKeyCredential.parseRequestOptionsFromJSON(credentialRequestOptions)
};

// 3
const serverPublicKeyCredential = (await navigator.credentials.get(authenticateOptions)).toJSON();

// 4
serverPublicKeyCredential.userAgent = navigator.userAgent;

// 5
const response = await fetch(
      'https://<your-backend-url>', {
        method: 'POST',
        credentials: 'same-origin',
        headers: defaultHeaders(),
        body: JSON.stringify(serverPublicKeyCredential),
      });
const result = await response.json();

// 6
if (result.status === 'ok') {
  // handle success
} else {
  // handle failure, you can find more details in result.errorMessage
}

Forward the authentication response to the assertion endpoint

Send the authentication response to the Authentication Cloud assertion API endpoint. This endpoint does not require a token.