Self-service registration

Identity Engine

Note: A request context for the browser client is required when a server-side web app uses an embedded SDK as a proxy between itself and Okta. This context contains values (geolocation, IP address, and user agent) that inform a secure response. However, these values are currently taken from the server rather than the client. As a result, network zones and behaviors that drive their conditions based on these request context values don’t currently work.

Enable a self-registration flow in your app using the embedded SDK.

---

Learning outcomes

• Configure your Okta org for self-service registration.
• Set up the password, email, and/or phone authentication factors.
• Set up and send a verification email during new user registration.

What you need

• An app that uses the embedded Identity Engine SDK
• Okta org already configured for a multifactor use case
• Identity Engine SDK set up for your own app

Sample code

Node.js Identity Engine sample app (opens new window)

---

Overview

Self-service registration allows users to sign up to an app by themselves. In this use case, the user must register with a password, email, and/or phone factors. Enable self-service registration for the app in your Okta org and then build the self-service registration flow in your app.

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

Configuration updates

Configure your Okta org to accept self-registration with the password, email, and/or phone factors.

1. See

   Set up your Okta org for a multifactor use case

   .
2. Create a user profile policy
3. Set the Email and Phone authenticators as optional enrollment factors

Create a user profile policy

Create a policy for self-registration:

1. Open the Admin Console for your org.
2. Go to Security > User Profile Policies, and click Add user profile policy.
3. Enter a policy Name, and click Save.
4. Click the pencil icon next to your new policy.
5. Ensure that Self-service registration is set to Allowed.
6. Click Manage apps.
7. Click Add an App to This Policy.
8. Click Apply next to your app, and then click Close.

Note: See configure user profile policies (opens new window) for more user profile policy options.

Set the email and phone authenticators as optional enrollment factors

1. Go to Security > Authenticators to view the available authenticators.
2. Select the Enrollment tab.
3. Click Edit under Default Policy.
4. Go to the Effective factors section of the Edit Policy dialog:
   1. Set Email to Optional.
   2. Set Phone to Optional.
5. Click Update Policy.

Summary of steps

Start the new user registration with the password factor

The following diagram illustrates the beginning of the registration process where the user initiates their sign-in flow and enrolls their password.

Enroll and verify the email factor

The self-registration flow continues by enrolling the user's email address.

Enroll and verify the phone factor

After the password and email are verified, the user may also enroll the phone factor. However, it's now optional as the user has already enrolled two factors. The following flow describes the steps when the user does enroll the optional phone factor.

Skip the optional remaining factors

The user can also skip enrolling more factors when the remaining unenrolled factors are optional. In this case, the user skips the phone factor.

Integration steps

The user clicks the sign-up link

Add a Sign up link to your app's sign-in page. The user clicks the Sign up link and the browser takes them to the Create Account page.

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

Create a page for the user to enter their basic profile information: their email, first name, and family name. For example:

The user submits their profile data

When the user clicks Sign Up, create an instance of the OktaAuth object and then call idx.register() (opens new window) on the object, passing in the values entered by the user. This starts the registration flow:

// web-server/routes/register.js
router.post('/register', async (req, res, next) => {
  const { firstName, lastName, email } = req.body;
  const authClient = getAuthClient(req);
  const transaction = await authClient.idx.register({
    firstName,
    lastName,
    email,
  });
  handleTransaction({ req, res, next, authClient, transaction });
});

register() returns an anonymous response object that contains two properties.

• status indicates the status of the registration flow.
• nextStep contains information about the next required step of the flow.

A status of IdxStatus.PENDING indicates that the user hasn’t completed the flow. Query nextStep to determine what to do next:

// web-server/utils/getNextRouteFromTransaction.js
function getNextRouteFromTransaction ({ nextStep }) {
  let nextRoute;

  const { name, authenticator } = nextStep;
  const { key } = authenticator || {};

  switch (name) {
    // registration
    case 'enroll-profile':
      nextRoute = '/register';
      break;
    // authenticator enrollment
    case 'select-authenticator-enroll':
      nextRoute = '/select-authenticator';
      break;
    case 'enroll-authenticator':
      nextRoute = `/enroll-authenticator/${key}`;
      break;
    case 'authenticator-enrollment-data':
      nextRoute = `/enroll-authenticator/${key}/enrollment-data`;
      break;

   /// other cases elided

    default:
      break;
  }
  return nextRoute;
};

At this point, nextStep contains select-authenticator-enroll indicating that the user must select an authentication factor to enroll to verify their identity.

The app displays a list of required authenticators to enroll

Create a page that displays a list of required authentication factors the user can enroll to verify their identity. They must choose a factor from the list and click Next.

This page is used several times during the registration flow. Use the nextStep property's inputs collection to build the list. If you complete the steps properly in Configuration updates, the only required authenticator is the password factor. This is the sole factor stored in the inputs property.

nextStep: {
    inputs: [
      { name: 'authenticator',
         options: [{ label: Password, value: AuthenticatorKey.OKTA_PASSWORD }]
      }
   ],
}

The user enrolls their password

When the user selects the password authenticator and clicks Next, pass the selected authenticator as a parameter to idx.proceed().

// web-server/routes/authenticator.js
router.post('/select-authenticator', async (req, res, next) => {
  try {
    const { authenticator } = req.body;
    const authClient = getAuthClient(req);
    const transaction = await authClient.idx.proceed({ authenticator });
    handleTransaction({ req, res, next, authClient, transaction });
  } catch (err) {
    next(err);
  }
});

proceed() returns a response object with a status of IdxStatus.PENDING and a nextStep field that indicates that the user needs to enroll the authenticator (enroll-authenticator). In this context, the user needs to supply a new password.

Create a page that allows the user to supply a new password for verification. For example:

When the user submits their new password, pass it as a parameter to idx.proceed().

// web-server/routes/authenticator.js
router.post('/enroll-authenticator/okta_password', async (req, res, next) => {
  const { password, confirmPassword } = req.body;
  const authClient = getAuthClient(req);
  if (password !== confirmPassword) {
    // TODO: handle validation in middleware
    next(new Error('Password not match'));
    return;
  }

  const transaction = await authClient.idx.proceed({ password });
  handleTransaction({ req, res, next, authClient, transaction });
});

Display a list of optional authenticators to enroll

proceed() returns a response object with a status of IdxStatus.PENDING and a nextStep field that indicates that the user still has authentication factors to enroll (enroll-authenticator) before registration is complete.

In this scenario, you configure the app's authentication policy to require a password and another factor. Therefore, the user must enroll at least one of either the email or phone factors. Redirect them to the list page you created earlier to choose which one.

The user submits the email authenticator

If the user chooses and submits the email authenticator, pass the selected authenticator key as a parameter to idx.proceed().

const transaction = await authClient.idx.proceed({ authenticator });

The app displays the OTP input page

If the call is successful, a one-time passcode (OTP) is sent to the user's email. The returned response object has a status of IdxStatus.PENDING and a nextStep field that indicates that Identity Engine is waiting for the user to check their email and enter the OTP.

Build a form that allows the user to enter the OTP sent to them by email.

The user submits the OTP

The user opens the email and copies the OTP into the form. When the user submits their OTP, pass it as a parameter to idx.proceed():

// web-server/routes/authenticator.js
router.post('/enroll-authenticator/okta_email', async (req, res, next) => {
  const { verificationCode } = req.body;
  const authClient = getAuthClient(req);
  const transaction = await authClient.idx.proceed({ verificationCode });
  handleTransaction({ req, res, next, authClient, transaction });
});

The app displays a second list of optional authenticators to enroll

proceed() returns a response object with a status of IdxStatus.PENDING and a nextStep field that indicates that the user still has authentication factors to enroll (enroll-authenticator) before registration is complete.

Redirect the user to the list page you created earlier to choose another authentication factor. The code is the same. The page should show only the phone factor. However, since this factor is optional and the user has now enrolled two factors, nextStep includes the canSkip property set to true meaning that the list page should now also display a Skip button.

The user can either enroll in or skip the phone factor. Your code should handle both scenarios as follows.

The user enrolls the phone authenticator

The user submits the phone authenticator

If the user chooses and submits the email authenticator, pass the selected authenticator key as a parameter to idx.proceed().

const transaction = await authClient.idx.proceed({ authenticator });

The app displays a phone number input page

proceed() returns a response object with a status of IdxStatus.PENDING and a nextStep field that indicates that the user needs to supply phone registration data (authenticator-enrollment-data). This data includes the phone number and verification method (SMS or voice).

Build a form that allows the user to enter their phone number and a second form to select a phone verification method.

Note: The SDK requires the following phone number format: +##########. For example, +5551234567.

The user submits their phone information

When the user submits their phone number and verification method (in this case, use SMS), pass this information as parameters to idx.proceed().

router.post('/enroll-authenticator/phone_number/enrollment-data', async (req, res, next) => {
  const { phoneNumber, methodType } = req.body;
  const authClient = getAuthClient(req);
  const transaction = await authClient.idx.proceed({
    methodType,
    phoneNumber,
  });
  handleTransaction({ req, res, next, authClient, transaction });
});

The app displays the SMS OTP input page

If the call is successful, your SMS provider sends a one-time passcode (OTP) in an SMS to the user's mobile phone. The returned response object has a status of IdxStatus.PENDING. This status indicates that Identity Engine is waiting for the user to check their email and enter the OTP.

Build a form that allows the user to enter the OTP sent to them by SMS. Depending on your implementation, the page can be the same page that verifies the email code.

The user submits the SMS OTP

The user checks their phone and copies the OTP into the form. When the user submits the OTP, pass this information as parameters to idx.proceed().

router.post('/enroll-authenticator/phone_number', async (req, res, next) => {
  const { verificationCode } = req.body;
  const authClient = getAuthClient(req);
  const transaction = await authClient.idx.proceed({ 
    verificationCode,
  });
  handleTransaction({ req, res, next, authClient, transaction });
});

Complete registration

If the request to verify the code is successful, proceed() returns a response object with a status of IdxStatus.SUCCESS. This status signifies that no more factors (required or optional) are waiting to be enrolled and verified.

The user is now registered with no more factors to be verified. Call authClient.tokenManager.setTokens() to store the returned tokens in a session and redirect the user to the app's default signed-in page.

// web-server/utils/handleTransaction.js
case IdxStatus.SUCCESS:
      // Save tokens to storage (req.session)
      authClient.tokenManager.setTokens(tokens);
      // Redirect back to home page
      res.redirect('/');
      return;

The user skips the phone authenticator

If the user skips phone enrollment, call idx.proceed() passing in the value {skip: true}.

router.post('/select-authenticator/skip', async (req, res, next) => {
  const authClient = getAuthClient(req);
  const transaction = await authClient.idx.proceed({ skip: true });
  handleTransaction({ req, res, next, authClient, transaction });
});

If the returned response object has a status of IdxStatus.SUCCESS, the user is now registered with no more factors to be verified. Call authClient.tokenManager.setTokens() to store the returned tokens in a session and redirect the user to the app's default signed-in page.

Send a confirmation email even if the email authenticator is disabled

Even when only the password factor is required for an Okta app, you can still send a confirmation email.

To replicate this scenario:

1. Configure your org following the steps described in

   Set up your Okta org for a multifactor use case

   .
2. Set your app's authentication policy to require only the password factor.
   1. In the Admin Console, go to Applications > Applications.
   2. Select your app, and then go to the Sign On tab.
   3. In the User authentication section, click Edit.
   4. Set Authentication Policy to Password only, and click Save.
3. Set your app's Initiate login URI to its sign-in URI. By setting this value, the email verification link for new user enrollment redirects the user to the URL provided in the Initiate login URI field.
   1. Select the General tab.
   2. In the General Settings section, click Edit.
   3. Set Initiate login URI to your Sign-in Redirect URI, and click Save.
4. Make email verification mandatory in your default user profile policy.
   1. Go to Security > User Profile Policies.
   2. Click the pencil icon next to the Default policy.
   3. Ensure that Required before access is granted is selected for Email Verification.

During new user registration, there are no factors required other than the password. However, email verification is set to Required in the profile enrollment configuration. In this case, the user is sent an email using the Registration - Activation email template. The user clicks the link in the activation email and is redirected to the sample app's home page.