Configure User Self-Registration

To set up basic user self-registration, you'll need at least the following configuration files:


You can find this file in the default IDM project configuration directory, openidm/conf.

To enable self-service registration in the UI, enable the following boolean property in ui-configuration.json:

"selfRegistration" : true,

You can find a template version of this file in the following directory: openidm/samples/example-configurations/self-service. This includes the following properties:

  • allInOneRegistration: determines whether IDM collects all user registration information in one or multiple pages. By default, it's set to true:

    "allInOneRegistration" : true,
  • stageConfigs: configuration details for the stages included in the self-registration process. While the specific stages included may vary, most processes will include at least:

    • idmUserDetails: includes the IDM property for email addresses (mail), whether or not registration with social identity providers is enabled, and what data is required from new users, as described in "Configure the User Self-Registration Form".

    • registrationPreferences: lists preferences to include as defined in the managed.json file. For more information, see "Configure User Preferences".

  • snapshotToken: configuration details for the token used to store the user's details during the registration process.

  • storage: determines how a user's details are stored for consumption by later stages in the registration process. By default, this is set to stateless.

Depending on how you configure User Self-Registration, you may need to set up additional configuration files, as discussed in "Configure the User Self-Registration Form".

Common components included in self-registration include:

  • Email validation

    If you have included email verification, you must configure an outgoing email server. For details about the required addition to selfservice-registration.json, see "Configuring Emails for Self-Service Registration".

  • Security questions (KBA)

    If you have configured security questions, users who self-register must create these questions during registration and answer them during the password reset process. You can also configure the system to force users who have been created during a reconciliation from an external data store to add security questions. The relevant code block is shown here, which includes security questions as a stage in the user self-registration process. For related configuration options, see "Configure Security Questions".

        "name" : "kbaSecurityAnswerDefinitionStage",
        "kbaConfig" : null
  • Google ReCAPTCHA

    If you've activated Google reCAPTCHA for user self-service registration, you'll see the following code block:

        "name" : "captcha",
        "recaptchaSiteKey" : "<siteKey>",
        "recaptchaSecretKey" : "<secretKey>",
        "recaptchaUri" : ""

    As suggested by the code, you'd substitute the actual siteKey and secretKey assigned by Google for your domain. For more information, see "Configure Google reCAPTCHA".

  • Terms & Conditions

    If you've set up Terms & Conditions, users who self-register will have to accept them, based on criteria you create, as discussed in "Terms & Conditions". If you've included Terms & Conditions with user self-registration, you'll see the following code block:

        "name" : "termsAndConditions"

    New users will have to manually accept these conditions before they complete the self-registration process.

  • Privacy & Consent

    If you've configured Privacy & Consent, you'll see a code block with the consent name. The following code block includes template Privacy & Consent terms in English (en) and French (fr):

        "name" : "consent",
        "consentTranslations" : {
            "en" : "Please consent to sharing your data with whomever we like.",
            "fr" : "Veuillez accepter le partage de vos données avec les services de notre choix."


    Substitute Privacy & Consent content that meets the requirements of your legal authorities.

For audit activity data related to user self-registration, see Query the Activity Audit Log.

Configure Self-Registration From the Admin UI

To configure user self-registration from the Admin UI, select Configure > User Registration, and select Enable User Registration on the page that appears. When you enable self-registration from the Admin UI, IDM will create selfservice-registration.json for you, if it is not already present. When enabled, you'll see a pop-up window that specifies User Registration Settings, including the following:

  • Identity Resource, typically managed/user.

  • Identity Email Field, typically mail or email.

  • Success URL for the End User UI; users who successfully log in are redirected to that URL. By default, the success URL is http://localhost:8080/#dashboard/.

  • Preferences, which set up default marketing preferences for new users. New users can change these preferences during registration, or from the End User UI.

  • Advanced Options, Snapshot Token, typically a JSON Web Token (JWT).

  • Advanced Options, Token Lifetime, with a default of 300 seconds.

Once active, you'll see three tabs under User Registration in the Admin UI:

Managing User Self-Registration Over REST

To display the current user self-registration configuration over REST, run the following command:

curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Accept-API-Version: resource=1.0" \
 --request GET \

Unless you have disabled file writes, the output will match the contents of your project's selfservice-registration.json file. For information on disabling file writes, see "Disabling Automatic Configuration Updates".

If needed, you can update this configuration by including the desired contents of the file:

curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --header "Accept-API-Version: resource=1.0" \
 --header "Content-Type: application/json" \
 --request PUT \
 --data '{ <Insert file contents here> }' \
Read a different version of :