Register User

Self-service user registration flow for your application. Users sign up themselves and set their own password.

Purpose and Benefits

What is User Registration?

User registration allows end-users to create their own accounts in cidaas through a self-service flow. Unlike admin-created users, registered users set their own password and complete the registration process themselves.

Key Benefits

Benefit	Description
Self-Service Onboarding	Users can sign up independently without admin intervention
User-Controlled Security	Users set their own password during registration
Webfinger Integration	Automatic user existence checks and provider redirection via webfinger
Invitation Support	Seamless integration with invitation flow for pre-configured access
Flexible Verification	Optional email/mobile verification based on app settings
Auto-Login Support	Optional automatic login after successful registration
Progressive Profiling	Collect minimal data first, gather more information later

When to Use Registration

• Public Signup: Allow anyone to create an account on your platform
• Self-Service Onboarding: Users sign up themselves without admin involvement
• Invitation Completion: Users complete registration after receiving an invitation
• Social Registration: Users sign up via social identity providers
• Progressive Onboarding: Collect minimal data initially, gather more later

Quick Comparison

Aspect	Register User	Create User	Invite User
Password Set By	User (during registration)	Admin (set in request)	User (during registration)
User Action Required	Registration + Optional Verification	Login only	Registration + Login
User Status	Created after registration	Created immediately	Created only after registration
Use Case	Public signup, self-service	Automated provisioning	Team onboarding

Prerequisites

Before implementing registration:

• ✅ App Settings configured with registration enabled
• ✅ Field Settings configured
• ✅ Required scope: cidaas:register or cidaas:invite (for invitation-based registration)
• ✅ Hosted Pages configured (default or custom registration page)
• ✅ Webfinger configuration (optional, for domain/user-based redirection)

Registration Flow

The following sequence diagram illustrates the complete registration process with webfinger user existence check:

Flow Steps Explained

1. Get Request ID (Authorization)

   • Client calls GET /authz-srv/authz with client_id, response_type, and redirect_uri
   • Returns requestId which is required for subsequent API calls
   • API Reference: See Authorization API

2. Webfinger User Existence Check (Recommended)

   • Client calls POST /useractions-srv/userexistence/{requestId} with user identifier (email, mobile, or username)
   • System checks if user exists and determines appropriate action based on webfinger configuration
   • API Reference: See Webfinger User Existence API for request/response examples
   • Returns action: register, login, redirect, select, or blocked

3. Handle Webfinger Response

   • register: User doesn't exist, proceed to get registration fields
   • login: User exists, redirect to login
   • redirect: Redirect to specific identity provider
   • select: Show provider selection (multiple providers available)
   • blocked: Provider not configured, show error

4. Get Public Information (If action is register)

   • Client calls GET /public-srv/public/{requestId} to retrieve:
     • App details
     • Available login providers
     • Password policy
     • Other public configuration
   • API Reference: See Public Page Information API

5. Get Registration Fields (If action is register)

   • Client calls GET /fieldsetup-srv/public/fields?requestId={requestId} to retrieve:
     • List of registration fields (system and custom)
     • Field labels (localized)
     • Required/optional field indicators
     • Field order
     • Field validation rules
   • API Reference: See Get Public Fields API

6. Render Registration Form

   • Use field list to dynamically render registration form
   • Display fields in correct order
   • Show required/optional indicators
   • Apply validation rules
   • Pre-fill with invitation data if invite_id is present

7. User Registers

   • User submits registration via POST /useractions-srv/registration with:
     • requestId (from step 1)
     • User data (email, password, etc.)
     • Optional invite_id (query parameter or header) for invitation-based registration
   • API Reference: See Register User API for request examples

8. Registration Response

   • Response contains action field indicating next step:
     • VERIFICATION: Email/mobile verification required
     • AUTO_LOGIN: Auto-login enabled, complete login flow
     • REGISTER_SUCCESS: Registration successful, show success page
     • LOGIN: Redirect to login page

Important Details

Webfinger User Existence

The webfinger user existence check (POST /useractions-srv/userexistence/{requestId}) determines the appropriate action based on:

• User existence: Whether the user already exists in the system
• Webfinger configuration: Domain-based, user-based, or no redirection
• Provider configuration: Available identity providers for the user's domain

Webfinger Configuration Types

Type	Description	Use Case
No Redirection	Standard check - returns register or login	Simple registration flow
Domain-Based Redirection	Redirects based on email domain	Enterprise SSO (e.g., @company.com → company SSO)
User-Based Redirection	Redirects based on user's registered providers	Multi-provider accounts

Action Values

Action	Description	When Returned
register	User should register	User doesn't exist, no redirection or domain-based redirection
login	User should login	User exists, no redirection or domain-based redirection
redirect	Redirect to identity provider	Single matching provider found
select	Show provider selection	Multiple providers available
blocked	Access blocked	Provider not configured in app

Request Parameters

• Path Parameter: requestId (required) - Obtained from authorization endpoint
• Query Parameters:
  • webfinger (optional): no_redirection, domain_based_redirection, or user_and_domain_based_redirection
  • rememberMe (optional): Remember user preference
• Request Body:
  • email (optional): User email address
  • mobile (optional): User mobile number
  • username (optional): Username
  • At least one identifier required

Required Permissions

• Scope: cidaas:register (for standard registration) or cidaas:invite (for invitation-based registration)
• Webfinger Endpoint: No authentication required (public endpoint)
• Register Endpoint: No authentication required (public endpoint)

Registration Endpoint

Endpoint: POST /useractions-srv/registration

Query Parameters:

• invite_id (optional): For invitation-based registration
  • Can be provided as query parameter: ?invite_id={inviteId}
  • Or as header: invite_id: {inviteId}

Request Body:

• requestId (required): From authorization endpoint
• email, mobile_number, or username (at least one required)
• password (required unless social registration or passwordless registration)
• provider (optional): Social provider name (e.g., google, facebook) - required for social registration
• track_id (optional): Tracking ID from social provider callback - required for social registration and enables automatic account linking (when user rans into progressive profiling as social provider does not return all fields required by fieldsetup or app required fields)
• Additional fields based on Field Settings

Response Actions:

Action	Description	Next Step
VERIFICATION	Email/mobile verification required	Redirect to verification page
AUTO_LOGIN	Auto-login enabled	Call auto-login API
REGISTER_SUCCESS	Registration successful	Show success page
LOGIN	Redirect to login	User logs in

Invitation-Based Registration

When user clicks invitation link:

1. Extract invite_id from URL query parameters
2. Get invitation details: GET /useractions-srv/invitations/{inviteId}
3. Pre-fill registration form with invitation data (name, email, groups)
4. Register with invite_id: POST /useractions-srv/registration?invite_id={inviteId} or in header
5. System automatically assigns groups/roles from invitation

Related: Invite User

Social Registration

Users can register using social identity providers (Google, Facebook, etc.) instead of email/password.

Social Registration Flow

1. User initiates social login via provider (e.g., Google, Facebook)
2. User authenticates with social provider
3. Provider redirects back with authorization code
4. System exchanges code for user information
5. Registration completes with social provider data

Account Linking During Social Registration

Automatic Account Linking: When track_id is present in the registration request and a user account already exists with the same email/mobile but different provider, the accounts are automatically linked.

How it works:

• User has existing account with email (e.g., self provider)
• User attempts to register with social provider (e.g., Google) using same email
• If track_id is present, system detects the conflict
• System automatically links the social identity to the existing account
• User can now login with either email/password or social provider

Important: Account linking only occurs during social registration when track_id is present. Without track_id, a conflict error is returned instead of automatic linking.

Related: Account Linking

Groups and Roles

During registration, users can be assigned to groups and roles:

Group Assignment

• Invitation-Based: Groups are automatically assigned from the invitation when invite_id is provided
• Default Group: All users are automatically added to the CIDAAS_USERS group with USER role (mandatory, cannot be disabled)
• Default Groups per App: Additional groups can be configured in App Settings via operations_allowed_groups. These groups are automatically assigned to all users during registration. Groups must exist and be allowed in app settings to be assigned.

Role Assignment

• Group Roles: Roles are assigned within groups (e.g., USER role in CIDAAS_USERS group)
• Default Roles: Users receive default roles from their assigned groups
• Custom Roles: Custom roles can be assigned based on group configuration

Group Structure

Groups in cidaas follow a hierarchical structure:

• Group ID: Unique identifier (e.g., CIDAAS_USERS, CUSTOMERS)
• Group Type: Defines the group category (e.g., DEFAULT, CUSTOM)
• Path: Hierarchical path (e.g., /CIDAAS_USERS, /CUSTOMERS)
• Roles: List of roles available within the group

Note: Group assignment during registration requires the cidaas:groups_user_map_write scope. For standard registration, users are automatically assigned to the default CIDAAS_USERS group.

Related: User Groups & Roles

Field Configuration

Allowed Fields

Fields shown on registration form (configured in App Settings):

• System Fields: email, mobile_number, username, given_name, family_name, etc.
• Custom Fields: Business-specific fields (configured in Field Settings)

Required Fields

Fields marked with * on registration form:

• At least one identifier required: email, mobile_number, or username
• Additional required fields based on app/tenant configuration

Note: Missing required fields trigger progressive profiling after login.

Registration Settings

Configure in App Settings:

Setting	Effect
Allow Registration	Enable/disable registration
Auto-activation	Auto-verify users (skip verification)
Auto-login	Automatically log in after registration
Verification Required	Require email/mobile verification
Webfinger	Domain/user-based redirection configuration

Technical Integration

Endpoint	Method	Description	Link
Authorization	GET	Get requestId for registration flow	GET /authz-srv/authz
Webfinger User Existence	POST	Check user existence and determine action (by requestId)	POST /useractions-srv/userexistence/:requestId
Public Page Information	GET	Get app details, providers, password policy (by requestId)	GET /public-srv/public/:requestId
Get Registration Fields	GET	Get list of registration fields with labels (by requestId)	GET /fieldsetup-srv/public/fields?requestId=:requestId
Register User	POST	Register a new user	POST /useractions-srv/registration
Get Invitation	GET	Get invitation details (for invitation-based registration)	GET /useractions-srv/invitations/:inviteId

Related Topics

Topic	Description	Link
Create User	Admin creates user with password	Create User
Invite User	Admin invites user to register	Invite User
Account Linking	Merge identities from different providers	Account Linking
Account Structure	User data model	Account Structure
Progressive Profiling	Collect data over time	Progressive Registration
Field Settings	Configure registration fields	Field Settings
App Settings	Registration configuration	App Management
Webfinger	Domain/user-based redirection	Webfinger Documentation

Need Support?

Please contact us directly on our support page.