Usage of self-registration
17.2.3.2. Usage - User self-registration flows
17.2.3.2.1. Steps
17.2.3.2.1.1. List of possible REST calls

For a detailed explanation of the REST interface, please refer to Loginapp REST API Reference.

17.2.3.2.1.2. Step 1 - User data registration step

This request starts the self-registration of a user. Since no flow is selected explicitly, the default flow is started.

Step 1 - HTTP request - user data registration step

copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/data/ 
{
    "surname" : "Doe",
    "email" : "john.doe@ergon.ch",
    "town" : "Zürich",
    "birthdate" : "1970-10-01"
}

A successful response will return a value of "USER_DATA_REGISTRATION_REQUIRED" if the call was successful but a call to continue would fail. Use the validate call to list all validation issues.

Step 1 - HTTP response - user data registration step

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-12-12T08:43:48.356Z"
    },
    "data": {
        "type": "user-self-registration.session",
        "id": "509880836941347711",
        "attributes": {
            "nextStep": "USER_DATA_REGISTRATION_REQUIRED"
        }
    }
}

Since the given name is mandatory, but was missing from the previous call, another call to the /data/ REST API is required.

Step 1 - HTTP request - user data registration step

copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/data/ 
{
    "givenname" : "John"
}

A successful response will return a value of "USER_DATA_REGISTRATION_POSSIBLE" if the call was successful and a call to continue will be successful as well.

Step 1 - HTTP response - user data registration step

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-12-12T08:44:33.047Z"
    },
    "data": {
        "type": "user-self-registration.session",
        "id": "509880836941347711",
        "attributes": {
            "nextStep": "USER_DATA_REGISTRATION_POSSIBLE"
        }
    }
}
17.2.3.2.1.3. Continue

This request is required to move the flow one step ahead.

Step 1 - HTTP request - continue

copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/continue

Since we already know that the validation was successful, the response should always be a 200 OK.

Step 1 - HTTP response - continue

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-12-12T08:50:39.232Z"
    },
    "data": {
        "type": "user-self-registration.session",
        "id": "509880836941347711",
        "attributes": {
            "nextStep": "EMAIL_OTP_REQUIRED"
        }
    }
}
17.2.3.2.1.4. Step 2 - Username generation step

Step 2 is non-interactive and does not require any REST calls to be executed.

17.2.3.2.1.5. Step 3 - Email verification step

When the email verification step is started, it first generates a message and sends it to the channel verification target (i.e. the email address) to be verified.

Email Message

Sehr geehrte(r) John Doe

Bitte bestätigen Sie die Registrierung mit Benutzername john.doe@ergon.ch mit diesem Code: umFWMZ4S.

Freundliche Grüsse, Ihr IAM-Team

In the user interface, the user is required to enter the code provided in the message to be entered.

Step 3 - HTTP request - email verification step

copy
POST https://iam-host.com/auth/rest/public/user-self-registration/verification/email/otp/check/
{
    "otp" : "umFWMZ4S"
}

Step 3 - HTTP response - email verification step

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-12-12T08:51:19.268Z"
    },
    "data": {
        "type": "user-self-registration.session",
        "id": "509880836941347711",
        "attributes": {
            "nextStep": "USER_DATA_REGISTRATION_REQUIRED"
        }
    }
}
17.2.3.2.1.6. Step 4 - User data registration step

Step 4 - HTTP request - user data registration step

copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/password/
{
        "password" : "password0"
}

Step 4 - HTTP response - user data registration step

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-12-12T08:51:44.996Z"
    },
    "data": {
        "type": "user-self-registration.session",
        "id": "509880836941347711",
        "attributes": {
            "nextStep": "USER_DATA_REGISTRATION_POSSIBLE"
        }
    }
}
17.2.3.2.1.7. Continue

This request is required to move the flow one step ahead.

Step 4 - HTTP request - continue

copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/continue

Since we already know that the validation was successful, the response should always be a 200 OK.

Step 4 - HTTP response - continue

copy
HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-12-12T08:52:02.237Z"
    },
    "data": {
        "type": "user-self-registration.session",
        "id": "509880836941347711",
        "attributes": {}
    }
}
17.2.3.2.1.8. Step 5 - User persisting step

After the continue, the user persisting step will be executed automatically.

17.2.3.2.2. Other REST examples
17.2.3.2.2.1. Error response

In this request, the birthdate attribute contains incorrectly formatted input.

HTTP request - user data registration step with incorrect data

copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/data/ 
{
    "surname" : "Doe",
    "givenname" : "John",
    "email" : "jdoe@ergon.ch",
    "town" : "Zürich",
    "birthdate" : "1.1.1970"
}

In case of an error (in the example below the formatting of the birthdate was incorrect) a detailed error message is returned:

HTTP response failure - user data registration step

copy
HTTP/1.1 400 Bad Request
 
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-12-12T09:01:47.225Z",
        "nextStep": "USER_DATA_REGISTRATION_REQUIRED"
    },
    "errors": [
        {
            "code": "VALIDATION_FAILED",
            "source": {
                "pointer": "/birthdate"
            },
            "meta": {
                "type": "jsonapi.metadata.validation.error",
                "detail": "WRONG_FORMAT"
            }
        }
    ]
}
17.2.3.2.2.2. Validate

The validate REST call is strictly speaking optional, but it is rather helpful for a GUI client to provide the end-user with information on why a particular set of data was rejected by the registration flow validation.

Note: it is possible to issue this call as the first call in the flow. This would allow the GUI to dynamically indicate to the user, which fields are mandatory and must be filled without hardcoding and before the user submits the form.

HTTP Request: validate

copy
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/validate

The validation returns all "errors" that must be addressed before a continue to the next step in the flow is possible. 

Note: a 200 OK return code implies that the validation was successful and the step can be continued. A 400 Bad Request is returned to indicate issues with validation. 

HTTP Response: validate

copy
HTTP/1.1 400 Bad Request
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2018-12-12T08:55:38.700Z",
        "nextStep": "USER_DATA_REGISTRATION_REQUIRED"
    },
    "errors": [
        {
            "code": "VALIDATION_FAILED",
            "source": {
                "pointer": "/email"
            },
            "meta": {
                "type": "jsonapi.metadata.validation.error",
                "detail": "REQUIRED"
            }
        },
        {
            "code": "VALIDATION_FAILED",
            "source": {
                "pointer": "/givenname"
            },
            "meta": {
                "type": "jsonapi.metadata.validation.error",
                "detail": "REQUIRED"
            }
        },
        {
            "code": "VALIDATION_FAILED",
            "source": {
                "pointer": "/surname"
            },
            "meta": {
                "type": "jsonapi.metadata.validation.error",
                "detail": "REQUIRED"
            }
        }
    ]
}