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

ASP.NET MVC 4.x Sample Applications for Okta (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 a 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 self-registration flow begins when 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.

The user submits their profile data

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

When the user clicks Sign Up, create a UserProfile object and set its properties to the values entered by the user. Pass this object as a parameter to IdxClient.RegisterAsync().

var idxAuthClient = new IdxClient();

var userProfile = new UserProfile();
userProfile.SetProperty("firstName", model.FirstName);
userProfile.SetProperty("lastName", model.LastName);
userProfile.SetProperty("email", model.Email);

var registerResponse = await idxAuthClient.RegisterAsync(userProfile);

RegisterAsync() returns a RegisterResponse object. Query its AuthenticationStatus property for the status of the registration process. A status of AwaitingAuthenticatorEnrollment indicates that the user must enroll an authentication factor to verify their identity.

if (registerResponse.AuthenticationStatus ==
   AuthenticationStatus.AwaitingAuthenticatorEnrollment)
{
   Session["idxContext"] = registerResponse.IdxContext;
   TempData["authenticators"] = ViewModelHelper.
      ConvertToAuthenticatorViewModelList(registerResponse.Authenticators);
   return RedirectToAction("SelectAuthenticator", "Manage");
}

Display 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. 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 Authenticators list property.

This page is used several times during the registration flow. Find the names and IDs of the available authenticators in the response object's Authenticators collection to build the list.

var authenticators = (IList<AuthenticatorViewModel>)TempData["authenticators"];
var viewModel = new SelectAuthenticatorViewModel
  {
     Authenticators = authenticators,
     PasswordId = authenticators.
        FirstOrDefault(x => x.Name.ToLower() == "password")?.AuthenticatorId,
     PhoneId = authenticators.
        FirstOrDefault(x => x.Name.ToLower() == "phone")?.AuthenticatorId,
     CanSkip = TempData["canSkip"] != null && (bool)TempData["canSkip"]
  };

TempData["authenticators"] = viewModel.Authenticators;
return View(viewModel);

The user enrolls their password

When the user selects the password authenticator and clicks Next, create an EnrollAuthenticatorOptions object and assign its AuthenticatorId property to the password authenticator ID. Pass this object as a parameter to IdxClient.EnrollAuthenticatorAsync().

var enrollAuthenticatorOptions = new EnrollAuthenticatorOptions
{
     AuthenticatorId = model.AuthenticatorId,
};

var enrollResponse = await idxAuthClient.EnrollAuthenticatorAsync(
      enrollAuthenticatorOptions, (IIdxContext)Session["IdxContext"]);

EnrollAuthenticatorAsync() returns an EnrollResponse object with an AuthenticationStatus of AwaitingAuthenticatorVerification. This indicates that the new user needs to verify the authenticator. In this case, this means the user needs to supply a new password.

switch (enrollResponse?.AuthenticationStatus)
{
   case AuthenticationStatus.AwaitingAuthenticatorVerification:
   if (model.IsPasswordSelected)
   {
      return RedirectToAction("ChangePassword", "Manage");
   }

   return RedirectToAction("VerifyAuthenticator", "Manage");

case AuthenticationStatus.AwaitingAuthenticatorEnrollmentData:
   return RedirectToAction("EnrollPhoneAuthenticator", "Manage");
default:
   return View("SelectAuthenticator", model);
}

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

When the user submits their new password, create a VerifyAuthenticatorOptions object and assign its Code property to the new password. Pass this object as a parameter to VerifyAuthenticatorAsync().

var idxAuthClient = new IdxClient(null);
var verifyAuthenticatorOptions = new VerifyAuthenticatorOptions
{
   Code = code,
};

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

Display a list of optional authenticators to enroll

VerifyAuthenticatorAsync() returns a RegisterResponse object with an AuthenticationStatus property of AwaitingAuthenticatorEnrollment. This indicates that the user still has authentication factors to enroll before registration is complete.

In this scenario, you configure the app's app sign-in 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 following code snippet shows how to handle the response. The authenticator list page loads again (the first time was for password) with the two remaining factors.

switch (authnResponse.AuthenticationStatus)
   {
       ...
       case AuthenticationStatus.AwaitingAuthenticatorEnrollment:
           TempData["authenticators"] =
              ViewModelHelper.ConvertToAuthenticatorViewModelList(authnResponse.Authenticators);
              TempData["canSkip"] = authnResponse.CanSkip;
            return RedirectToAction("SelectAuthenticator", "Manage");
...

Note To learn how to use the CanSkip property to allow users to skip enrolling more optional factors, see Display a second list of optional authenticators to enroll.

The user submits the email authenticator

If the user chooses and submits the email authenticator, create an EnrollAuthenticatorOptions object and assign its AuthenticatorId property to the email authenticator ID. Pass this object as a parameter to IdxClient.EnrollAuthenticatorAsync().

var enrollAuthenticatorOptions = new EnrollAuthenticatorOptions
{
   AuthenticatorId = model.AuthenticatorId,
};

var enrollResponse = await idxAuthClient.EnrollAuthenticatorAsync(
   enrollAuthenticatorOptions, (IIdxContext)Session["IdxContext"]);

Display OTP input page

If the call is successful, a one-time passcode (OTP) is sent to the user's email. The returned EnrollResponse object has an AuthenticationStatus of AwaitingAuthenticatorVerification. This status indicates that Identity Engine is waiting for the user to check their email and enter the OTP.

var enrollResponse = await idxAuthClient.EnrollAuthenticatorAsync(
   enrollAuthenticatorOptions, (IIdxContext)Session["IdxContext"]);

switch (enrollResponse?.AuthenticationStatus)
{
   case AuthenticationStatus.AwaitingAuthenticatorVerification:
        return RedirectToAction("VerifyAuthenticator", "Manage");
...
}

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 the OTP, create a VerifyAuthenticatorOptions object and assign its Code property to the OTP. Pass this object as a parameter to VerifyAuthenticatorAsync().

var idxAuthClient = new IdxClient(null);
var verifyAuthenticatorOptions = new VerifyAuthenticatorOptions
{
   Code = code,
};

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

Display a second list of optional authenticators to enroll

VerifyAuthenticatorAsync() returns a RegisterResponse object with an AuthenticationStatus property of AwaitingAuthenticatorEnrollment. This indicates that the user still has authentication factors to enroll before registration is complete.

switch (authnResponse.AuthenticationStatus)
{
   ...
   case AuthenticationStatus.AwaitingAuthenticatorEnrollment:
      TempData["authenticators"] =
         ViewModelHelper.ConvertToAuthenticatorViewModelList(authnResponse.Authenticators);
         TempData["canSkip"] = authnResponse.CanSkip;
      return RedirectToAction("SelectAuthenticator", "Manage");
   ...

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, the CanSkip property is now 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 selects the phone authenticator, create an EnrollAuthenticatorOptions object and assign its AuthenticatorId property to the phone authenticator ID. Pass this object as a parameter to IdxClient.EnrollAuthenticatorAsync().

var enrollAuthenticatorOptions = new EnrollAuthenticatorOptions
{
   AuthenticatorId = model.AuthenticatorId,
};

var enrollResponse = await idxAuthClient.EnrollAuthenticatorAsync(
   enrollAuthenticatorOptions, (IIdxContext)Session["IdxContext"]);

Display phone number input page

The returned EnrollResponse object has an AuthenticationStatus of AwaitingAuthenticatorEnrollmentData. This status indicates that Identity Engine is waiting for the user for more data before the factor can be enrolled. In this case, the user needs to supply a phone number.

var enrollResponse = await idxAuthClient.EnrollAuthenticatorAsync(
   enrollAuthenticatorOptions,(IIdxContext)Session["IdxContext"]);
switch (enrollResponse?.AuthenticationStatus)
{
   ...
   case AuthenticationStatus.AwaitingAuthenticatorEnrollmentData:
      return RedirectToAction("EnrollPhoneAuthenticator", "Manage");
   ...
}

Build a form that allows the user to enter their phone number.

Note: The .NET SDK requires the phone number in the following format: +# ### ### ####, including the beginning plus (+) sign.

The user submits their phone number

When the user submits their phone number, create an EnrollPhoneAuthenticatorOptions object and assign its AuthenticatorId, PhoneNumber, and MethodType properties to the phone authenticator ID, phone number, and AuthenticatorMethodType.Sms respectively. Pass this object as a parameter to EnrollAuthenticatorAsync().

Note: Only SMS is supported for the phone authenticator type.

var enrollPhoneAuthenticatorOptions = new EnrollPhoneAuthenticatorOptions
{
   AuthenticatorId = Session["phoneId"].ToString(),
   PhoneNumber = model.PhoneNumber,
   MethodType = AuthenticatorMethodType.Sms,
};

var enrollResponse = await idxAuthClient.EnrollAuthenticatorAsync(
   enrollPhoneAuthenticatorOptions, (IIdxContext)Session["IdxContext"]);
Session["IdxContext"] = enrollResponse.IdxContext;

Display SMS OTP input page

If the call is successful, a one-time passcode (OTP) is sent by SMS to the user's mobile phone. The returned EnrollResponse object has an AuthenticationStatus of AwaitingAuthenticatorVerification. This status indicates that Identity Engine is waiting for the user to check their email and enter the OTP.

var enrollResponse = await idxAuthClient.EnrollAuthenticatorAsync(
   enrollAuthenticatorOptions, (IIdxContext)Session["IdxContext"]);

switch (enrollResponse?.AuthenticationStatus)
{
   case AuthenticationStatus.AwaitingAuthenticatorVerification:
        return RedirectToAction("VerifyAuthenticator", "Manage");
   ...
}

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 sample app reuses the same page for both email and phone verification.

The user submits the SMS OTP

The user checks their phone and copies the OTP into the form. When the user submits the OTP, create a VerifyAuthenticatorOptions object and assign its Code property to the OTP. Pass this object as a parameter to VerifyAuthenticatorAsync().

var idxAuthClient = new IdxClient(null);
var verifyAuthenticatorOptions = new VerifyAuthenticatorOptions
{
   Code = code,
};

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

Complete registration

If the SMS OTP is valid, the returned response object has an AuthenticationStatus of 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. Store the returned tokens in a session and redirect the user to the app's default signed-in page.

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

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

The user skips the phone authenticator

If the user skips phone enrollment, call SkipAuthenticatorSelectionAsync(). This method skips phone enrollment and eliminates the need to verify the factor:

try
{
   var skipSelectionResponse = await idxAuthClient.SkipAuthenticatorSelectionAsync
   ((IIdxContext)Session["IdxContext"]);

   switch (skipSelectionResponse.AuthenticationStatus)
   {
      case AuthenticationStatus.Success:
         ClaimsIdentity identity = await AuthenticationHelper.GetIdentityFromTokenResponseAsync
         (idxAuthClient.Configuration, skipSelectionResponse.TokenInfo);
         _authenticationManager.SignIn(new AuthenticationProperties(), identity);
         return RedirectToAction("Index", "Home");
   }
   return RedirectToAction("Index", "Home");
}
catch (TerminalStateException exception)
{
   TempData["TerminalStateMessage"] = exception.Message;
   return RedirectToAction("Login", "Account");
}
catch (OktaException exception)
{
   ModelState.AddModelError(string.Empty, exception.Message);
   return RedirectToAction("SelectAuthenticator");
}

If the returned response object has an AuthenticationStatus of Success, the user is now registered with no more factors to be verified. Redirect the user to the app's default signed-in page.

The method can also throw exceptions for unsuccessful registrations such as the following:

• TerminalStateException: an exception inherited from OktaException that's raised when an unexpected message is returned from the Okta API and no further remediation is possible.
• OktaException: a general base exception that's raised when any Okta client and API exceptions are thrown.

After a successful registration, store the returned tokens in a session and redirect the user to the app's default signed-in page.

Troubleshooting tips

When you test this use case, ensure that you use a new email for each test. If you have a gmail account, you can reuse the same email by adding a plus (+) and extra text (for example, myemail+1@gmail.com, myemail+2@gmail.com, and so on). Ensure that the password that you use meets the minimum security requirements.

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 app sign-in 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 App sign-in 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 receives an email that uses the Registration - Activation email template. The user clicks the link in the activation email and is redirected to the sample app's home page.