Creating and Integrating Custom User Registration Pages with Identity Pools APIs

Learn how to implement and integrate custom user registration pages using Identity Pools APIs.

Implementing User Registration Pages - Overview

Implementing a user registration page can be a complex process, but it is essential for many websites and applications that require user authentication and authorization. Even though, SecureAuth Identity Pools come with a built-in and brandable user registration page, some businesses may require creating a custom one in order to apply advanced branding, support custom registration flows, and more. Here are some key considerations to keep in mind when implementing a user registration page:

Required Information: Decide what information you need from users during the registration process. Typically, this includes a username, email address, and password. Depending on the website or application, you may also need additional information, such as a full name, phone number, or address.
Password Security: Passwords should be encrypted and stored securely. Consider requiring users to create strong passwords that meet certain complexity requirements, such as minimum length and a mix of upper and lowercase letters, numbers, and special characters.
Verification: Consider implementing email verification to confirm that the user's email address is valid and belongs to them. This step can help prevent spam and fraudulent accounts.
User Experience: Ensure that the registration process is user-friendly and easy to navigate. Make sure that the registration form is clear and straightforward, and provide helpful instructions or tooltips to guide users through the process.
Error Handling: Implement error handling to catch common errors and provide meaningful feedback to users when there is an issue with their registration. For example, if a user tries to register with an email address that is already in use, provide a clear error message that explains the issue and suggests a solution.

To ensure the security of user data during the registration process, it is essential to implement additional security measures beyond the basic username, email address, and password fields. Personal information, such as full name, address, and phone number, may be required, so it's crucial to transfer and store it securely.

One way to achieve this is to create a web application that consists of a frontend and a backend. The frontend is responsible for collecting user input, while the backend is responsible for processing and storing user data securely. To add an extra layer of security, consider implementing features like OAuth mTLS.

Implement Custom Registration Page Using SecureAuth Identity Pools APIs

You can integrate your custom user registration page with SecureAuth Identity Pools in two ways:

Prerequisites

Client application registered and configured in the System workspace within your tenant
You will use this client application to get a System-level access token to authenticate your user registration page to SecureAuth authorization server before calling Identity Pools APIs.
Identity Pools configured on the tenant level (optional)
Before jumping into calling SecureAuth Identity Pools APIs to register users, you may want to configure Identity Pools first. For example, make sure that your Identity Pools payload and metadata schemas reflect the attributes you will get from the user during the registration process (payload) or set for them yourself (metadata).

Integrate Using Self Register User API - Recommended

The Self Register User API is used by SecureAuth in the Identity Pools built-in user registration page. It allows allows user creation with only the essential data provided by users, skipping a user identifier and verification when applicable.

A User provides their registration data to the User Registration Application
The User Registration Application sends a request to SecureAuth OAuth 2.0 Token Endpoint.
The request must contain the identity and identity_self_registration scopes added as the value of the scope request body parameter.
How the User Registration Application authenticates to the SecureAuth authorization server is at the implementer's hand to decide. If the application is divided into frontend and backend part, the client credentials flow and the mTLS-based client authentication can be used. If the application has no backend, consider using the client authentication method set to none and with the use of PKCE.
SecureAuth mints an access token and provides it to the User Registration Application for consumption.
The User Registration Application sends a request to the SecureAuth Self Register User endpoint.
Example:
```
curl -X POST https://{tenantID}.{region}.authz.cloudentity.io/api/identity/{tenantID}/system/pools/{ipID}/user/register?send_activation_message=true&code_type_in_message=code
-H 'Content-Type: application/json'
-H 'Authorization: Bearer $AT'
-d '{"identifier":"jdoe@cloudentity.com","password":"superS3cureP@ssword","payload":{"given_name":"John","family_name":"Doe","name":"sir John Doe II"}}'
```
The request MUST contain the access token the application got from SecureAuth in the third step.
User attributes may be provided as the values of the payload request body parameter.
Important
Whether SecureAuth sends an email to the user with the activation message (either link or code), it is controlled by the send_activation_message (set to true by default). If you wish to change this behavior, proceed to the optional steps described further. You can either go with SecureAuth-branded email being sent (steps 9-13) or request activation code from SecureAuth and provide it to the user in your own email template (steps 14-20).
At this point, SecureAuth verifies:
- If user self-registration is allowed in the Identity Pools settings. If not, the request fails.
- If the identifier sent is not already used as someone's verified address. If yes, the request silently passes, but instead of the activation message, it sends a message that there is already an account registered with the provided address.
SecureAuth sends a message to the user either with activation link or code.
The activation message content (link or code) can be changed by setting the code_type_in_message query parameter when requesting to the Self Register User endpoint.
At this point, if the activation message content are set to code, the User Registration Application should redirect the user to a page where they can enter the activation code they received from SecureAuth via email.
User selects the link provided in the activation message or provides the activation code to the User Registration Page for verification.
If the activation code contents were set to link, the user account is activated and email is marked as verified. If the identifier is not already taken, the identifier (matching address) is added to the user.
The User Registration Application sends a request to the SecureAuth Activate User With Code endpoint.
The access token provided in the request, must contain the identity and identity_self_registration scopes.
SecureAuth activates the user and sets their email to verified.
If the activation code contents were set to link, the user account is activated and email is marked as verified. If the identifier is not already taken, the identifier (matching address) is added to the user.
Optional Steps Described Below
The steps below are optional and should be used only if you chose to set the send_activation_message query parameter to false when sending the request to the Self Register User endpoint.
The User Registration Application sends a request to SecureAuth Send Activation Message endpoint.
The access token provided in the request must contain the identity and identity_self_registration scopes.
The activation message contents (link or code) can be changed by setting the code_type_in_message query parameter when sending requests to the Send Activation Message endpoint.
At this point, if the activation message contents are set to code, the User Registration Application should redirect the user to a page where they can enter the activation code they received from SecureAuth via email.
SecureAuth sends a message to the user either with activation link or code.
User selects the link provided in the activation message or provides the activation code to the User Registration Page for verification.
If the activation code contents were set to link, the user account is activated and email is set to verified.
The User Registration Application sends a request to the SecureAuth Activate User With Code endpoint.
The access token provided in the request must contain the identity and identity_self_registration scopes.
SecureAuth activates the user and sets their email to verified.
The user account is activated and email is marked as verified. If the identifier is not already taken, the identifier (matching address) is added to the user.
The User Registration Application sends a request to SecureAuth Generate Code of a Specific Type endpoint.
The access token provided in the request, must contain the identity and identity_self_registration scopes.
The value of the type request body parameter must be set to activation.
The User Registration Application should redirect the user to a page where they can enter the activation code.
SecureAuth generates the activation code.
SecureAuth returns the activation code to the User Registration Application.
User Registration Application sends a message to the user providing them with the generated activation code.
The user provides the activation code to the User Registration Application.
The User Registration Application sends a request to SecureAuth Activate User With Code endpoint to verify the provided code and activate the user.
The access token provided in the request must contain the identity and identity_self_registration scopes.
SecureAuth activates the user.
The user account is activated and email is marked as verified. If the identifier is not already taken, the identifier (matching address) is added to the user.

Integrate Using Create User API

The Create User API provides custom User Registration Applications with more freedom when it comes to setting user extended data. Users can be created with any status (active, inactive, deleted, new), identifiers, addresses, and credentials.

A User provides their registration data to the User Registration Application
The User Registration Application sends a request to SecureAuth OAuth 2.0 Token Endpoint.
The request must contain the identity and identity_self_registration scopes added as the value of the scope request body parameter.
How the User Registration Application authenticates to the SecureAuth authorization server is at the implementer's hand to decide. If the application is divided into frontend and backend parts, the client credentials flow and the mTLS-based client authentication can be used. If the application has no backend, consider using the client authentication method set to none and with the use of PKCE.
SecureAuth mints an access token and provides it to the User Registration Application for consumption.

The User Registration Application sends a request to SecureAuth Create User endpoint.

The access token provided in the request must contain the identity and identity_self_registration scopes.

Request example with userinput JSON file with example user data:

curl -X POST https://{tenantID}.{region}.authz.cloudentity.io/api/identity/{tenantID}/system/pools/{ipID}/users
 -H "Content-Type: application/json"
 -H "Authorization: Bearer $AT"
 -d @userinput

{
      "credentials": [
        {
          "password": "secret",
          "type": "password",
          "webauthn_credentials": "public_key"
        }
      ],
      "id": "12345",
      "identifiers": [
        {
          "identifier": "johndoe@example.com",
          "type": "email"
        }
      ],
      "metadata": {
        "group": "vendors",
        "role": "admin"
      },
      "metadata_schema_id": "vendors",
      "payload": {
        "username": "johnnyD"
      },
      "payload_schema_id": "vendors_payload",
      "status": "active",
      "verifiable_addresses": [
        {
          "address": "johndoe@example.com",
          "preferred_contact_method": "sms",
          "status": "active",
          "type": "email",
          "verified": true
        }
      ]
    }

SecureAuth creates the user and returns an extended view on user entry.
For details on the returned entry, see the Get User API documentation.

Summary

You learned how custom User Registration Applications can allow users to register themselves using SecureAuth Identity Pools APIs. Custom Registration Apps can create users in two ways: using the Self Register User API and activating the user, or using the Create User API to create users with any status, identifiers, credentials, and addresses.

In this section: