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 Java Application using Embedded Authentication with the Identity Engine 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:

Note: The examples in this guide use Java 11 and Spring Boot MVC

1: Your app displays the sign-in page

Create a sign-in page that captures the user's username and 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 IdxAuthenticationWrapper.authenticate().

// Begin authentication challenge flow
AuthenticationResponse beginResponse = 
    idxAuthenticationWrapper.begin(constructRequestContext());

// Remember the user’s state
ProceedContext proceedContext = beginResponse.getProceedContext();

// set the user's credentials
AuthenticationOptions authenticationOptions =
    new AuthenticationOptions(username, password);

// submit username and password
AuthenticationResponse authenticationResponse =
    idxAuthenticationWrapper.authenticate(authenticationOptions, proceedContext);

3: Your app displays a list of authenticators

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

Display all of the authenticators that the user has enrolled and are ready for use.

// Update the user's state
proceedContext = authenticationResponse.getProceedContext();

// Check the current authentication status
AuthenticationStatus authenticationStatus = 
   authenticationResponse.getAuthenticationStatus();

switch (authenticationStatus) {
    case AWAITING_AUTHENTICATOR_SELECTION:
        List<Authenticator> authenticators = 
            authenticationResponse.getAuthenticators();

    // show authenticators to the user and prompt for choice

    // other case statements
}

You can find the names and IDs of the available authenticators in the AuthenticationResponse object's authenticators collection.

4: The user submits the email authenticator

When the user submits the email authenticator, pass the authenticator's ID as a parameter to idxAuthenticationWrapper.selectAuthenticator().

Authenticator authenticator =
    authenticators.get(Integer.parseInt(selection));

idxAuthenticationWrapper.selectAuthenticator(
    proceedContext, authenticator);

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 AWAITING_AUTHENTICATOR_VERIFICATION. 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 authenticationResponse.getTokenResponse() to retrieve the user's OIDC claims information and pass it into your application. The user has now signed in.

VerifyAuthenticatorOptions verifyAuthenticatorOptions =
    new VerifyAuthenticatorOptions(code);

AuthenticationResponse authenticationResponse =
    idxAuthenticationWrapper.verifyAuthenticator(proceedContext, verifyAuthenticatorOptions);

switch (authenticationStatus) {
    case SUCCESS:
        TokenResponse tokenResponse = authenticationResponse.getTokenResponse();
        String accessToken = tokenResponse.getAccessToken();

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 (opens new window).