User Registration with Aadhaar-based Identity Proofing

IBM Verify enables organizations to onboard Indian users with government-verified identities by integrating with India's Aadhaar identity system.

Use Case

Personas

Admin (Identity or Application Owner)
An IT administrator or developer at a financial institution, insurance company, or government-facing enterprise (for example, TrustMeInsurance) responsible for configuring a secure, compliant user onboarding flow. This persona wants to:

• Eliminate manual KYC (Know Your Customer) processes by automating government identity verification at registration time.
• Ensure that every self-registered user is a verified Indian resident whose provided details (name, mobile, email, date of birth) match their Aadhaar record.
• Reduce fraud and duplicate accounts by tying registration to a unique, government-issued identity.
• Remain compliant with Indian data-protection and regulatory requirements for identity proofing.

End User (Indian Resident)
An Indian resident registering for a service for the first time. This persona wants to:

• Register quickly without uploading physical documents or visiting a branch.
• Authenticate once by using the Aadhaar OTP-based verification they already know, and let the system prefill and cross-check their details automatically.
• Give explicit consent before their Aadhaar data is used, and receive clear confirmation when their account is created.

Understanding the Identity Verification Ecosystem

Aadhaar

Aadhaar is a 12-digit unique identification number issued by the Unique Identification Authority of India (UIDAI) to all Indian residents. It serves as a proof of identity and address, and is linked to biometric and demographic data.

Aadhaar Authentication

Aadhaar-based identity verification in this flow relies on OTP-based authentication. When a user is redirected to MeriPehchaan, they authenticate by entering their Aadhaar-linked mobile number and providing a one-time passcode (OTP) sent by UIDAI.

DigiLocker

DigiLocker is a digital locker service provided by the Government of India that enables Indian citizens to store and share their documents digitally. It provides secure access to authentic documents issued by various government agencies, including Aadhaar.

MeriPehchaan

MeriPehchaan is India's Single Sign-On (SSO) platform that provides a unified authentication gateway for accessing government services. It authenticates users through Aadhaar OTP-based authentication and allows them to consent to share their personal information with service providers.

API Aggregators

To integrate with these government services, various API aggregators provide simplified access to Aadhaar verification and DigiLocker services. For this implementation, Signzy is used as the API aggregator.

📘

Note

Before you begin, contact your chosen aggregator to provision and configure the following on their side:

• Enable Aadhaar OTP authentication and DigiLocker access for your account.
• Obtain your authorization key (API credential) and the base URL for the sandbox or production environment.
• Verify that the redirect or callback URL for your IBM Verify tenant is allowlisted in the aggregator's portal.
• Review the aggregator's flow parameters (timeout values, consent scopes, logo or branding fields) and note any values you may need to adjust in the workflow's CELx function tasks.

Once the aggregator account is ready, proceed with the IBM Verify configuration steps below.

Overview of the flow

The user registration flow with Aadhaar-based identity proofing follows these steps:

1. User data collection: The user fills in a registration form with their email address, mobile number, full name, and date of birth.
2. Initialize Aadhaar authentication session: IBM Verify calls the API aggregator to create a DigiLocker authentication session and receives a redirect URL for MeriPehchaan.
3. Redirect to MeriPehchaan for Aadhaar OTP authentication: The user is redirected to MeriPehchaan, where they authenticate by using their Aadhaar-linked mobile number and an OTP sent by UIDAI. After successful authentication, the user consents to share their DigiLocker data with the service.
4. Validate Aadhaar authentication scope and errors: Upon return from MeriPehchaan, IBM Verify verifies that the authentication completed successfully and that the user granted the required DigiLocker consent scope.
5. Fetch DigiLocker profile: Retrieve the user's DigiLocker profile information (email, phone, DigiLocker ID) from the aggregator using the authenticated session.
6. Fetch Aadhaar data: Retrieve the Aadhaar XML record—including name, date of birth, and photo—from DigiLocker through the aggregator.
7. Cross-validate user-provided data against Aadhaar record:
   • Mobile number: user-provided number matches the Aadhaar-linked number
   • Email address: user-provided email matches the DigiLocker-registered email
   • Full name: user-provided name matches the name in the Aadhaar record
   • Date of birth: user-provided DOB matches the Aadhaar record
8. Data adjustments: Perform necessary data transformations (for example, date format normalization) to align Aadhaar-sourced values with the IBM Verify user directory schema.
9. User consent page: Display the cross-validation results and prompt the user for final consent before account creation.
10. Create user account: If all validations pass and the user consents, create a verified user account in IBM Verify with the validated identity data.
11. Success or error handling: Show a success confirmation page or a descriptive error page depending on the outcome.

Prerequisites

1. IBM Verify configurations:

   • Access to IBM Verify administration console
   • Flow Designer enabled in your tenant: Beta CI-49771: Workflow Modeler (contact IBM Verify support)
   • Session/cache management enabled: Beta VDEV-32965: Session context cache (contact IBM Verify support)

2. API aggregator access:

   • Account with an API aggregator (for example, Signzy)
   • API credentials (authorization key)
   • API endpoint access (production or sandbox)

3. Application (Optional):

   • To start and bind flows together
   • Here, the TrustMeInsurance sample application is used for setups. You can use any other appropriate application.
     

Installation and Configuration

Step 1: Create Custom Branding Theme

This flow uses custom pages for error handling, consent collection, and success confirmation. Create a dedicated theme to prevent affecting other flows.

1. Log in to the IBM Verify administration console.

2. Navigate to User experience > Branding.

3. Create a new theme (for example, "Aadhaar Validation"):

   

   📘

   Note

   Keep a copy of the theme ID for later use in the workflow configuration.

4. Download the master theme template and customize the following pages:

   Workflow Pages (path: workflow/pages/):

   • custom_page1.html: Consent page with validation results
   • custom_page2.html: Success confirmation page
   • custom_page3.html: Error page with detailed error messages

   Error Pages (path: workflow/error/):

   • error_page.html: Generic error page

   📘

   Note

   Get these sample pages from the GitHub repository: verify-saas-resources

   Custom page themes are associated with TrustMeInsurance for the demo purpose only. You might need to customize the pages according to your application.

5. Upload the customized pages to your theme:

   

   • Click the three vertical dots next to each custom page.
   • Click Upload and select your customized HTML file.

Step 2: Creating Custom Attributes

This step creates custom attributes to store DigiLocker-specific information for users.

1. Log in to the IBM Verify administration console.

2. Navigate to Directory > Attributes.

3. Click Add attribute:

   

4. Select Custom attribute. If needed, select the checkboxes for Provisioning and SSO, then click Next:

   

Creating the Date of Birth (DOB) Attribute

5. Provide the attribute details:

   • Attribute name: DOB
   • Attribute ID: dob
   • Description: "Date of birth"

   Click Next:

   

6. Configure the attribute type:

   • Attribute identifier: dob
   • Data type: String
   • Can specify mapping if needed (optional)
   • In "View additional settings", you can also add transformation rules (optional)

   Click Next:

   

7. Add validations if needed, then click Add attribute:

   

Creating Additional DigiLocker Attributes

Repeat the preceding steps to create the following attributes:

DigiLocker Timestamp Attribute:

• Attribute name: DigiLocker Timestamp
• Attribute ID: digilockerTimestamp
• Data type: String
• Validation: Read-only for user

DigiLocker ID Attribute:

• Attribute name: DigiLocker ID
• Attribute ID: digilockerId
• Data type: String
• Validation: Read-only for user, unique across all users in the directory

DigiLocker State Attribute:

• Attribute name: DigiLocker State
• Attribute ID: digilockerStatus
• Data type: String
• Validation: Read-only for user

Step 3: Configuring the User Forms

📘

Note

The current article provides the steps to create a single user form with specific fields to demonstrate the basic registration flow. The flow can be expanded to include more attributes and forms, based on the individual needs of registration.

1. Log in to the IBM Verify administration console.

2. Navigate to User experience > User forms > Create form:

   

3. Enter a form name, for example, user-reg-aadhaar. You can also customize settings such as Primary language, Session management, Theme, and Human Verification.

4. Click Start building form:

   

5. Clear all default elements and click Add form element:

   

Adding Full Name Field

6. Add an element to collect the full name with the following configuration:

   • Form element: Text input field
   • User attribute: display_name
   • Field label: Full Name
   • Helper text: Your full name as per Aadhaar.
   • Placeholder text: Enter your full name
   • Required field: Enabled

   

Adding Email Address Field

7. Add an element to collect the email address with the following configuration:

   • Form element: Email
   • User attribute: email
   • Account username: Enabled
   • Field label: Email Address / Username
   • Helper text: Enter the email address registered with your Aadhaar. It will also serve as your username.
   • Placeholder text: [email protected]
   • Required field: Enabled
   • Required field error: This field is required.
   • Verify email: Enabled (this creates 2 additional steps: "Let's verify your email" and "Email verified")
   • Verification method: Email one-time passcode (OTP)
   • Field validation (regex): ^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+$
     • This regex validates standard email format: alphanumeric characters, plus signs, underscores, periods, and hyphens before the @ symbol, followed by a domain name
   • Validation error message: Enter a valid email address.

   

Adding Mobile Number Field

8. Add an element to collect the mobile number with the following configuration:

   • Form element: Phone
   • User attribute: mobile_number
   • Account username: Disabled
   • Field label: Mobile number
   • Helper text: Number as per Aadhaar. Include country code.
   • Placeholder text: +91XXXXXXXXXX
   • Required field: Enabled
   • Required field error: This field is required.
   • Verify phone: Enabled (this creates 2 additional steps: "Let's verify your phone" and "Phone verified")
   • Verification method: SMS one-time passcode (OTP) (Phone call OTP is also available as an option)
   • Field validation (regex): ^\+91[6-9]\d{9}$
     • This regex validates Indian mobile numbers: starts with +91 (country code), followed by a digit between 6-9 (valid starting digits for Indian mobile numbers), and exactly 9 more digits
   • Validation error message: Enter a valid Indian mobile number.

   

Adding Date of Birth Field

9. Add an element to collect the date of birth with the following configuration:

   • Form element: Text input field
   • User attribute: DOB
   • Account username: Disabled
   • Field label: Date of Birth
   • Helper text: Enter your date of birth as per Aadhaar.
   • Placeholder text: DD/MM/YYYY
   • Required field: Enabled
   • Required field error: This field is required.
   • Field validation: Enabled
   • Field validation (regex): ^(0[1-9]|[12][0-9]|3[01])/(0[1-9]|1[0-2])/((19|20)[0-9]{2})$
     • This regex validates dates in DD/MM/YYYY format: day (01-31), month (01-12), and year (1900-2099)
   • Validation error message: Enter a valid calendar date in DD/MM/YYYY format.

   

10. Click Save draft and then click Publish to make the form available for use.

📘

Note

This step completed the user form needed for Aadhaar-based registration with identity proofing. Other settings can be customized such as branding, displayed text for collecting user attributes, other fields for validation, and more.

Step 4: Import and Setup Workflow

i. Import Workflow

1. Log in to the IBM Verify administration console.

2. Navigate to User experience > Flow designer.

3. Click the Import icon next to the Create flow button:

   

4. Upload the flow file: user_registration_with_aadhaar.json

   📘

   Note

   Get the user_registration_with_aadhaar.json file from the GitHub repository: verify-saas-resources

5. Provide flow metadata:

   • Name: User Registration with Aadhaar
   • Description: User registration and identity proofing with Aadhaar through DigiLocker
   • Reference: (auto-generated or custom)

6. Click Import flow:

   

7. The flow is imported in Draft mode:

   

ii. Configure Flow Components

After importing the flow, you need to configure the following components:

📘

Reference Materials

For detailed information on modifying flow components and CELx functions, refer to:

• Managing Flow Designer
• CELx Attribute Rule Functions

A. User Registration Form Configuration

1. Click the "renderUserForm" (User form task).

2. In the side panel, navigate to the Form field and select the form you created in Step 3 (Configuring the user forms).

   

3. Click Save to save your changes.

B. Initialize Authentication Session Configuration

1. Click the "initiateAuthSession" (Function task).

2. In the side panel, navigate to the Rule expression field.

3. Open the Rule builder and edit the CELx (Common Expression Language extended) code:

   

4. Update the following placeholder fields in the CELx code:

   • <api_creds>: Your API aggregator authorization code
   • <api_base_url>: API aggregator base URL
   • <logo_url>: Your company logo URL
   • <fav_icon_url>: Your favicon URL
   • <support_email>: Your support email address
   • <company_name>: Your company name

📘

Note

You can modify the CELx code to add or remove parameters from the initialization call based on your specific API requirements.

5. Click Save to save your changes.

C. Evaluate Authentication Scope and Errors Configuration

1. Click the "evaluateAuthScopeAndErrors" (Function task).

2. In the side panel, navigate to the Rule expression field.

3. Open the Rule builder and edit the CELx (Common Expression Language extended) code:

   

4. Update the following placeholder fields in the CELx code:

   • <api_creds>: Your API aggregator authorization code
   • <api_base_url>: API aggregator base URL

5. Click Save to save your changes.

D. Fetch Identity Provider Data Configuration

1. Click the "fetchIdentityProviderData" (Function task).

2. In the side panel, navigate to the Rule expression field.

3. Open the Rule builder and edit the CELx (Common Expression Language extended) code:

   

4. Update the following placeholder fields in the CELx code:

   • <api_creds>: Your API aggregator authorization code
   • <api_base_url>: API aggregator base URL

5. Click Save to save your changes.

E. Fetch Aadhaar Data Configuration

1. Click the "fetchAadhaarData" (Function task).

2. In the side panel, navigate to the Rule expression field.

3. Open the Rule builder and edit the CELx (Common Expression Language extended) code:

   

4. Update the following placeholder fields in the CELx code:

   • <api_creds>: Your API aggregator authorization code
   • <api_base_url>: API aggregator base URL

5. Click Save to save your changes.

F. Consent Page Configuration

1. Click the "renderConsentPage" (Page task).

2. Select the Theme which was created before: Aadhaar Validation.

3. Select the Template name which was uploaded: custom_page1.

   

4. Click Save to save your changes.

G. Create User Account Configuration

1. Click the "createUserAccount" (Function task).

2. In the side panel, navigate to the Rule expression field.

3. Open the Rule builder and edit the CELx (Common Expression Language extended) code:

   

4. Update the following placeholder field in the CELx code:

   • app_login_link := "https://<app-login-link>": Replace <app-login-link> with your application's login URL

5. Click Save to save your changes.

H. Success Page Configuration

1. Click the "renderSuccessPage" (Page task).

2. Select the Theme which was created before: Aadhaar Validation.

3. Select the Template name which was uploaded: custom_page2.

   

4. Click Save to save your changes.

I. Error Page Configuration

1. Click the "renderErrorPage" (Page task).

2. Select the Theme which was created before: Aadhaar Validation.

3. Select the Template name which was uploaded: custom_page3.

   

4. Click Save to save your changes.

iii. Publish the Flow

1. After completing all configurations, click Publish to make the flow active and available for use.

   

2. After the flow is published, click the ⚙️ Settings icon and the following is displayed:

   • The execution URL - Copy this URL as it is required for launching the flow
   • The flow layout

   

Step 5: Running the Flow

📘

Note

Typically, the prescribed flow is triggered as part of user registration; however, it is recommended to run the end-to-end flow before it is enabled for generic usage.

You can run the flow explicitly with the flow execution URL.

Testing the Flow

1. Open the Execution URL in a browser.

2. Complete the user registration form with your details.

3. You are redirected to MeriPehchaan for Aadhaar OTP-based authentication.

4. Enter your Aadhaar-linked mobile number. UIDAI sends a one-time passcode (OTP) to that number. Enter the OTP to authenticate, then consent to share your DigiLocker data with the service.

5. You are redirected back to the flow, which:

   • Validates your DigiLocker data
   • Fetches your Aadhaar information
   • Cross-validates all data points
   • Displays a consent page with validation results

6. Review the validation results and provide final consent.

7. If all validations pass, your account gets created and a success page is displayed.

Integration with Your Application

To integrate this flow into your application:

1. Embed the flow: Use the execution URL as an iframe or redirect users to it.
2. Handle callbacks: Configure your application to handle the redirect after successful registration.
3. Execution URL Configuration: The execution URL is needed for launching the flow from your application.

Summary

This flow demonstrates how IBM Verify seamlessly integrates with India's Aadhaar ecosystem to enable secure, government-verified user registration. By leveraging Aadhaar-based identity proofing through DigiLocker and MeriPehchaan, organizations can implement robust identity verification while maintaining user privacy and regulatory compliance.

The flow showcases IBM Verify's flexibility in integrating with external identity verification systems, custom user forms, data validation workflows, and secure user account creation with verified identity information. This approach is particularly valuable for CIAM implementations in India where Aadhaar-based verification is essential for regulatory compliance and fraud prevention.

💎

Vishesh S Amin, IBM Security