Web Authentication integration guide

Identity Engine

Enable phishing-resistant, passwordless authentication in your app using the embedded SDK to integrate WebAuthn for sign-in flows with passkeys, security keys, or biometrics.

Note: When the Passkeys Rebrand self-service Early Access feature is enabled, the FIDO2 (WebAuthn) authenticator is called Passkeys (FIDO2 WebAuthn), and there are new settings and updates to the authenticator page layout.

See Configure the FIDO2 (WebAuthn) authenticator (opens new window) and settings (opens new window). To enable the Passkeys Rebrand feature, see Enable self-service features (opens new window).

---

Learning outcomes

• Understand the WebAuthn flow
• Learn how to integrate WebAuthn into your authentication use case

What you need

• Identity Engine SDK set up for your own app

• An authenticator such as a fingerprint scanner or hardware security key

Sample code

Embedded Java SDK sample application (opens new window)

---

The case for WebAuthn

Passwords and other authenticators that rely on one-time passcodes (OTPs) are vulnerable to security attacks because they use relayed information that bad actors can obtain. Bad actors use phishing and other fraudulent tactics to gain access to passwords, OTPs, and other data. Phishing is one of the major causes of security attacks today.

To be resistant to phishing attacks, a local communication channel should exist between the device and the authentication factor. WebAuthn supplies this local communication channel by providing a framework to authenticate through USB security keys, fingerprints, Touch ID, and other types of localized authenticators. For example, an app running in a browser can authenticate a user by initiating a biometric request using a fingerprint scanner on their laptop.

Besides being resistant to phishing attacks, WebAuthn can drastically reduce sign-in friction by allowing passwordless sign-ins during reauthentication use cases. For example, mobile banking apps use this type of sign-in flow. Some mobile banking apps allow iPhone users to sign in using only Face ID after the user first signs in with a password.

Note: For detailed information on the WebAuthn standard, including an up-to-date list of supported browsers, see webauthn.me (opens new window).

Passkeys and WebAuthn

Passkeys are discoverable WebAuthn credentials that use the FIDO2 Web Authentication (WebAuthn) standard (opens new window). They store the user identifier, which is the unique ID that associates the credential with a specific user, on the authenticator.

Storing the user identifier on the authenticator enables "usernameless" sign-in flows, allowing users to initiate an authentication challenge without having to enter their username. You can sync passkeys across devices by using cloud services (multi-device passkeys). You can also hardware-bind passkeys to a specific authenticator (single-device passkeys), such as a security key or platform authenticator.

Non-discoverable WebAuthn credentials are sometimes referred to as second-factor credentials, and they're explicitly used after another factor during MFA flows. They don't store a user identifier. They require the user to provide a username first so the app can identify which credential to challenge. They're typically hardware-bound, but some non-discoverable credentials can also be synced across devices.

See Passkeys and Okta overview to learn more about passkeys, relying party IDs (RP IDs), and how to use them.

Example authentication flow

WebAuthn uses public-key cryptography to securely communicate and validate the user's device, credentials, and other information. An example WebAuthn authentication challenge flow is as follows:

1. A user attempts to sign in to a Service Provider's website.
2. The website's back-end servers generate a challenge that's cryptographically signed using a public key.
3. The encrypted challenge and other identifying information is sent to the client app running in the browser.
4. The client app then calls WebAuthn APIs in the browser and passes the challenge to the authenticator for validation.
5. The challenge and other data are validated, and the computer's biometrics authenticator prompts the user for a fingerprint.
6. After the fingerprint is validated, the challenge is decrypted using a private key, repackaged with additional information, and re-encrypted using a private key.
7. The repackaged challenge is sent to the server where it's decrypted using the public key. The server validates that it's the same challenge that started the flow.

In the previous example, the public and private keys are generated on the user's device during enrollment. The following diagram illustrates the enrollment and challenge flows and how they're integrated within Okta.

As the Service Provider, you can provide WebAuthn support to your users. Enable WebAuthn in your Okta org and build out support for it in your app using the embedded SDK.

Update configurations

Before you can start using WebAuthn, enable it in your Okta org and create an app sign-in policy that requires it to be used.

Add WebAuthn to your org

First, add the WebAuthn authenticator to your org and enable it.

1. In the Admin Console, go to Security > Authenticators to show the available authenticators.

2. Follow these steps if FIDO2 (WebAuthn) isn't in the list:

   1. Click Add Authenticator.
   2. Click Add on the FIDO2 (WebAuthn) tile.
   3. Verify that User verification is set to Discouraged.
   4. Click Add.

   If FIDO2 (WebAuthn) is in the list:

   1. Select Actions > Edit for FIDO2 (WebAuthn).
   2. If User verification isn't set to Discouraged, click Edit to set it.
   3. Click Save.

3. Select the Enrollment tab.

4. Check that FIDO2 (WebAuthn) is set to either Optional or Required in the Eligible Authenticators section of the default policy.

   1. If FIDO2 (WebAuthn) is set to Disabled, click Edit for the default policy.
   2. Select Optional from the dropdown list for FIDO2 (WebAuthn), and then click Update Policy.

Note: See Configure the FIDO2 (WebAuthn) authenticator (opens new window) for information about configuring WebAuthn in the Admin Console.

Set your app integration to use the WebAuthn authenticator

Apps are automatically assigned the shared default app sign-in policy (opens new window). This policy has a catch-all rule that allows a user access to the app using either one or two factors, depending on your org setup. In production, it becomes evident when you can share your authentication needs between apps.

Create a policy specifically for your app for testing purposes.

1. In the Admin Console, go to Security > Authentication Policies.

2. Click Add a Policy, name it, and then click Save.

3. Locate the catch-all rule of the new policy and select Actions > Edit.

4. Select Allowed after successful authentication.

5. Set User must authenticate with to Password / IdP + Another factor.

6. Follow these steps for the Possession factor constraints are setting:

   1. Select Phishing resistant.
   2. Verify that FIDO2 (WebAuthn) is listed in the box under Additional factor types. If it isn't listed, check that the authenticator has been enabled using steps 4 and 5 of Add WebAuthn to your org.
   3. Click Save.

7. Select the Applications tab for your policy, and then click Add App.

8. Find your app in the list and click Add next to it.

9. Click Close.

10. Verify that the app appears in the Applications tab of the new policy.

Software versions

• Your browser must be up to date to use WebAuthn. The Embedded SDK sample app for the Java SDK only supports Chrome (version 88 and higher).
• The sample app uses the Thymeleaf (opens new window) template engine for processing and creating HTML and javascript. Download (opens new window) the latest version to use it in your app.

Integrate SDK for authenticator enrollment

Integrate the embedded SDK to enroll a user with a WebAuthn authenticator, such as a security key or biometric. This flow typically starts after a primary authentication method, like a password, when the SDK signals that enrollment is required. Your app then uses a challenge from Okta to call the browser's navigator.credentials.create() method. After the user creates the passkey, it's sent back to Okta to complete the enrollment process.

Summary of steps

The following example illustrates the WebAuthn enrollment flow that occurs when a user signs in.

Start the enrollment flow

Start the challenge flow with calls to IDXAuthenticationWrapper.begin() and AuthenticationResponse.getProceedContext(). Then send username and password to the Okta server with IDXAuthenticationWrapper.authenticate().

AuthenticationResponse beginResponse = idxAuthenticationWrapper.begin();
ProceedContext proceedContext = beginResponse.getProceedContext();

AuthenticationResponse authenticationResponse;
authenticationResponse = idxAuthenticationWrapper.authenticate(
    new AuthenticationOptions(username, password.toCharArray()), proceedContext);

Display the WebAuthn option

If you configure your Okta org as detailed in Configuration updates and WebAuthn isn’t already enrolled for the user, authenticate() returns an AuthenticationResponse object with authenticationStatus equal to AWAITING_AUTHENTICATOR_ENROLLMENT_SELECTION and a webauthn authenticator item in the authenticators array.

{
  "authenticationStatus": "AWAITING_AUTHENTICATOR_ENROLLMENT_SELECTION",
  "authenticators": [
    {
    "id": "autc4m63eWYtQ0x3c696",
    "type": "webauthn",
    "label": "Security Key or Biometric",
    "factors": [{
    "id": "autc4m63eWYtQ0x3c696",
    "method": "webauthn",
    "label": "Security Key or Biometric"
    }],
    "hasNestedFactors": false
    }]
}

Use the type and label properties to show the available list of authenticators to the user.

<tr th:each="authenticator : ${authenticators}">
    <div class="form-check">
        <input class="form-check-input" type="radio" name="authenticator-type"
            th:value="${authenticator.label}" checked="true">
        <label class="form-check-label" th:text="${authenticator.label}"></label>
    </div>
</tr>

A simple authenticator selection page should look like this:

Submit the WebAuthn option

When the user selects the WebAuthn option, call IDXAuthenticationWrapper.enrollAuthenticator() passing in ProceedContext and the authenticator ID returned from AuthenticationResponse.authenticators[n].factors[n].id.

Optional<Authenticator> authenticatorOptional =
    authenticators.stream().filter(auth -> auth.getType().equals("webauthn"))
    .findFirst();
String authId = authenticatorOptional.get().getId();

AuthenticationResponse enrollResponse =
    idxAuthenticationWrapper.enrollAuthenticator(proceedContext, authId);

Identify data for creating a credential

The AuthenticationResponse object returned by IDXAuthenticationWrapper.enrollAuthenticator() has authenticationStatus set to AWAITING_AUTHENTICATOR_ENROLLMENT, which indicates that the user must verify their WebAuthn credentials. AuthenticationResponse returns the challenge and other information needed to verify the WebAuthn credentials on the user's device.

{
  "authenticationStatus": "AWAITING_AUTHENTICATOR_ENROLLMENT",
  "webAuthnParams": {
    "currentAuthenticator": {
      "value": {
        "type": "security_key",
        "id": "autc4m63eWYtQ0x3...",
        "key": "webauthn",
        "displayName": "Security Key or Biometric",
        "contextualData": {
          "activationData": {
            "user": {
              "id": "00uunttkoePFgXjQO696",
                "name": "johndoe@email.com",
                "displayName": "John Doe"
            },
            "challenge": "pMhDjTZmaxwBYqLe4-mpOSCVbafd..."
          }
        }
      }
      }
    }
}

Display a page to create credentials

Redirect the user to a page that creates the WebAuthn credentials and allow this page access to the AuthenticationResponse properties.

1. Call ModelandView.addObject() and add AuthenticationResponse.currentAuthenticator, which is used later to extract the challenge and other data.

   modelAndView = new ModelAndView("enroll-webauthn-authenticator");
   modelAndView.addObject("title", "Enroll WebAuthn Authenticator");
   modelAndView.addObject("currentAuthenticator",
       enrollResponse.getWebAuthnParams().getCurrentAuthenticator());
   

2. Set client-side javascript variables to values that originate from currentAuthenticator. These variables are used later to create the credential.

   <script th:inline="javascript">
       const challenge = /*[[${currentAuthenticator.value.contextualData.activationData.challenge}]]*/ '';
       const userId = /*[[${currentAuthenticator.value.contextualData.activationData.user.id}]]*/ '';
       const username = /*[[${currentAuthenticator.value.contextualData.activationData.user.name}]]*/ '';
       const displayName = /*[[${currentAuthenticator.value.contextualData.activationData.user.displayName}]]*/ '';
   </script>
   

   The previous javascript code snippet produces the following code in the browser:

   <script th:inline="javascript">
       const challenge = "ktbYamV1etMLBrLKIVD4xKvkDrL...";
       const userId = "00uuoauaxfdMkYw4...";
       const username = "johndoe@gmail.com";
       const displayName = "John Doe";
   </script>
   

Build the parameter for creating a credential

On page load, create the parameter needed to make a new credential. When creating this parameter, use the challenge and user.id properties.

const publicKeyCredentialCreationOptions = {
    rp: {
        name: "localhost",
        id: "localhost",
    },
    challenge: strToBin(challenge),
    user: {
        id: strToBin(userId),
        name: name,
        displayName: displayName,
    },
    pubKeyCredParams: [{alg: -7, type: "public-key"}],
};

function strToBin(str) {
    return Uint8Array.from(atob(base64UrlSafeToBase64(str)),
    c => c.charCodeAt(0));
}

Create a credential

Call navigator.credentials.create() in the client browser and pass in the CredentialCreationOptions object created in the previous step.

navigator.credentials.create({
    publicKey: publicKeyCredentialCreationOptions
}).then((newCredential) ...

This call initiates the following steps:

1. The browser prompts the user to choose the type of WebAuthn authenticator that they’re using. For example: a portable hardware authenticator such as a USB security key or a software-based authenticator such as a fingerprint scanner.

2. After the user chooses the authenticator, the device asks for consent to create the credentials. In the following example, the Touch ID authenticator prompts the user for a fingerprint to confirm the consent.

3. The private and public key pairs are created. The private key is stored internally on the device and linked to the user and domain name. Specifically, navigator.credentials.create() returns an object of type PublicKeyCredential that contains the public key, credential ID, and other information used to associate the new credential with the server and browser.

   {
   "id": "Aa9rTddZCalI...",
   "rawId": ..,
   "response" : {
     "attestationObject" : Binary data ... ,
     "clientDataJSON": Binary data ... ,
     },
   "type": "public-key"
   }
   

Build the parameter for sending the public key

The returned PublicKeyCredential object contains the signature and other binary-formatted data that you need to convert to strings before sending it back to the Okta servers.

.then((assertion) => {
.then((newCredential) => {
    const clientDataJSON = binToStr(newCredential.response.clientDataJSON);
    const attestationObject = binToStr(newCredential.response.attestationObject);

    const params = {
        "clientData": clientDataJSON,
        "attestation": attestationObject
    };

    const options = {
        method: 'POST',
        body: JSON.stringify(params),
        headers: { "Content-type": "application/json; charset=UTF-8" }
    };

function binToStr(bin) {
          return btoa(new Uint8Array(bin).reduce((s, byte) => s
          + String.fromCharCode(byte), ''));
      }

Forward public key credentials

Forward the signature to the Okta server for validation. Specifically, perform the following steps:

1. First, send the converted signature to your app using an HTTP Post request from the client browser to the server.

   fetch("/enroll-webauthn", options)
                   .then(res => {
   

2. Next, send the data to IDXAuthenticationWrapper.verifyWebAuthn() to have the server validate the signature and store the credential ID and public key associated with the user's account.

   ProceedContext proceedContext = Util.getProceedContextFromSession(session);
   
   AuthenticationResponse authenticationResponse = idxAuthenticationWrapper
       .verifyWebAuthn(proceedContext, webauthnRequest);
   

3. Depending on the org configuration, the AuthenticationResponse returned by IDXAuthenticationWrapper.verifyWebAuthn() may contain authenticationStatus of SUCCESS along with token information, or another status to indicate that there are further remediation steps to complete.

Integrate SDK for authenticator challenge

Use the authenticator challenge flow to verify a user with their previously enrolled passkey or security key. This process confirms possession of an existing credential for a secure sign-in flow. It confirms possession by using the SDK to orchestrate a navigator.credentials.get() request and validate the cryptographic response from the authenticator.

Summary of steps

The following example illustrates the WebAuthn enrollment flow that occurs when a user signs in.

Start the challenge flow

Start the challenge flow with calls to IDXAuthenticationWrapper.begin() and AuthenticationResponse.getProceedContext(). Then send the username and password to the Okta server with IDXAuthenticationWrapper.authenticate().

AuthenticationResponse beginResponse = idxAuthenticationWrapper.begin();
ProceedContext proceedContext = beginResponse.getProceedContext();

AuthenticationResponse authenticationResponse;
authenticationResponse = idxAuthenticationWrapper.authenticate(
    new AuthenticationOptions(username, password.toCharArray()),
    proceedContext);

Display the WebAuthn option

If you configure your Okta org as detailed in Configuration updates and WebAuthn is already enrolled for the user, authenticate() returns an AuthenticationResponse object with authenticationStatus equal to AWAITING_AUTHENTICATOR_SELECTION and a webauthn authenticator item in the authenticators array.

{
"authenticationStatus": "AWAITING_AUTHENTICATOR_SELECTION",
  "authenticators": [{
  "id": "autc4m63eWYtQ0x3...",
  "type": "webauthn",
  "label": "Security Key or Biometric",
  "factors": [{
    "id": "autc4m63eWYtQ0x3...",
    "method": "webauthn",
    "label": "Security Key or Biometric"
    }],
    "hasNestedFactors": false
  }],
}

Use the type and label properties to show the available list of authenticators to the user.

<tr th:each="authenticator : ${authenticators}">
    <div class="form-check">
        <input class="form-check-input" type="radio" name="authenticator-type"
           th:value="${authenticator.label}" checked="true">
        <label class="form-check-label" th:text="${authenticator.label}"></label>
    </div>
</tr>

A simple authenticator selection page should look like this:

Submit the WebAuthn authenticator option

When the user selects the WebAuthn option, call IDXAuthenticationWrapper.enrollAuthenticator() passing in ProceedContext and the authenticator ID returned from AuthenticationResponse.authenticators[n].factors[n].id.

Optional<Authenticator> authenticatorOptional =
    authenticators.stream().filter(auth -> auth.getType().equals
    ("webauthn")).findFirst();
String authId = authenticatorOptional.get().getId();

AuthenticationResponse enrollResponse = idxAuthenticationWrapper
    .enrollAuthenticator(proceedContext, authId);

Identify data for getting the credential

The AuthenticationResponse object from IDXAuthenticationWrapper.enrollAuthenticator() has authenticationStatus set to AWAITING_AUTHENTICATOR_VERIFICATION. This indicates that the user must verify their WebAuthn credentials. The following code shows an example response. Also, AuthenticationResponse returns the challenge, credential ID, and other information needed to verify the WebAuthn credentials on the user's device.

{
  "authenticationStatus": "AWAITING_AUTHENTICATOR_VERIFICATION",
  "webAuthnParams": {
    "currentAuthenticator": {
      "value": {
        "type": "security_key",
        "id": "autc4m63eWYtQ0x3...",
        "key": "webauthn",
        "displayName": "Security Key or Biometric",
        "contextualData": {
          "challengeData": {
            "userVerification": "preferred",
            "challenge": "O99tLUgxcY5fzANLKS7B5rUGZor2...",
            "extensions": {
              "appid": "https://test.okta.com"
            }
          }
        }
      }
    },
    "webauthnCredentialId": "AYqpxcR9Jrw6BzVJyZf-ImP7OffDl9-pHcRV2fLD9wexskXac7-..."
  }
}

Display a page to verify WebAuthn credentials

Redirect the user to a page that verifies the WebAuthn credentials returned in the AuthenticationResponse.webAuthnParams object; specifically currentAuthenticator.contextualData.challengeData and webauthnCredentialId.

1. Call ModelandView.addObject() and add webauthnCredentialId and challengeData.

   String webauthnCredentialId = enrollResponse.getWebAuthnParams()
       .getWebauthnCredentialId();
   
   modelAndView.addObject("title", "Select WebAuthn Authenticator");
   modelAndView.addObject("webauthnCredentialId", webauthnCredentialId);
   modelAndView.addObject("challengeData", enrollResponse.getWebAuthnParams()
       .getCurrentAuthenticator().getValue().getContextualData()
       .getChallengeData());
   

2. Set client-side javascript variables used later to get the credential.

   <script th:inline="javascript">
       const challengeData = /*[[${challengeData}]]*/ '';
       const webauthnCredentialId = /*[[${webauthnCredentialId}]]*/ '';
   </script>
   

   The previous javascript code snippet produces the following code in the browser:

   <script th:inline="javascript">
       const challengeData = {"userVerification":"preferred","challenge":"O99tLUgxcY5fz",...};
       const webauthnCredentialId = "AYqpxcR9Jrw6BzVJyZf-ImP7OffDl9-pHcRV2fLD9wexskXac7
   </script>
   

Build parameter for getting a credential

On page load, build the parameter needed to request the credential. Use the challengeData.challenge and webauthnCredentialId values to create this parameter.

const publicKeyCredentialRequestOptions = {
  challenge: strToBin(challengeData.challenge),
  allowCredentials: [{
      id: strToBin(webauthnCredentialId),
      type: 'public-key',
  }],
  userVerification: 'discouraged',
  timeout: 60000,
  };

function strToBin(str) {
    return Uint8Array.from(atob(base64UrlSafeToBase64(str)),
    c => c.charCodeAt(0));
}

Receive credentials and create cryptographic signature

Call navigator.credentials.get() in the client browser and pass in the CredentialRequestOptions object created in the previous step.

navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions
}).then((assertion) ...

This call initiates the following steps:

1. The authenticator looks up the information stored for the credential ID and checks that the domain name matches the one used during enrollment.

2. If the validations are successful, the authenticator prompts the user for consent. In the following example, the Touch ID authenticator prompts the user for a fingerprint to confirm consent.

3. If the user is verified successfully, the authenticator uses the private key to generate a cryptographic signature over the domain name and challenge. Specifically, navigator.credentials.get() returns an object of type PublicKeyCredential that contains this signature.

{
"id": "Aa9rTddZCalI...",
"rawId": ..,
"response" : {
  "authenticatorData" : Binary data ... ,
  "clientDataJSON": Binary data ... ,
  "signature": Binary data ... ,
  "userHandle": Binary data ... ,
  },
"type": "public-key"
}

Build the parameter for sending the public key

The returned PublicKeyCredential object contains the signature and other binary-formatted data that you need to convert to strings before sending it back to the Okta servers.

.then((assertion) => {
    const clientData = binToStr(assertion.response.clientDataJSON);
    const authenticatorData = binToStr(assertion.response.authenticatorData);
    const signatureData = binToStr(assertion.response.signature);

    const params = {
       "clientData": clientData,
        "authenticatorData": authenticatorData,
        "signatureData": signatureData
    };

    const options = {
        method: 'POST',
        body: JSON.stringify(params),
        headers: { "Content-type": "application/json; charset=UTF-8" }
    };

function binToStr(bin) {
    return btoa(new Uint8Array(bin).reduce((s, byte) => s
        + String.fromCharCode(byte), ''));
}

Forward the signature for validation

Forward the signature to the Okta server for validation. Specifically, perform the following steps:

1. Send the converted signature data from the client browser to the server side of your web app.

   fetch('/verify-webauthn', options)
       .then(res => { ...
   

2. Call IDXAuthenticationWrapper.verifyWebAuthn() to have the server validate the signature corresponding to the challenge and public key.

   ProceedContext proceedContext = Util.getProceedContextFromSession(session);
   
   AuthenticationResponse authenticationResponse = idxAuthenticationWrapper
       .verifyWebAuthn(proceedContext, webauthnRequest);
   

3. Depending on the org configuration, the AuthenticationResponse returned by IDXAuthenticationWrapper.verifyWebAuthn() may contain authenticationStatus of SUCCESS along with token information, or another status to indicate that there are further remediation steps to complete.

See also

• Sign in with password and email factors
• Self-service registration