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.
4: Handle the register response
If the org's application is properly configured with multiple factors,
RegisterAsync should return a response with an
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.
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.
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.
7: Handle the submit response
EnrollAuthenticatorAsync call returns an
AuthenticationStatus. If the enrollment is successful, this property should return
AwaitingAuthenticatorVerification is returned, the next step is to verify the authenticator. In this use case, the user needs to verify with the password authenticator.
8: Show the new password page
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
to store the new password.
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 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.
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.
12: Handle the submit response
If the call to
EnrollAuthenticatorAsync was successful, it should return an
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.
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.
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
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.
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
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.
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.
![A form with a field for a phone number, formatting advice and a next button](/img/wireframes/enter-phone-number-form.png)
Handle the submit response
If the call to
EnrollAuthenticatorAsync is successful, the
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.
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.
The next step is to handle the response from
VerifyAuthenticatorAsync. If the phone SMS code was valid, the method should return an
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.
19 Option 2: Skip phone enrollment
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:
SkipAuthenticatorSelectionAsync returns an
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.
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,
firstname.lastname@example.org, and so on). Ensure that the password that you use meets the minimum security requirements.