Self-registration requests (self_register_requests)

Overview

Manages user self-registrations.

Two-step algorithm:

  • 1. POST request from an unauthorized user to send an email with an email address confirmation link.

    • 1.1. Check for the 'domain', 'login', 'name', 'email' fields in the JSON request body. The domain must be from the list allowing self-registration (defaults.json, Settings fields 'self_register_*').

    • 1.2. Verify the correctness of the specified values and, if necessary, verify uniqueness.

    • 1.3. Create the system/SelfRegisterRequests entity with a 1-day lifetime limit.

    • 1.4. Send an email to the user with a link containing the UUID of the registration request. The link leads to the system web application /app-root, but it contains an identifier that can be used to call the API directly with a PATCH request.

  • 2. PATCH request to confirm the email and set the password.

    • 2.1. Check for the 'pwd' field in the JSON request body.

    • 2.2. Verify the invitation validity based on the identifier passed in the URL.

    • 2.3. Send a request to create the user account in MDC and check the password complexity policy.

    • 2.4. On success, delete the system/SelfRegisterRequests entity.

The created user account is formed by merging the template (domain setting 'self_register_template') and the values specified during self-registration: 'name', 'login', 'pwd', 'opts.email'. The identifier is generated randomly. The 'opts.self_registered' field is set to 'true'.

Servicing is performed by the mware, email, and ws microservices.

For successful email sending, configure the mail server profile, the mail server account, and set its 'isSystem' flag.

Requests

HTTP verb Endpoint Description

POST

/rest/v1/iam/self_register_requests

Sending an invitation

PATCH

/rest/v1/iam/self_register_requests/<id>

Confirming the mailbox and setting the password


Sending an invitation

Step 1/2 of the two-step self-registration algorithm.

Creates a draft user account and sends an email to confirm the email address.

Performed by an unauthorized user.

Only an existing domain allowing self-registration may be specified as the domain (setting 'self_register_allowed').

The request may be performed no more than once every 2 minutes from the same IP address.

Request

Example request
POST /rest/v1/iam/self_register_requests HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "domain": "pbx.incoplax.com",
  "login": "my_login",
  "name": "My Name",
  "email": "my.address@email.com",
}

Response

Example successful response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "error_code": 0,
  "result": true,
  "result_msg": "Check your email box for confirmation URL"
}
Example failed response
HTTP/1.1 412 Precondition failed
Content-Type: application/json; charset=utf-8

{
  "error_code": 1501,
  "error_message": "login already exists",
  "error_details":{
    "field": "login"
  }
}

Confirming the mailbox and setting the password

Step 2/2 of the two-step self-registration algorithm.

Request

Example request
PATCH /rest/v1/iam/self_register_requests/19738eb3-0183-b148-9420-7cd30a921f58 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "pwd": "ew!hIb3V"
}

Response

Example successful response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "error_code": 0,
  "result": true,
  "result_msg": "Now login with new password",
  "user":{
    "domain": "pbx.incoplax.com",
    "login": "mylogin"
  }
}
Example failed response
HTTP/1.1 412 Precondition failed
Content-Type: application/json; charset=utf-8

{
  "error_code": 1501,
  "error_message": "pwd contains invalid symbols. Expected: A-Za-z0-9_-.~!",
  "error_details":{
    "field": "pwd"
  }
}

Error codes

Possible message types (the 'error_details.msg_code' field): 100xx, 101xx, 102xx, 152xx.