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.

---

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

Android 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 Enrollment Settings, click the actions menu icon (⋮) beside the ENABLED flag for the rule and select Edit.
4. In the Edit Rule dialog box, under the For new users section, select Allowed in the Sign-up field.
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

The sequence of steps for self-service registration is described in the following three sequence diagrams.

Start a new user registration with the password authenticator

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 authenticator

After being shown the list of available authenticators, the customer continues the self-registration flow by selecting the email authenticator.

Skip the optional remaining authenticators

After the password and email authenticators are verified, the user has the option to skip the phone authenticator.

Enroll and verify the phone (SMS) authenticator

After the password and email authenticators are verified, the user has the option to enroll the phone authenticator.

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

The following flow describes the steps when the user enrolls the optional phone authenticator.

Integration steps

1: Register new users

The self-registration flow begins when the user clicks the Sign up link on your app's sign-in page. Create a Sign up link that directs the user to a create account form, similar to the following wireframe.

You need to create a form to capture the user's new account details.

Begin the authentication process by calling the Java SDK's IDXAuthenticationWrapper.begin() (opens new window) method.

val beginResponse = idxAuthenticationWrapper.begin()

After the authentication transaction begins, you need to call getProceedContext() to get the ProceedContext (opens new window) object that contains the current state of the authentication flow, and pass it as a parameter in an IDXAuthenticationWrapper.fetchSignUpFormValues() call to dynamically build the create account form:

val beginProceedContext = beginResponse.getProceedContext()
val newUserRegistrationResponse = idxAuthenticationWrapper.fetchSignUpFormValues(beginProceedContext)

Note: IDXAuthenticationWrapper.fetchSignUpFormValues() allows you to build the create account form dynamically from the required form values using AuthenticationResponse#getFormValues.

2: The user enters their profile data

Enroll the user with basic profile information captured from the create account form by calling the IDXAuthenticationWrapper.register() method.

val userProfile = UserProfile()
userProfile.addAttribute("lastName", lastname)
userProfile.addAttribute("firstName", firstname)
userProfile.addAttribute("email", email)

val proceedContext = newUserRegistrationResponse.getProceedContext()

val authenticationResponse = idxAuthenticationWrapper.register(proceedContext, userProfile)

3: Display the enrollment authenticators

After you've configured your org and app with instructions from Set up your Okta org for a multifactor use case, your app is configured with Password authentication, and additional Email or Phone authenticators. Authenticators are the factor credentials, owned or controlled by the user, that can be verified during authentication.

This step contains the request to enroll a password authenticator for the user.

After the initial register request, IDXAuthenticationWrapper.register() returns an AuthenticationResponse (opens new window) object that contains the following properties:

1. AuthenticationStatus = AWAITING_AUTHENTICATOR_ENROLLMENT_SELECTION
   This status indicates that there are required authenticators that need to be verified.

2. Authenticators = List of authenticators (opens new window) (in this case, there is only the password authenticator).
   

   val authenticators = authenticationResponse.authenticators
   

After receiving the AWAITING_AUTHENTICATOR_ENROLLMENT_SELECTION status and the list of authenticators, you need to provide the user with a form to select the authenticator to enroll. In the following wireframe, there is only one password authenticator to enroll.

4: The user selects the authenticator to enroll

Pass the user-selected authenticator (in this case, the password authenticator) to the IDXAuthenticationWrapper.selectAuthenticator() method.

val authenticationResponse = idxAuthenticationWrapper.selectAuthenticator(proceedContext, authenticator)

This request returns an AuthenticationResponse object with AuthenticationStatus=AWAITING_AUTHENTICATOR_VERIFICATION. You need to build a form for the user to enter their password in this authenticator verification step.

5: Verify the authenticator and display additional authenticators

After the user enters their new password, call the IDXAuthenticationWrapper.verifyAuthenticator() method with the user's password.

val verifyAuthenticatorOptions = VerifyAuthenticatorOptions(newPassword)
val authenticationResponse = idxAuthenticationWrapper.verifyAuthenticator(proceedContext, verifyAuthenticatorOptions)

The request returns an AuthenticationResponse object with AuthenticationStatus=AWAITING_AUTHENTICATOR_ENROLLMENT_SELECTION and an Authenticators list that contains the email and phone factors.

6: The user selects the email authenticator

In this use case, the user selects the Email authenticator as the authenticator to verify. Pass this user-selected authenticator to the IDXAuthenticationWrapper.selectAuthenticator() method.

val authenticationResponse = idxAuthenticationWrapper.selectAuthenticator(proceedContext, authenticator)

If this request is successful, a code is sent to the user's email and AuthenticationStatus=AWAITING_AUTHENTICATOR_VERIFICATION is returned. You need to build a form to capture the code for this verification step.

7: The user submits the email verification code

The user receives the verification code in their email and submits it in the verify code form. Use VerifyAuthenticationOptions (opens new window) to capture the code and send it to the IDXAuthenticationWrapper.verifyAuthenticator() method:

val verifyAuthenticatorOptions = VerifyAuthenticatorOptions(code)
val authenticationResponse =
    idxAuthenticationWrapper.verifyAuthenticator(proceedContext, verifyAuthenticatorOptions)

If the request to verify the code is successful, the SDK returns an AuthenticationResponse object with AuthenticationStatus=AWAITING_AUTHENTICATOR_ENROLLMENT_SELECTION property and an Authenticators list that contains the phone factor. Reuse the authenticator enrollment form from 3: Display enrollment factors to display the list of authenticators to the user.

Based on the configuration described in Set up your Okta org for a multifactor use case, the app in this use case is set up to require one possession factor (either email or phone). After the email factor is verified, the phone factor becomes optional. In this step, the isSkipAuthenticatorPresent() function returns TRUE for the phone authenticator. You can build a Skip button in your form to allow the user to skip the optional phone factor.

If the user decides to skip the optional factor, they are considered signed in since they have already verified the required factors. See Step 8, Option 1: The user skips the phone authenticator for the skip authenticator flow. If the user decides to select the optional factor, see Step 8, Option 2: The user selects the phone authenticator for the optional phone authenticator flow.

8: Handle the phone authenticator options

Option 1: The user skips the phone authenticator

If the user decides to skip the phone authenticator enrollment, make a call to the IDXAuthenticationWrapper.skipAuthenticatorEnrollment() method. This method skips the authenticator enrollment.

val authenticationResponse = idxAuthenticationWrapper.skipAuthenticatorEnrollment(proceedContext)

Note: Ensure that isSkipAuthenticatorPresent()=TRUE for the authenticator before calling skipAuthenticatorEnrollment().

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

Option 2: The user selects the phone authenticator

In this use case option, the user selects the optional Phone authenticator for verification. Pass this selected authenticator to the IDXAuthenticationWrapper.selectAuthenticator() method.

val authenticationResponse = idxAuthenticationWrapper.selectAuthenticator(proceedContext, authenticator)

The response from this request is an AuthenticationResponse object with AuthenticationStatus=AWAITING_AUTHENTICATOR_ENROLLMENT_DATA.

This status indicates that the user needs to provide additional authenticator information. The user must then enter their phone number and the SMS verify method is sent automatically (1), or the user enters their phone number and selects either the SMS or the Voice Verify method (2).

1. The user enters their phone number and the SMS verify method is sent automatically

This step assumes that the voice feature isn't enabled in your org. The phone verification code is sent through SMS automatically.

When the user submits their phone number, capture this information and pass it to the IDXAuthenticationWrapper.verifyAuthenticator() method. In the following code example, the user phone number is encapsulated in the verifyAuthenticatorOptions object:

val authenticationResponse =
   idxAuthenticationWrapper.verifyAuthenticator(proceedContext, verifyAuthenticatorOptions)

The Java SDK sends the phone authenticator data to Okta. Okta processes the request and sends an SMS code to the specified phone number. After the SMS code is sent, Okta sends a response to the SDK, which returns AuthenticationStatus=AWAITING_AUTHENTICATOR_VERIFICATION to your client app. This status indicates that the user needs to provide the verification code for the phone authenticator.

You need to build a form to capture the user's SMS verification code.

2. The user enters their phone number and selects either the SMS or the Voice Verify method

This step assumes that your org is enabled with the voice feature.

You need to build a form to capture the user's phone number as well as a subsequent form for the user to select their phone verification method (either SMS or voice).

Note: The Java SDK requires the following phone number format: {+}{country-code}{area-code}{number}. For example, +15556667777.

When the user enters their phone number and selects a method to receive the verification code, capture this information and send it to the IDXAuthenticationWrapper.submitPhoneAuthenticator() method.

val authenticationResponse =
   idxAuthenticationWrapper.submitPhoneAuthenticator(proceedContext, phone, factor)

The Java SDK sends the phone authenticator data to Okta. Otka processes the request and sends a code to the specified phone number. After the code is sent, Okta sends a response to the SDK that returns AuthenticationStatus=AWAITING_AUTHENTICATOR_VERIFICATION to your app. This status indicates that the user needs to provide the verification code for the phone authenticator.

Note: If the user selects Voice as the phone verification method, Okta sends an automated voice message with the verification code to the specified phone.

You need to build a form to capture the user's verification code.

The user submits the SMS verification code

The user receives the verification code as an SMS on their phone and submits it in the verify code form. Send this code to the IDXAuthenticationWrapper.verifyAuthenticator() method:

val verifyAuthenticatorOptions = VerifyAuthenticatorOptions(code)
val authenticationResponse =
   idxAuthenticationWrapper.verifyAuthenticator(proceedContext, verifyAuthenticatorOptions)

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

Resend the code

Sometimes the user needs to have the code resent. To implement that functionality, use the following:

 val response = authenticationWrapper.resend(proceedContext)

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 sign-on 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.