Basic sign in with the password factor

Identity Engine

Enable a password-only authentication flow in your web app using the embedded SDK.

Note: Passwords are vulnerable to theft and phishing. Allow users to choose other authenticators by replacing password-only experiences with either a password-optional or a multifactor experience.

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

---

Learning outcomes

Add a password-only authentication flow to a server-side web app.

What you need

• An app that uses the embedded Okta Java Identity Engine SDK (opens new window)
• Identity Engine SDK set up for your own app

Sample code

Okta Java IDX Embedded Auth with SDK Sample (opens new window)

---

Configuration updates

To configure your app so that it requires only a password, see

Set up your Okta org for a password factor-only use case

.

Summary of steps

The following diagram summarizes the steps involved in a sign-in flow using only a password:

Integration steps

The user launches the sign-in page

Build a sign-in page that captures both the user's name and their password.

Begin the authentication process by calling IDXAuthenticationWrapper.begin() and getting a new ProceedContext (opens new window) object.

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

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().

AuthenticationResponse authenticationResponse =
   idxAuthenticationWrapper.authenticate(
      new AuthenticationOptions(username, password),
      beginResponse.getProceedContext()
   );

Your app handles an authentication success response

IDXAuthenticationWrapper.authenticate() returns an AuthenticationResponse (opens new window) object with an AuthenticationStatus (opens new window) property indicating the current state of the sign-in flow. Handle the returned AuthenticationStatus value accordingly:

Success status

If the Java SDK returns an AuthenticationResponse object with AuthenticationStatus=SUCCESS, then the user is successfully signed in. Use the AuthenticationResponse.getTokenResponse() method to retrieve the required tokens (access, refresh, ID) for authenticated user activity.

public ModelAndView handleTerminalTransitions(AuthenticationResponse response, HttpSession session) {
   Util.updateSession(session, response.getProceedContext());
   if (response.getTokenResponse() != null) {
      return homeHelper.proceedToHome(response.getTokenResponse(), session);
   }

   if (response.getAuthenticators() == null && response.getErrors().size() > 0) {
      ModelAndView modelAndView = new ModelAndView("error");
      modelAndView.addObject("errors", response.getErrors());
      return modelAndView;
   }

   if (response.getAuthenticationStatus() == SKIP_COMPLETE) {
      ModelAndView modelAndView = homeHelper.proceedToHome(response.getTokenResponse(), session);
      modelAndView.addObject("info", response.getErrors());
      return modelAndView;
   }
   return null;
}

Other authentication statuses

Handle other returned AuthenticationStatus (opens new window) cases if there are other factors to verify. For example:

    ...
        switch (response.getAuthenticationStatus()) {
            case AWAITING_PASSWORD_RESET:
                return registerPasswordForm("Reset Password");
            case PASSWORD_EXPIRED:
                return registerPasswordForm("Password Expired");
            case AWAITING_AUTHENTICATOR_SELECTION:
            case AWAITING_AUTHENTICATOR_VERIFICATION_DATA:
                return selectAuthenticatorForm(response, "Select Authenticator", session);
            case AWAITING_AUTHENTICATOR_VERIFICATION:
                return verifyForm();
            case AWAITING_AUTHENTICATOR_ENROLLMENT_SELECTION:
                return selectAuthenticatorForm(response, "Enroll Authenticator", session);
            default:
                return unsupportedPolicy();
        }
    ...

Failed authentication

There's no explicit failed status from AuthenticationStatus. Check the response handler for an error in AuthenticationResponse for failed authentication, and handle the flow accordingly. For example:

if (responseHandler.needsToShowErrors(authenticationResponse)) {
    ModelAndView modelAndView = new ModelAndView("redirect:/login");
    modelAndView.addObject("errors", authenticationResponse.getErrors());
    return modelAndView;
}

Get the user profile information

After the user signs in successfully, request basic user information from the authorization server using the tokens that were returned in the previous step.

try {
   String userInfoUrl = getNormalizedUri(issuer, "/v1/userinfo");

   HttpHeaders httpHeaders = new HttpHeaders();
   httpHeaders.setBearerAuth(tokenResponse.getAccessToken());

   HttpEntity<String> requestEntity = new HttpEntity<>(null, httpHeaders);

   ParameterizedTypeReference<Map<String, String>> responseType =
           new ParameterizedTypeReference<Map<String, String>>() { };
   ResponseEntity<Map<String, String>> responseEntity =
           restTemplate.exchange(userInfoUrl, HttpMethod.GET, requestEntity, responseType);

   claims = responseEntity.getBody();
   Assert.notNull(claims, "claims cannot be null");
   user = claims.get("preferred_username");
}
catch (Exception e) {
   logger.error("Error retrieving profile from user info endpoint", e);
}