Dev tutorials

10 mins read

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, Cloudentity 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 Cloudentity Identity Pools APIs

You can integrate your custom user registration page with Cloudentity 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 Cloudentity authorization server before calling Identity Pools APIs.

  • Identity Pools configured on the tenant level (optional)

    Before jumping into calling Cloudentity 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 Cloudentity 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.

[mermaid-begin]
sequenceDiagram autoNumber participant User participant URP as User Registration Application participant AS as Cloudentity Authorization server User->>URP: User Data URP->>AS: /token Note over URP,AS: The identity and identity_self_registration scopes
must be requested
as part of the call to the /token endpoint AS->>URP: Access Token Note over URP,AS: Cloudentity returns a token
with the requested identity scope URP->>AS: POST /system/pools/{ipID}/user/register AS->>User: Send user activation message with code User->>URP: Activation Code URP->>AS: /system/pools/{ipID}/users/{userID}/activate AS->>AS: Activate user opt Note over User,AS: If the send_activation_message query param is not used when calling /selfRegisterUser,
you may either choose going with a Cloudentity-branded User Activation Message
or implement your own custom activation message and send it to the user. alt Cloudentity-Branded User Activation Message Is Sent URP->>AS: /selfSendActivationMessage AS->>User: Send activation message with code User->>URP: Activation code URP->>AS: /system/pools/{ipID}/users/{userID}/activate AS->>AS: Activate user else Custom User Activation Message Is Needed URP->>AS: /system/pools/{ipID}/user/code/generate AS->>AS: Generate activation code AS->>URP: Activation code URP->>User: Send activation message with code User->>URP: Activation code URP->>AS: /system/pools/{ipID}/users/{userID}/activate AS->>AS: Activate user end end

  1. A User provides their registration data to the User Registration Application

  2. The User Registration Application sends a request to Cloudentity 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 Cloudentity 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.

  3. Cloudentity mints an access token and provides it to the User Registration Application for consumption.

  4. The User Registration Application sends a request to the Cloudentity 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 Cloudentity in the third step.

    User attributes may be provided as the values of the payload request body parameter.

    Important

    Whether Cloudentity 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 Cloudentity-branded email being sent (steps 9-13) or request activation code from Cloudentity and provide it to the user in your own email template (steps 14-20).

    At this point, Cloudentity 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.

  5. Cloudentity 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 Cloudentity via email.

  6. 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.

  7. The User Registration Application sends a request to the Cloudentity Activate User With Code endpoint.

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

  8. Cloudentity 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.

  9. The User Registration Application sends a request to Cloudentity 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 Cloudentity via email.

  10. Cloudentity sends a message to the user either with activation link or code.

  11. 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.

  12. The User Registration Application sends a request to the Cloudentity Activate User With Code endpoint.

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

  13. Cloudentity 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.

  14. The User Registration Application sends a request to Cloudentity 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.

  15. Cloudentity generates the activation code.

  16. Cloudentity returns the activation code to the User Registration Application.

  17. User Registration Application sends a message to the user providing them with the generated activation code.

  18. The user provides the activation code to the User Registration Application.

  19. The User Registration Application sends a request to Cloudentity 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.

  20. Cloudentity 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.

[mermaid-begin]
sequenceDiagram autoNumber participant User participant URP as User Registration Application participant AS as Cloudentity Authorization server User->>URP: User Data URP->>AS: /token Note over URP,AS: The identity and identity_self_registration scopes
should be requested
as part of the call to the /token endpoint AS->>URP: Access Token Note over URP,AS: Cloudentity returns a token
with the requested identity and
identity_self_registration scopes URP->>AS: POST /system/pools/{ipID}/users AS->>URP: HTTP 201 User

  1. A User provides their registration data to the User Registration Application

  2. The User Registration Application sends a request to Cloudentity 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 Cloudentity 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.

  3. Cloudentity mints an access token and provides it to the User Registration Application for consumption.

  4. The User Registration Application sends a request to Cloudentity 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

    userinput example

                   
                  
        {
      "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
        }
      ]
    }

  5. Cloudentity 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 Cloudentity 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.

Updated: Sep 14, 2023