Web Authentication integration guide

Identity Engine

This guide shows you how to integrate Web Authentication (WebAuthn) into your app using the embedded SDK.

---

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

Sample ASP.NET MVC Application using Embedded Authentication with the IDX SDK (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 rely on relayed information that bad actors can easily obtain. Phishing, where phony websites, phone calls, and other fraudulent tactics are used to gain access to passwords, OTPs, and other data is the major cause 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 today, which allows iPhone users to sign in using only Face ID after the first sign-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).

Example authentication flow

WebAuthn uses public-key cryptography to security 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 laptop'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 by enabling it in your Okta org and building out support for it in your application using the embedded SDK.

Update configurations

Before you can start using Web Authentication (WebAuthn), you need to enable it in your Okta org and assign it an authentication policy that requires it to be used.

Add WebAuthn to your org

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

1. Open the Admin Console for your org.

2. Choose Security > Authenticators to show the available authenticators.

3. 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. Verify that User verification is set to Discouraged. If not, click Edit and set User verification to Discouraged.
   3. Click Save.

4. Select the Enrollment tab.

5. 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 box for FIDO2 (WebAuthn), and then click Update Policy.

Set your app integration to use the WebAuthn authenticator

New apps are automatically assigned the shared default authentication 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. You should create a policy specifically for your app for testing purposes.

1. Open the Admin Console for your org.

2. Choose Security > Authentication Policies to show the available authentication policies.

3. Click Add a Policy.

4. Give the policy a name, and then click Save.

5. Locate the Catch-all Rule of the new policy and select Actions > Edit.

6. Select Allowed after successful authentication.

7. Set User must authenticate with to Password + Another factor.

8. For Possession factor constraints

   1. Verify that Device Bound is selected.
   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.

9. Select the Applications tab for your newly created policy, and then click Add App.

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

11. Click Close.

12. Verify that the app is now listed in the Applications tab of the new policy.

Software versions

Integrate SDK for authenticator enrollment

Summary of steps

The following summarizes the WebAuthn enrollment flow using a user sign-in use case.

1: Build a sign-in page on the client

Build a sign-in page that captures the user’s name and password, as shown in the following example.

2: Authenticate the user credentials

After a user initiates the sign-on flow by entering their username and password and then clicks Log In, create an AuthenticationOptions object in your LogIn method. Then, set the object's Username and Password properties to the values set by the user. Pass this object as a parameter to the AuthenticateAsync method on the IdxClient.

var authnOptions = new AuthenticationOptions
{
    Username = model.UserName,
    Password = model.Password,
};

try
{
    var authnResponse = await _idxClient.AuthenticateAsync(authnOptions).ConfigureAwait(false);

3: Handle the response from the sign-in flow

Query the AuthenticationStatus property of the AuthenticationResponse object returned by AuthenticateAsync to discover the current status of the authentication process.

    Session["idxContext"] = authnResponse.IdxContext;
    switch (authnResponse?.AuthenticationStatus)
    {
        case AuthenticationStatus.Success:
                … your code …
        case AuthenticationStatus.PasswordExpired:
                … your code …

If you configured your Okta org correctly, you need to respond to two specific authenticator statuses to handle this scenario in addition to Success and PasswordExpired:

• AwaitingAuthenticatorEnrollment that is covered in this section
• AwaitingChallengeAuthenticatorSelection that is covered in the challenge flow section.

The names of the authenticators available for enrollment or challenge can be found in the AuthenticationResponse object's Authenticators collection. Redirect the user to a list of authenticators to select the WebAuthn authenticator for enrollment.

Note: The isChallengeFlow session variable is set to false if the user needs to enroll the WebAuthn authenticator, and true if they have already done so.

        case AuthenticationStatus.AwaitingAuthenticatorEnrollment:
            Session["isChallengeFlow"] = false;
            Session["authenticators"] = 
               ViewModelHelper.ConvertToAuthenticatorViewModelList(authnResponse.Authenticators);
            return RedirectToAction("SelectAuthenticator", "Manage");
        case AuthenticationStatus.AwaitingChallengeAuthenticatorSelection:
            Session["authenticators"] = 
               ViewModelHelper.ConvertToAuthenticatorViewModelList(authnResponse.Authenticators);
            Session["isChallengeFlow"] = true;
            return RedirectToAction("SelectAuthenticator", "Manage");
        default:
            return View("Login", model);
    }
}
catch (OktaException exception)
{
    ModelState.AddModelError(string.Empty, $"Invalid login attempt: {exception.Message}");
    return View("Login", model);
}

4: Display a list of possible authenticator factors

Build a page to display the list of authenticators (including a WebAuthn option). For example, in the sample application, a new SelectAuthenticatorViewModel is populated from the Authenticators collection returned by the AuthenticationResponse.

public ActionResult SelectAuthenticator()
{
   var authenticators =
      (IList<AuthenticatorViewModel>)Session["authenticators"] ??
      new List<AuthenticatorViewModel>();
   var viewModel = new SelectAuthenticatorViewModel
   {
      Authenticators = authenticators,
      AuthenticatorId = authenticators.
         FirstOrDefault()?.AuthenticatorId,
      PasswordId = authenticators.
         FirstOrDefault(x => x.Name.ToLower() == "password")?.AuthenticatorId,
      PhoneId = authenticators.
         FirstOrDefault(x => x.Name.ToLower() == "phone")?.AuthenticatorId,
      WebAuthnId = authenticators.
         FirstOrDefault(x => x.Name.ToLower() == "security key or biometric")?.AuthenticatorId,
      TotpId = authenticators.
         FirstOrDefault(x => x.Name.ToLower() == "google authenticator")?.AuthenticatorId,
      OktaVerifyId = authenticators.
         FirstOrDefault(x => x.Name.ToLower() == "okta verify")?.AuthenticatorId,
      CanSkip = TempData["canSkip"] != null && (bool)TempData["canSkip"]
   };
   return View(viewModel);
}

The viewModel parameter is then consumed in a Razor page.

<section id="selectAuthenticatorForm">
    @using (Html.BeginForm("SelectAuthenticatorAsync", "Manage",
       new { ReturnUrl = ViewBag.ReturnUrl }, FormMethod.Post,
       new { @class = "form-horizontal", role = "form" }))
    {
        @Html.AntiForgeryToken()
        <!-- Headings elided -->
        @Html.ValidationSummary(true, "", new { @class = "text-danger" })
        @Html.HiddenFor(m => m.PasswordId)
        @Html.HiddenFor(m => m.PhoneId)
        @Html.HiddenFor(m => m.WebAuthnId)
        @Html.HiddenFor(m => m.OktaVerifyId)
        @Html.HiddenFor(m => m.TotpId)
        <ul>
            @foreach (var authenticator in Model.Authenticators)
            {
                <div>
                    <label>
                        @Html.RadioButtonFor(m => m.AuthenticatorId,
                            authenticator.AuthenticatorId)
                        @authenticator.Name
                    </label>
                </div>
            }
        </ul>
        @Html.ValidationMessageFor(m => m.AuthenticatorId,
            "", new { @class = "text-danger" })
        <div class="form-group">
            <div>
                <input type="submit" value="Submit" />
            </div>
        </div>
    }
</section>

The WebAuthn factor option is listed as Security Key or Biometric, as shown in the following image.

5: Retrieve encrypted challenge and user information

When the user selects the WebAuthn authenticator factor and clicks Submit, the form posts back to the SelectAuthenticatorAsync method. This checks whether the user is in challenge flow or enrollment flow.

When in Enrollment flow, a call is made to idxClient.SelectEnrollAuthenticatorAsync, using its enrollAuthenticatorOptions parameter to pass in the WebAuthn Authenticator factor ID.

var enrollAuthenticatorOptions = new SelectEnrollAuthenticatorOptions
{
    AuthenticatorId = model.AuthenticatorId,
};

var enrollResponse = await _idxClient.SelectEnrollAuthenticatorAsync(
    enrollAuthenticatorOptions, (IIdxContext)Session["IdxContext"]);

If the call is successful, the returned enrollResponse object has an AuthenticationStatus of AwaitingAuthenticatorVerification and its CurrentAuthenticator property contains the encrypted challenge and the user information that the browser can use to enroll the authenticator.

Session["IdxContext"] = enrollResponse.IdxContext;
Session["isPasswordSelected"] = model.IsPasswordSelected;

switch (enrollResponse?.AuthenticationStatus)
{
    case AuthenticationStatus.AwaitingAuthenticatorVerification:
        {
            if (model.IsPasswordSelected)
            {
                return RedirectToAction("ChangePassword", "Manage");
            }
            else if (model.IsWebAuthnSelected)
            {
                Session["currentWebAuthnAuthenticator"] = 
                   enrollResponse.CurrentAuthenticator;
                return RedirectToAction(
                    "EnrollWebAuthnAuthenticator", "Manage");
            }

            return RedirectToAction("VerifyAuthenticator", "Manage");
        }

    // other case statements

    default:
        return View("SelectAuthenticator", model);
}

6: Enroll authenticator through the browser

Build a page with the challenge and user information from the website's backend servers and then call navigator.credentials.create to raise the prompt to enter a security key, validate with Windows Hello, Touch ID, or other WebAuthn Authenticator. For example, in the sample application, a new EnrollWebAuthnViewModel is populated from the currentAuthenticator object returned by the enrollResponse in the previous step.

var currentAuthenticator = (IAuthenticator)Session["currentWebAuthnAuthenticator"];

var viewModel = new EnrollWebAuthnViewModel
{
    DisplayName = currentAuthenticator.Name,
    UserId = currentAuthenticator.ContextualData.ActivationData.User.Id,
    Username = currentAuthenticator.ContextualData.ActivationData.User.Name,
    Challenge = currentAuthenticator.ContextualData.ActivationData.Challenge,
};

The viewModel is then consumed in the script section of a Razor page. First it's prepared to be passed to the authenticator.

document.addEventListener('DOMContentLoaded', function () {
    const challenge = '@Model.Challenge';
    const userId = '@Model.UserId';
    const username = '@Model.Username';
    const displayName = '@Model.DisplayName';


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

Then the call to navigator.credentials.create calls WebAuthn APIs in the browser and passes the challenge to the authenticator for validation. The user sees the authenticator challenge dialog. In this case, the WebAuthn option is a security USB key.

After the authenticator validates the user, it returns an attestationObject that contains the information needed to validate the registration event, and a clientDataJSON object used to associate the new credential with the server and the browser.

    navigator.credentials.create({
        publicKey: publicKeyCredentialCreationOptions
    }).then((newCredential) => {
        const clientDataJSON = binToStr(
            newCredential.response.clientDataJSON);
        const attestationObject = binToStr(
            newCredential.response.attestationObject);

        const params = {
            "clientData": clientDataJSON,
            "attestation": attestationObject,
            "challenge": challenge,
            "userId": userId,
            "username": username,
            "displayName": displayName
        };

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

7. Send verification credentials to Okta server

Send the verifying credentials back to the Okta server to finish enrolling the WebAuthn authenticator for the user. Okta decrypts the challenge using the user's public key and stores the user's credentials and public key.

        fetch("@Url.Action("EnrollWebAuthnAuthenticatorAsync", "Manage")", options)
            .then(res => {
                console.log("Request successful! Response:", res);
                location.href = '@Url.Action("EnrollWebAuthnAuthenticator", "Manage",
                    new { verificationCompleted = true})';
            }).catch(function(err) {
                console.error(err);
                }
            );
    }).catch(function (err) {
        console.error(err);
    });
}, false);

Pass the credentials as a parameter to the EnrollAuthenticatorAsync method on the IdxClient.

var authnResponse = await _idxClient.EnrollAuthenticatorAsync(
    new EnrollWebAuthnAuthenticatorOptions
    {
        Attestation = viewModel.Attestation,
        ClientData = viewModel.ClientData,
    }, (IIdxContext)Session["idxContext"]);

Session["WebAuthnResponse"] = authnResponse;

8: Enroll more authenticators or sign the user in

Query the AuthenticationStatus property of the AuthenticationResponse object returned by EnrollAuthenticatorAsync to discover the current status of the authentication process. You need to respond to two specific authenticator statuses:

• AwaitingAuthenticatorEnrollment
• Success

A status of AwaitingAuthenticatorEnrollment means that there are other authenticator types (Google, Okta Verify) the user has yet to enroll. Your app should return to Step 4 and display a list of those authenticators that are still unenrolled as well as an option to skip further enrollment.

A status of Success (or the user choosing to skip further authenticator enrollment) means that the user has now successfully enrolled their WebAuthn authenticator and is signed into the app. Call AuthenticationHelper.GetIdentityFromTokenResponseAsync to retrieve the OIDC claims information about the user and pass them into your application.

var authnResponse = (IAuthenticationResponse)Session["webAuthnResponse"];

switch (authnResponse?.AuthenticationStatus)
{
    case AuthenticationStatus.Success:
        ClaimsIdentity identity = await AuthenticationHelper.GetIdentityFromTokenResponseAsync
            (_idxClient.Configuration, authnResponse.TokenInfo);
        _authenticationManager.SignIn(identity);
        return RedirectToAction("Index", "Home");

    case AuthenticationStatus.AwaitingAuthenticatorEnrollment:
        Session["isChallengeFlow"] = false;
        Session["authenticators"] = ViewModelHelper.ConvertToAuthenticatorViewModelList
            (authnResponse.Authenticators);
        TempData["canSkip"] = authnResponse.CanSkip;
        return RedirectToAction("SelectAuthenticator", "Manage");

    default:
        return RedirectToAction("Index", "Home");
}

Integrate SDK for authenticator challenge

Summary of steps

The following summarizes the WebAuthn challenge flow using a user sign-in use case.

1 - 4: Sign in and Select Authenticator

The challenge flow follows the same first four steps as the enrollment flow:

1. Build a sign-in page on the client.
2. Authenticate the user credentials.
3. Handle the response from the sign-in flow.
4. Display a list of possible authenticator factors.

5: Retrieve encrypted challenge and user information

When the user selects the WebAuthn Authenticator factor and clicks Submit, the form posts back to the SelectAuthenticatorAsync method. This checks whether the user is in challenge flow or enrollment flow.

When in challenge flow, a call is made to idxClient.SelectChallengeAuthenticatorAsync, using its selectAuthenticatorOptions parameter to pass in the WebAuthn authenticator factor ID.

var selectAuthenticatorOptions = new SelectAuthenticatorOptions
{
    AuthenticatorId = model.AuthenticatorId,
};

selectAuthenticatorResponse = await _idxClient.SelectChallengeAuthenticatorAsync(
    selectAuthenticatorOptions, (IIdxContext)Session["IdxContext"]);

If the call is successful, the returned selectAuthenticatorResponse object has an AuthenticationStatus of AwaitingAuthenticatorVerification and its CurrentAuthenticator property contains the challenge and other information to verify the WebAuthn credentials on the user’s device.

Session["IdxContext"] = selectAuthenticatorResponse.IdxContext;

switch (selectAuthenticatorResponse?.AuthenticationStatus)
{
    case AuthenticationStatus.AwaitingAuthenticatorVerification:
        var action = (model.IsWebAuthnSelected)
            ? "VerifyWebAuthnAuthenticator"
            : "VerifyAuthenticator";
        if (model.IsWebAuthnSelected)
        {
            Session["currentWebAuthnAuthenticator"] =
                selectAuthenticatorResponse.CurrentAuthenticatorEnrollment;
        }
        return RedirectToAction(action, "Manage");

// other case statements

    default:
        return View("SelectAuthenticator", model);
}

6: Display challenge page

Build a page that takes the challenge and user information from Okta servers and calls navigator.credentials.get to raise a challenge prompt from the correct WebAuthn authenticator.

For example, in the sample application, a new VerifyWebAuthnViewModel is populated from the CurrentAuthenticatorEnrollment property of the AuthenticatorResponse object returned in the previous step.

var currentAuthenticator = (IAuthenticator)Session["currentWebAuthnAuthenticator"];

var viewModel = new VerifyWebAuthnViewModel
{
    WebAuthnCredentialId = currentAuthenticator.CredentialId,
    Challenge = currentAuthenticator.ContextualData.ChallengeData.Challenge,
};

The viewModel parameter is then consumed in the script section of a Razor page. First it's prepared to be passed to the authenticator.

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

The call to navigator.credentials.get calls WebAuthn APIs in the browser and passes the challenge to the authenticator for validation. The authenticator looks up the information stored for the credential ID and checks that the domain name matches the one that was used during enrollment.

If the validations are successful, the user sees the authenticator challenge dialog.

After the authenticator validates the user, it returns an assertion object that proves the user is who they say they are.

• clientDataJSON: A collection of the data passed from the browser to the authenticator
• authenticatorData: Some additional data from the authenticator
• signature: The signature generated by the private key in the authenticator

    navigator.credentials.get({
            publicKey: publicKeyCredentialRequestOptions
        })
        .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" }
            };

7: Send signature for validation

Send the validating credentials back to the Okta server to finish validating the authentication data for the user. Okta decrypts the signature using the user's public key it stored during enrollment and validates that it's the same challenge that started the flow.

            fetch('@Url.Action("VerifyWebAuthnAuthenticatorAsync", "Manage")', options)
                .then(res => {
                    console.log("Request successful! Response:", res);
                    location.href = '@Url.Action("VerifyWebAuthnAuthenticator",
                        "Manage", new { verificationCompleted = true })';
                })
                .catch(function(err) {
                    console.error(err);
                });
        })
        .catch(function (err) {
            console.error(err);
        });
}, false);

Pass the signature and other information as parameters to the ChallengeAuthenticatorAsync method on the IdxClient.

var authnResponse = await _idxClient.ChallengeAuthenticatorAsync(
    new ChallengeWebAuthnAuthenticatorOptions
    {
        AuthenticatorData = viewModel.AuthenticatorData,
        ClientData = viewModel.ClientData,
        SignatureData = viewModel.SignatureData,
    }, (IIdxContext)Session["idxContext"]);

Session["webAuthnResponse"] = authnResponse;

8. Confirm successful verification and sign user in

Query the AuthenticationStatus property of the AuthenticationResponse object returned by ChallengeAuthenticatorAsync to discover the current status of the authentication process. A status of Success means that the user is now successfully signed in to the app. Call AuthenticationHelper.GetIdentityFromTokenResponseAsync to retrieve the OIDC claims information about the user and pass them into your application.

 var authnResponse = (IAuthenticationResponse)Session["webAuthnResponse"];

switch (authnResponse?.AuthenticationStatus)
{
    case AuthenticationStatus.Success:
        ClaimsIdentity identity =
            await AuthenticationHelper.GetIdentityFromTokenResponseAsync(
                _idxClient.Configuration, authnResponse.TokenInfo);
        _authenticationManager.SignIn(identity);
        return RedirectToAction("Index", "Home");

     default:
        return RedirectToAction("Index", "Home");
}

See also

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