IDM 7.5.0

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 User self-registration form.

    • registrationPreferences: lists preferences to include as defined in the managed.json file. For more information, refer to 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 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, refer to Self-Service registration emails.

  • 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, refer to Security questions.

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

    If you’ve activated Google reCAPTCHA for user self-service registration, you’ll refer to 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, refer to 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 refer to 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 refer to 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, refer to Query the Activity Audit Log

Configure self-registration using the admin UI

To configure user self-registration using the admin UI:

  1. From the navigation bar, click Configure > User Registration.

  2. On the User Registration page, enable Enable User Registration.

    When you enable self-registration using the admin UI, IDM creates selfservice-registration.json if it doesn’t already exist.
  3. Configure options in the Configure Registration Form window:

    • 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 this URL. By default, {hostname}/#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 JSON Web Token (JWT).

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

  4. Click Save.

    Now that User Registration is active, three tabs display on the User Registration page:

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 matches the contents of your project’s selfservice-registration.json file.

To update the configuration over REST, include the desired file contents:

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> }' \
Copyright © 2010-2024 ForgeRock, all rights reserved.