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"
}-
The client loads the initial registration form. The server returns the
initialtag 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
submitRequirementsaction.The server returns the following:
-
The
initialtag to indicate the start of the registration process. -
A
tokenthat must be provided in subsequent steps. -
A JSON
requirementsobject 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" } -
-
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.jsonin this case).The following excerpt of the configuration file shows the default
snapshotTokenconfiguration. To change the expiration time, set thetokenExpiryproperty:"snapshotToken" : { "type" : "jwt", "jweAlgorithm" : "RSAES_PKCS1_V1_5", "encryptionMethod" : "A128CBC_HS256", "jwsAlgorithm" : "HS256", "tokenExpiry" : 300 }, -
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.