IDM 7.5.0

Self-registration REST requests

The REST calls shown in this chapter assume that user registration is enabled with the default security questions, and that the configuration is similar to that shown in the sample registration configuration file (samples/example-configurations/self-service/selfservice-registration.json ):

Example Self-Registration Configuration
{
    "allInOneRegistration" : true,
    "stageConfigs" : [
        {
            "name": "parameters",
            "parameterNames" : [
                "returnParams"
            ]
        },
        {
            "name" : "idmUserDetails",
            "identityEmailField" : "mail",
            "socialRegistrationEnabled" : true,
            "identityServiceUrl" : "managed/user",
            "registrationProperties" : [
                "userName",
                "givenName",
                "sn",
                "mail"
            ],
            "registrationPreferences": ["marketing", "updates"]
        },
        {
            "name" : "termsAndConditions"
        },
        {
            "name" : "emailValidation",
            "identityEmailField" : "mail",
            "emailServiceUrl" : "external/email",
            "emailServiceParameters" : {
                "waitForCompletion" : false
            },
            "from" : "info@admin.org",
            "subject" : "Register new account",
            "mimeType" : "text/html",
            "subjectTranslations" : {
                "en" : "Register new account",
                "fr" : "Créer un nouveau compte"
            },
            "messageTranslations" : {
                "en" : "<h3>This is your registration email.</h3><h4><a href=\"%link%\">Email verification link</a></h4>",
                "fr" : "<h3>Ceci est votre email d'inscription.</h3><h4><a href=\"%link%\">Lien de vérification email</a></h4>"
            },
            "verificationLinkToken" : "%link%",
            "verificationLink" : "https://idm.example.com:8443/#/registration/"
        },
        {
            "name" : "kbaSecurityAnswerDefinitionStage",
            "kbaConfig" : null
        },
        {
            "name" : "selfRegistration",
            "identityServiceUrl" : "managed/user"
        },
        {
            "name" : "localAutoLogin",
            "successUrl" : "",
            "identityUsernameField": "userName",
            "identityPasswordField": "password"
        }
    ],
    "storage" : "stateless"
}
  1. The client loads the initial registration form. The server returns the initial tag to indicate the start of the registration process:

    curl \
     --header "X-OpenIDM-Username: anonymous" \
     --header "X-OpenIDM-Password: anonymous" \
     --header "X-OpenIDM-NoSession: true" \
     --request GET \
     "https://idm.example.com:8443/openidm/selfservice/registration"
    {
      "_id": "1",
      "_rev": "1113597344",
      "type": "parameters",
      "tag": "initial",
      "requirements": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "Parameters",
        "type": "object",
        "properties": {
          "returnParams": {
            "description": "Parameter named 'returnParams'",
            "type": "string"
          }
        }
      }
    }

    The client sends an empty POST request with the submitRequirements action.

    The server returns the following:

    • The initial tag to indicate the start of the registration process.

    • A token that must be provided in subsequent steps.

    • A JSON requirements object that must be provided in subsequent steps.

    Example Registration Submission
    curl \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Password: anonymous" \
    --header "X-OpenIDM-Username: anonymous" \
    --header "X-OpenIDM-NoSession: true" \
    --request POST \
    --data '{"input":{"input":{}}}' \
    https://idm.example.com:8443/openidm/selfservice/registration?_action=submitRequirements
    {
      "type":"allInOneRegistration",
      "tag":"initial",
      "requirements":{
        "$schema":"http://json-schema.org/draft-04/schema#",
        "description":"All-In-One Registration",
        "type":"object",
        "properties":{
          "response":{
            "recaptchaSiteKey":"6Lf...1ry",
            "description":"Captcha response",
            "type":"string"
          },
          "kba":{
            "type":"array",
            "minItems":2,
            "items":{
              "type":"object",
              "oneOf":[
                {
                  "$ref":"#/definitions/systemQuestion"
                },
                {
                  "$ref":"\#/definitions/userQuestion"
                }
              ]
            },
            "questions":[
              {
                "question":{
                  "en":"What’s your favorite color?",
                  "en_GB":"What is your favourite colour?",
                  "fr":"Quelle est votre couleur préférée?"
                },
                "id":"1"
              },
              {
                "question":{
                  "en":"Who was your first employer?"
                },
                "id":"2"
              }
            ]
          },
          "user":{
            "default":{
            },
            "description":"User Object",
            "type":"object"
          },
          "accept":{
            "description":"Accept",
            "type":"string"
          }
        },
        "required":[
          "response",
          "accept",
          "kba"
        ],
        "terms":"These are our terms and conditions",
        "termsVersion":"1.0",
        "uiConfig":{
          "displayName":"We have updated our terms",
          "purpose":"To proceed, accept these terms",
          "buttonText":"Accept"
        },
        "createDate":"2018-11-05T13:14:00.540Z",
        "definitions":{
          "systemQuestion":{
            "description":"System Question",
            "type":"object",
            "required":[
              "questionId",
              "answer"
            ],
            "properties":{
              "questionId":{
                "description":"Id of predefined question",
                "type":"string"
              },
              "answer":{
                "description":"Answer to the referenced question",
                "type":"string"
              }
            },
            "additionalProperties":false
          },
          "userQuestion":{
            "description":"User Question",
            "type":"object",
            "required":[
              "customQuestion",
              "answer"
            ],
            "properties":{
              "answer":{
                 "description":"Answer to the question",
                 "type":"string"
              },
              "customQuestion":{
                 "description":"Question defined by the user",
                 "type":"string"
              }
            },
            "additionalProperties":false
          },
          "providers":{
            "type":"array",
            "items":{
              "type":"object",
              "oneOf":[
              ]
            }
          }
        },
        "socialRegistrationEnabled":false,
        "registrationForm":null,
        "registrationProperties":{
          "properties":{
            "userName":{
              "title":"Username",
              "description":"Username",
              "viewable":true,
              "type":"string",
              "searchable":true,
              "userEditable":true,
              "usageDescription":"",
              "isPersonal":true,
              "policies":[
                {
                  "policyId" : "minimum-length",
                  "params" : {
                    "minLength" : 1
                  }
                },
                {
                  "policyId":"unique"
                },
                {
                  "policyId":"no-internal-user-conflict"
                },
                {
                  "policyId":"cannot-contain-characters",
                  "params":{
                    "forbiddenChars":[
                      "/"
                    ]
                  }
                }
              ]
            },
            "givenName":{
              "title":"First Name",
              "description":"First Name",
              "viewable":true,
              "type":"string",
              "searchable":true,
              "userEditable":true,
              "usageDescription":"",
              "isPersonal":true
            },
            "sn":{
              "title":"Last Name",
              "description":"Last Name",
              "viewable":true,
              "type":"string",
              "searchable":true,
              "userEditable":true,
              "usageDescription":"",
              "isPersonal":true
            },
            "mail":{
              "title":"Email Address",
              "description":"Email Address",
              "viewable":true,
              "type":"string",
              "searchable":true,
              "userEditable":true,
              "usageDescription":"",
              "isPersonal":true,
              "policies":[
                {
                   "policyId":"valid-email-address-format"
                }
              ]
            }
          },
          "required":[
            "userName",
            "givenName",
            "sn",
            "mail"
          ]
        },
        "registrationPreferences":{
          "updates":{
            "description":"Send me news and updates",
            "type":"boolean"
          },
          "marketing":{
            "description":"Send me special offers and services",
            "type":"boolean"
          }
        },
        "stages":[
          "captcha",
          "termsAndConditions",
          "kbaSecurityAnswerDefinitionStage",
          "idmUserDetails"
        ]
      },
      "token":"eyJ0eXAiOiJKV1QiLCJjdHkiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ZXlKMGVYQ...2h-k"
    }
  2. The client sends a POST request with the requirements. The server responds with a request for the emailed code:

    curl \
    --header "Content-type: application/json" \
    --header "X-OpenIDM-Password: anonymous" \
    --header "X-OpenIDM-Username: anonymous" \
    --header "X-OpenIDM-NoSession: true" \
    --request POST \
    --data '{
      "input":{
        "user":{
          "userName":"bjensen",
          "givenName":"Babs",
          "sn":"Jensen",
          "mail":"babs.k.jensen@gmail.com",
          "preferences":{
            "updates":false,
            "marketing":false
          },
          "password":"Passw0rd"
        },
        "kba":[
          {
            "answer":"red",
            "questionId":"1"
          },
          {
            "answer":"forgerock",
            "questionId":"2"
          }
        ],
        "response":"03AMGVjXggloUomtJx2Q0_wAjzyb9lN3LJBRIN67O85eGJIejO6WMlZGZ2jqnz...",
        "g-recaptcha-response":"03AMGVjXggloUomtJx2Q0_wAjzyb9lN3LJBRIN67O85eGJIejO...",
        "accept":"true"
      },
      "token":"eyJ0eXAiOiJKV1QiLCJjdHkiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ZXlKMGVYQWlPa..."
    }' \
    https://idm.example.com:8443/openidm/selfservice/registration?_action=submitRequirements
    {
      "type":"emailValidation",
      "tag":"validateCode",
      "requirements":{
        "$schema":"http://json-schema.org/draft-04/schema#",
        "description":"Verify emailed code",
        "type":"object",
        "required":[
          "code"
        ],
        "properties":{
          "code":{
            "description":"Enter code emailed",
            "type":"string"
          }
        }
      },
      "token":"eyJ0eXAiOiJKV1QiLCJjdHkiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ZXlKMGVYQWl..."
    }

    By default, the snapshot token expires after 300 seconds. If the delay between the first request and the second request is greater than that period, the snapshot token will be invalid and the initial request must be sent again to obtain a fresh snapshot token. You can change the snapshot token expiration time in the self-service process configuration file (selfservice-registration.json in this case).

    The following excerpt of the configuration file shows the default snapshotToken configuration. To change the expiration time, set the tokenExpiry property:

    "snapshotToken" : {
        "type" : "jwt",
        "jweAlgorithm" : "RSAES_PKCS1_V1_5",
        "encryptionMethod" : "A128CBC_HS256",
        "jwsAlgorithm" : "HS256",
        "tokenExpiry" : 300
    },
  3. The email verification link redirects to:

    https://idm.example.com:8443/#/registration/&token=eyJ0e..."

    The client is registered and logged into the End User UI.