Self-service registration

Identity Engine

Note: In proxy model architectures, where a server-side application using the Embedded SDK is used as a proxy between client applications and Okta servers, a request context for the client applications 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 application rather than the client, this enforcement is not available. As a result, network zones or behaviors that drive their conditions based on these request context values (geolocation, IP Address, or user agent) will not work until we can find a solution to the issue.

This guide covers self-service registration, which allows users to sign up for the app themselves. In this use case, the user must register with a password, email, and/or phone factors. You must first enable the self-service registration option for your app in the 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.

---

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 Okta 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 Identity Engine sample app (opens new window)

---

Configuration updates

Before you can build the self-registration flow in your app, you must configure the Okta org to accept self-registration with the password, email, and/or phone factors. See Set up your Okta org for a multifactor use case to set up the password, email, and phone factors in your Okta org.

In addition to setting up the authentication factors, you also need to configure the following in your Okta org:

1. Update the profile enrollment default policy
2. Confirm that the org application is assigned to everyone
3. Set the Email and Phone authenticators as optional enrollment factors

1: Update the profile enrollment default policy

Enable self-registration in your profile enrollment default policy:

1. In the Admin Console, select Security > Profile Enrollment from the left-hand navigation pane.
2. On the Profile Enrollment page, click the pencil icon next to the Default Policy.
3. On the Default Policy page, under Profile Enrollment, click Edit.
4. In the Profile Enrollment section, select Allowed for Self-service registration.
5. Click Save.

Note: See Managed Profile Enrollment policies (opens new window) for additional profile enrollment policy options.

2: Confirm that the org application is assigned to everyone

For new user registration, your app in your Okta org needs to be assigned to everyone.

1. In the Admin Console, select Applications > Applications from the left-hand navigation pane.
2. On the Applications page, select your application.
3. On your application page, select the Assignments tab.
4. From the left, click the Groups filter.
5. Confirm that the Everyone group appears in the Assignment list.

3: Set the Email and Phone authenticators as optional enrollment factors

1. In the Admin console, select Security > Authenticators from the left-hand navigation pane
2. On the Authenticators page, click the Enrollment tab.
3. In Default Policy, click Edit.
4. Under the Effective factors section of the Edit Policy dialog box, set both email and phone authenticators to optional for enrollment:
   • Set Email Authentication to Optional.
   • Set Phone Authentication 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 and enters their password.

Enroll and verify the email factor

The self-registration flow continues in this sequence.

Enroll and verify the phone (SMS) factor

After the password and email are verified, the user has the option to enroll in the phone factor.

Note: Based on the steps described in Set up your Okta org for a multifactor use case, the Okta application is set up to require one possession factor (either email or phone). After the email factor is verified, the phone factor becomes optional.

The following flow describes the steps when the user enrolls in the optional phone SMS factor.

Skip the optional remaining factors

The user can also opt to skip the factors when all of the remaining factors are optional. In this case, the user opts to skip the phone (SMS) factor.

Integration steps

1: Click the sign-up link

The self-registration flow begins when the user clicks the Sign up link. On the sign-in page, create a Sign up link that links to the create account page.

2: Enter the profile data

The next step for the user after they click the Sign up link is to enter basic information (for example, email, first name, and last name). Create a page that accepts this information. The following wireframe shows an example of a create account page.

3: Select Register

When the user clicks Register, create a UserProfile object and set its properties with the user profile information captured from the create account page. Pass this object into the IdxClient RegisterAsync method.

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);

4: Handle the register response

If the org's application is properly configured with multiple factors, RegisterAsync should return a response with an AuthenticationStatus of AwaitingAuthenticatorEnrollment. This status indicates that there is a required authenticator that needs to be verified. If you completed the steps properly in Set up your Okta org for a multifactor use case, the authenticator is the password factor that is stored in the Authenticators list property.

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

5: Show the password authenticator

The next step is to build a page that shows a user the required factors that need to be verified. After the call to RegisterAsync, the user needs to see the password factor requirement and select it for verification.

The page should be generic and should handle the list of authenticators that are returned from the various methods of the SDK. Use the Authenticators property in the returned response 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);

6: Submit the password authenticator

The next step is to call the EnrollAuthenticatorAsync method when the user selects the authenticator. In this use case, the AuthenticatorId for the password factor is passed.

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

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

7: Handle the submit response

The EnrollAuthenticatorAsync call returns an AuthenticationStatus. If the enrollment is successful, this property should return AwaitingAuthenticatorVerification. When AwaitingAuthenticatorVerification is returned, the next step is to verify the authenticator. In this use case, the user needs to verify with the password authenticator.

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);
}

8: Show the new password page

After AwaitingAuthenticatorVerification is returned, the next step is to build a page that allows the user to supply a new password for verification.

9: Submit the new password

When the user fills out the new password and clicks Register, a call to VerifyAuthenticatorAsync is made to verify (in this use case, to set the password for the new user). Use the Code property in the VerifyAuthenticatorOptions parameter to store the new password.

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

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

10: Handle the submit response

If you completed the steps in Set up your Okta org for a multifactor use case, AuthenticationResponse.AuthenticationStatus should return a status of AwaitingAuthenticatorEnrollment.

The AwaitingAuthenticatorEnrollment status is returned because the required email and optional phone factors await to be enrolled and verified. The user should be redirected to an authenticator list page.

Note: In the previous wireframe, a Skip button is not provided. You could choose to implement a skip option on your authenticators list page when one of the authenticators is optional. Since the email factor is required but the phone is optional, we'll describe it in later steps.

The code snippet below shows how the response is handled. AwaitingAuthenticatorEnrollment identifies that there are additional factors (in this use case, email and optionally phone). The authenticator list page is loaded again (the first time was for password) with the two additional factors.

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

Note The CanSkip property in the code sample above is used for optional factors. See the SDK sample for more information.

11: Submit the email authenticator

If the user selects the email authenticator, call the EnrollAuthenticatorAsync method and pass in the email AuthenticatorId. If the call is successful, a code is sent to the user's email.

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

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

12: Handle the submit response

If the call to EnrollAuthenticatorAsync was successful, it should return an AuthenticationStatus of AwaitingAuthenticatorVerification. When AwaitingAuthenticatorVerification is returned, a code is sent to the user's email, and the user needs to verify this code.

The following sample app code snippet shows that the user is redirected to the verify authenticator page to verify that the code was sent in the email.

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

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

13: Obtain the email verification code from email

Build the email verification code page that accepts the code from the email.

14: Submit the email code

The next step is to call VerifyAuthenticatorAsync. In the email verification, the code that is passed into VerifyAuthenticatorAsync is the code found in the verification email.

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

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

15: Handle the submit response

The next step is to handle the response from VerifyAuthenticatorAsync. If the email code was valid, the method should return AuthenticationStatus of AwaitingAuthenticatorEnrollment. This status signifies that there is another factor (required or optional) waiting to be enrolled and verified. If the steps described in Set up your Okta org for a multifactor use case were properly followed, the user should be sent back to the authenticator list page that shows only the phone authenticator.

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

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

16: Show the remaining list of authenticators

The remaining authenticator should display the phone factor to the user. Since this factor is currently optional and no other required factors need to be verified, the user should have the ability to skip the factor. Create a Skip button for this use case. This Skip button is governed by the CanSkip property on the AuthenticationResponse. See the following screenshot for an illustration.

The user can either enroll in the phone factor or skip the phone factor. Your code should handle both scenarios that will be described in the following steps.

17: Handle the phone authenticator options

18 Option 1: Enroll and verify the phone authenticator

1. Start phone verification

   If the user selects the phone authenticator (instead of skipping it), a call to EnrollAuthenticatorAsync is made passing in the phone AuthenticatorId. If the call was successful, the method should return an AwaitingAuthenticatorEnrollmentData response. The AwaitingAuthenticatorEnrollmentData response indicates that the enrollment data is required before the flow continues to verification.

   In the use case to verify the phone authenticator, the phone number is required, and the user should be redirected to a page where they can enter in a phone number. See the following code snippet from the sample app.

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

2. Show phone entry page

   Build the phone number entry page that accepts the phone number. The user uses the phone number entry page to enroll and verify.

   

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

3. Handle the submit response

   If the call to EnrollAuthenticatorAsync is successful, the AuthenticationStatus of AwaitingAuthenticatorVerification is returned. When AwaitingAuthenticatorVerification is returned, a code is sent to the phone number through SMS.

   In the following code snippet, the user is redirected to a reusable code verification page that handles the code for both email and SMS. Your implementation may vary.

   var enrollResponse = await _idxClient.EnrollAuthenticatorAsync(enrollPhoneAuthenticatorOptions,
      (IIdxContext)Session["IdxContext"]);
      ...
   if (enrollResponse.AuthenticationStatus ==
      AuthenticationStatus.AwaitingAuthenticatorVerification)
      {
         return RedirectToAction("VerifyAuthenticator", "Manage");
      }
   

4. Display phone verification code page

   Build a page that accepts the code sent to your phone number through 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.

   

   var idxAuthClient = new IdxClient(null);
            var verifyAuthenticatorOptions = new VerifyAuthenticatorOptions
            {
                  Code = code,
            };
   
   var authnResponse = await idxAuthClient.VerifyAuthenticatorAsync(verifyAuthenticatorOptions, (IIdxContext)Session["idxContext"]);
   

5. Complete authentication

   The next step is to handle the response from VerifyAuthenticatorAsync. If the phone SMS code was valid, the method should return an AuthenticationStatus of Success. This status signifies that no more factors (required or optional) are waiting to be enrolled and verified.

   If the steps described in Set up your Okta org (for multifactor use cases) were properly followed, the user should now be registered with no more factors to be verified. The user should then be sent to the default page after they have successfully registered. In the sample application, the user is sent to the user profile page.

   var authnResponse = await _idxClient.VerifyAuthenticatorAsync(verifyAuthenticatorOptions, (IIdxContext)Session["idxContext"]);
   Session["idxContext"] = authnResponse.IdxContext;
   
   switch (authnResponse.AuthenticationStatus)
   {
      ...
      case AuthenticationStatus.Success:
            ClaimsIdentity identity = await
            AuthenticationHelper.GetIdentityFromTokenResponseAsync(_idxClient.Configuration,
            authnResponse.TokenInfo);
            _authenticationManager.SignIn(new AuthenticationProperties(), identity);
            return RedirectToAction("Index", "Home");
      ...
   }
   

19 Option 2: Skip phone enrollment

1. If the user opts to skip phone enrollment, a call to SkipAuthenticatorSelectionAsync needs to be made. This method skips phone enrollment and eliminates the need to verify the factor:

   try
   {
         var skipSelectionResponse = await _idxClient.SkipAuthenticatorSelectionAsync
         ((IIdxContext)Session["IdxContext"]);
   
         switch (skipSelectionResponse.AuthenticationStatus)
         {
            case AuthenticationStatus.Success:
               ClaimsIdentity identity = await AuthenticationHelper.GetIdentityFromTokenResponseAsync
               (_idxClient.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");
   }
   

2. Complete authentication

   If SkipAuthenticatorSelectionAsync returns an AuthenticationStatus of Success, the registration is completed successfully. 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 send the user to the default signed-in page. In the sample app, this page is the user profile page. See Get the user profile information for more details on how to fetch user information.

Troubleshooting Tips

When you test this use case, ensure that you use a new email for each time. If you have a gmail account, you can reuse the same email by adding a plus (+) and additional 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 during new user registration with only the password factor required

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

Set up

In this scenario, the org is set up in the following manner:

1. The org is initially configured following the steps described in Set up your Okta org for a multifactor use case.

2. The application's authentication policy is updated for only the password factor. In the Admin Console, the AND User must authenticate with field is set to Password.

3. The Email verification field in the profile enrollment's Default Policy is set to Required before access is granted. You can find the profile enrollment configuration by navigating to Security > Profile Enrollment.

4. The Initiate login URI field is set to the sign-in URI in the application settings. 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.

Flow behavior

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 following email template: Registration - Activation.

The user clicks the link in the activation email and is redirected to the sample app's home page.