Sign in with password and email factors

Identity Engine

Note: In proxy model architectures, where a server-side app using the embedded SDK is used as a proxy between client apps and Okta servers, a request context for the client apps is required. Security enforcement is expected to be based on the client request context's IP address and user agent.

However, since these values are currently being derived from the server app rather than the client, this enforcement isn't available. As a result, network zones or behaviors that drive their conditions based on these request context values (geolocation, IP Address, or user agent) won't work until Okta can find a solution to the issue.

Enable a password and email sign-in flow in your app using the embedded SDK.

Note: To learn about a sign-in use case where the password is optional, see the Sign in with email only guide.

---

Learning outcomes

• Configure your Okta org to use the email authenticator.
• Challenge a user's identity with password and email factors.

What you need

Identity Engine SDK set up for your own app

Sample code

Sample ASP.NET MVC Application using Embedded Authentication with the IDX SDK (opens new window)

---

Overview

With the embedded SDK, your app can verify a user's identity using a password and then the email authenticator. The email authenticator can complete its verification using

magic links

, a one-time passcode (OTP), or a combination of both.

Update configurations

Before you build a sign-in flow with password and email factors, you must configure the Okta org to accept both factors in your app. To learn how to do this, see the Okta email integration guide.

Integrate

Summary of steps

The following summarizes the steps involved in a sign-in flow using password and email:

1: Your app displays the sign-in page

Build a sign-in page for your app that captures both the username and the password.

Note: The account's username is also its primary email address.

2: The user submits their username and password

When the user submits their username and password, create an AuthenticationOptions object and assign its Username and Password properties to the values entered by the user. Pass this object as a parameter to IdxClient.AuthenticateAsync().

var _idxClient = new IdxClient();
var authnOptions = new AuthenticationOptions {
   Username = model.UserName,
   Password = model.Password
};

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

3: Your app displays a list of authenticators

AuthenticateAsync() returns an AuthenticationResponse object. Query its AuthenticationStatus property for the current status of the authentication process. A status of AwaitingChallengeAuthenticatorSelection indicates that the user has supplied the correct password and must select a secondary authentication factor to verify their identity.

switch (authnResponse?.AuthenticationStatus)
{
   case AuthenticationStatus.AwaitingChallengeAuthenticatorSelection:
      Session["authenticators"] = ViewModelHelper.
         ConvertToAuthenticatorViewModelList(authnResponse.Authenticators);
      Session["isChallengeFlow"] = true;
      return RedirectToAction("SelectAuthenticator", "Manage");

   // other case statements

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

You can find the names and IDs of the available authenticators in the AuthenticationResponse object's Authenticators collection. You should redirect the user to an authenticator list page that displays all the authenticators that the user has enrolled and are ready for use. For example:

4: The user submits the email authenticator

When the user submits the email authenticator, create a SelectAuthenticatorOptions object and assign its AuthenticatorId property to the email authenticator ID. Pass this object as a parameter to IdxClient.SelectChallengeAuthenticatorAsync().

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

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

5: The user verifies their identity with the email authenticator

Identity Engine sends a verification email to the user if the call is successful. The returned AuthenticationResponse object has an AuthenticationStatus of AwaitingAuthenticatorVerification. This status indicates that Identity Engine is waiting for the user to check their email and either click the magic link or enter the OTP.

To learn how to support verification with magic links or OTP, see the Okta email integration guide.

6: Your app handles an authentication success response

When the user correctly verifies their identity using the email authenticator, the returned AuthenticationResponse object has an AuthenticationStatus of Success. Call AuthenticationHelper.GetIdentityFromTokenResponseAsync() to retrieve the user's OIDC claims information and pass it into your application. The user has now signed in.

var authnResponse = await _idxClient.VerifyAuthenticatorAsync(
   verifyAuthenticatorOptions, (IIdxContext)Session["idxContext"]);
Session["idxContext"] = authnResponse.IdxContext;

switch (authnResponse.AuthenticationStatus)
{

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

   // other case statements
}

return View(view, model);

Store these tokens for future requests and redirect the user to the default page after a successful sign-in attempt.

Note: You can request basic user information from Okta's OpenID Connect authorization server after a user has signed in successfully. See Get the user profile information.