Integrating the Hosted Self-Registration Workflow of Next Identity Journeys
With the self-registration feature in Next Identity Journeys, end users are greeted with an intuitive registration screen where they can provide essential details (like email address, first name, and password) to create their accounts.
Need to invite users instead of allowing them to self-register?
In case your application operates on an invitation-only basis, without support for self-registration, consider leveraging the
/pre-registerendpoint provided by Next Identity Journeys API. Learn more.
Hosted Journeys Registration
The registration workflow typically starts by redirecting end users to your sign-in screen via the /authorize endpoint. This step ensures the system verifies if the user already has an existing session or account. On the sign-in screen, if your application is set up to permit self-registration, a registration button will be visible for users to create a new account.
Hosted Journeys Registration Screen
Learn more about the workings and implementation of the /authorize endpoint here.
Email Notification System
The account register process includes an optional email notification system. Existing users attempting to re-register receive an email confirming their registered status, inviting them to log in directly. This ensures a seamless user experience and enhances the registration process's security.
Account Activation Process
After successfully registering, users will receive an email containing a link to activate their account. Clicking on this link will redirect them to a screen where they will see a button to activate their account.
Activate Account CTA Screen
Upon clicking the activation button, users will see a success message confirming that their account has been activated successfully.
Success Message
This additional step ensures that the user's email address is valid and that they have access to it, providing an extra layer of security for the account.
Endpoint URL
https://id.eu.nextreason.com/register?access_type=offline
&client_id={{client_id}}
&environment_id={{env_id}}
&nonce={{nonce}}
&organization_id={{org_id}}
&prompt=consent
&redirect_uri={{redirect_uri}}
&response_type=code
&scope=openid
&state={{state}}
&ui_locales=en-US
Required Parameters
| Parameter | Description |
|---|---|
client_id | The ID used to authenticate the API call. This client ID is tied to your specific configurations and rules. Contact your Next Reason consultant if you do not know your client ID. |
scope | OpenID Connect requests must contain the OpenID scope value. If the OpenID scope value is not present, the behavior is entirely unspecified. Other scope values may be present. Scope values used that are not understood by an implementation should be ignored. The "openid" default value will be used if no specific scope value is known. |
redirect_uri | Configures the URL the user is redirected after a successful authentication. Important note: Ensure the URL is included in the list of allowed URLs for your integration. Contact your Next Reason consultant for assistance with adding URLs to the allowlist |
response_type | Value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints. The only acceptable parameter is: code. |
state | This state parameter is constructed by your application and included in the call to the hosted Next Identity service. It will remain unchanged and will be passed back to your application when the screen is redirected back. It is intended for use by your application to track user state. It should be an opaque value used to maintain state between the request and the callback. Typically for applications, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie. This value is required on every call, but the hosted service does not use this value in any way, it is solely for use by the application. Doing so, the application can check and evaluate the value of the state parameter if it is correct or meets a specified criteria then perform expected actions or user journeys on the application-side. |
Optional Parameters
| Parameter | Description |
|---|---|
prompt | Space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are:noneThe Authorization Server must not display any authentication or consent user interface pages. An error is returned if a user is not already authenticated or the client does not have pre-configured consent for the requested claims or does not fulfill other conditions for processing the request. This can be used as a method to check for existing authentication and/or consent. loginThe Authorization Server should prompt the user for reauthentication. If it cannot reauthenticate the user, it must return an error, typically login_required. |
nonce | String value used to associate a client session with an ID token and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. |
ui_locales | Set the language to be displayed in the screen. Session cookie will save the locale setting sent for the first time, if this parameter is not present the latest language saved will be used to display the screen. It allows multiple locales and in case there's no configuration for the first one, it searches for the second one and so on. Since the ui_locales parameter is optional and will use the default_locale on settings if no value is present.See Localization for list of supported locales and the accepted values. The default country flag during mobile login or when changing the mobile number will be determined by the ui_locales in the query string parameters, if the mobile_query_default_flag is set in the configuration settings. If not, it will fall back to the mobile_default_country, then to the first value in the mobile_flag_countries setting, and finally to the default_locale. |
environment_id | The ID of the environment where the client is created. Each environment (for example, DEV, UAT or PROD) has their own environment_id. |
organization_id | The ID of the organization in the Next Identity. Each Organization has their own organization_id. |
code_challenge | Used in PKCE (Proof Key for Code Exchange) protocol. |
code_challenge_method | Used in PKCE (Proof Key for Code Exchange) protocol. |
login_hint | If this parameter value is passed with the call to the /authorize or /register endpoints, the email address or mobile number field on the hosted screen will be pre-filled. This applies to both email addresses and mobile phone numbers. |
Response Handling
After successful registration, users will receive an Activation Email. User needs to activate his account before he can login to the application.
Configuration Options
The attributes are customizable based on the requirements. The following fields can be added in the register form.
| Profile Fields | Description |
|---|---|
| Gender | Allows the user to select the gender |
| Security Questions | Allows the user to select his preferred security questions and provide the answer |
| Mobile Number | The profile field needed if authentication method is SMS |
| Company Name | Allows user to add company name |
| 2-Step Mobile | Mobile number that can be used for 2-factor authentication |
Error Handling
| Code | Error | Cause |
|---|---|---|
| No code, error message only | Email address is not formatted correctly | Email address format was not formatted correctly |
| No code, error message only | Passwords do not match | Passwords do not match |
| No code, error message only | You are not able to register with this email address | Email address is not allowed |
| 503 | We are unable to process your request right now. Please try again later. | Incorrect client_id |
Security Considerations
While the state parameter is not directly used within the register endpoint itself, it plays a critical role in ensuring the secure handling of the authorization process that leads to accessing the profile endpoint.
Integration
- On login screen (/authorize endpoint), click the Register link
- Fill in all required details on registration form then click Submit
- Access the email or mobile to complete the account activation