Sign in with email only

Identity Engine

Enable an email-only sign-in flow in your app using the embedded SDK.

Learning outcomes

• Configure your Okta org to enable a user to sign in without a password.
• Integrate a password-optional sign-in flow into an app based on an embedded SDK.

What you need

• Download and set up the SDK
  

Sample code

• React sample application (opens new window)

---

Update configurations

Before you can start integrating password-optional sign-up flows in your app,

Set up your Okta org for a password-optional use case

. See also

Recommended best practices

.

Note: To test the sign-in integration, you must use a user with an enrolled email authenticator.

Integrate

Summary of steps

The following summarizes the steps involved in the password-optional sign-in flow.

1: The user navigates to the sign-in page

When the user navigates to your app's sign-in page, call OktaAuth.idx.start() to start the sign-in flow.

const { oktaAuth } = useOktaAuth();
const startFlow = useCallback(async () => {
  newTransaction = await oktaAuth.idx.start();
}, [oktaAuth, flow, setTransaction]);

The method returns an IdxTransaction object that contains field metadata that you can use to create a sign-in page dynamically.

{
   "status":"PENDING",
   "nextStep":{
      "name":"identify",
      "inputs":[
         {
            "name": "username",
            "label": "Username",
            "required": true
         }
         ...
      ]
   },
}

Display — either statically or dynamically using IdxTransaction — an input field for the user's username.

2: The user submits their username

When the user submits their username, create an object with a username property and assign it the value entered by the user.

const inputValues = {
  username: "johndoe@email.com",
 };

Call OktaAuth.idx.proceed() passing in this new object as a parameter.

setProcessing(true);
const newTransaction = await oktaAuth.idx.proceed(inputValues);
setTransaction(newTransaction);

Note: You can also start the sign-in flow in a single step by passing the username as a parameter to OktaAuth.idx.authenticate(). See idx.authenticate (opens new window) in the GitHub docs or the Node Express version of this guide to learn more.

3. Identity Engine requests email verification

Identity Engine sends the user an email that contains a one-time passcode (OTP) they can use to verify their identity. OktaAuth.idx.proceed() returns an IdxTransaction object with a status of PENDING, indicating that the user needs to verify their identity with their email.

{
  status: "PENDING",
  nextStep: {
    name: "challenge-authenticator",
    type: "email",
    authenticator: {
      type: "email",
      key: "okta_email",
      displayName: "Email",
    },
  },
}

Build the logic that handles this response and sends the user to a dialog where they enter the OTP.

4. The user verifies their identity with their email

The user opens the email sent by Identity Engine. Create a dialog in your app where the user can submit the OTP from the email to Identity Engine.

When the user submits the OTP, create an object with a verificationCode property set to the OTP entered by the user.

const inputValues = {
    "verificationCode":"197277"
 };

Call OktaAuth.idx.proceed() passing in the new object as a parameter.

    const newTransaction = await oktaAuth.idx.proceed(inputValues);
    setTransaction(newTransaction);
    setInputValues({});
    setProcessing(false);

5. Identity Engine verifies OTP and returns success

OktaAuth.idx.proceed() returns IdxTransaction.status equal to SUCCESS along with access and ID tokens, which indicates a successful user sign-in flow.

{
  status: "SUCCESS",
  tokens: {
    accessToken: {
      accessToken: "eyJraWQiOiJLSWdvVHlt...",
      expiresAt: 1656106249,
      tokenType: "Bearer",
    },
    idToken: {
      idToken: "eyJraWQiOiJLSWdvVHltSGlL...",
      expiresAt: 1656106249,
    },
  },
}

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

Note: In other use cases where additional sign-in authenticators are required, the user must choose and verify all required authenticators before IdxTransaction.status of SUCCESS is returned.