# Custom Handle Implementation Guide

## What is a handle?

UIN / VID are system-generated unique identifiers provided to Residents. Residents are allowed to authenticate themselves using either UIN / VID.

What if residents are given the flexibility to create their handle (username) and use their unique handle to authenticate?

* Handles can include resident's phone number, e-mail ID, or any linked functional ID / sectoral ID.
* The handle can also be a custom username created through the resident portal.

**Note:** A recyclable ID, such as a mobile number, cannot be used as a handle. Handles must be unique and persistent to ensure reliable identification and authentication. Since mobile numbers and similar IDs can be reassigned or changed over time, they do not meet the criteria for a secure handle. Instead, handles should be chosen from identifiers that remain constant for the user, minimizing the risk of identity conflicts or unauthorized access.

## Overview

Countries that have an established user base can now register users onto a relying portal using their distinctive identifiers referred to as handles. These handles are tailored to meet the specific requirements of each country, enabling users to easily access digital services and receive prompt benefits from both the government and private sector. This approach eliminates the need for users to remember a new or system generated IDs.

## How does it work?

The implementation of custom handles involves below steps:

1. Mark the fields that can be used as user handles. A new attribute is introduced in identity schema, **handle** which accepts boolean value. More than one field in the identity schema can be marked as handle.

   With phone as an example:

   `{"fieldCategory": "phone number", "format": "none", "type": "string", "fieldType": "default", "requiredOn" : "", **"handle" : true**},`
2. When the user registers, collected user data should contain **selectedHandles**, as more than one field can be marked as handle, user can choose amongst the handle fields to use. User can also choose all of them. Client UI’s collecting user data during registration can decide to provide this option to the user or it can also set selected handles to default values as decided by the country. `selectedHandles` is also a field in schema, `identity`.

   `"selectedHandles" : {"fieldCategory": "none","format": "none","type": "array","items" : { "type" : "string" },"fieldType": "default" }`
3. When the collected identity object is sent to the ID repository, it validates the data and accepts the handle provided it is unique amongst the registered handles.

   **Note:** If duplicated, a request to register the user is rejected.
4. Once identity is successfully processed and stored in an ID-repository, identity credentials are issued to IDA to store user credentials for each ID (UIN & VID) as well for each selected handle.
5. ID-repository can be configured to disable issuance of user credential to IDA for both UIN or VID using below properties.

   `mosip.idrepo.identity.disable-uin-based-credential-request=true`

## What is handles collision? How handles collision can be avoided?

If the system is configured to use more than one functional ID as a handle and if two different functional ID systems followed the same format /pattern to generate an ID, handles collision may occur.

Collision between two different functional IDs will result in denying the creation / updating of a handle for a resident.

**Solution:** Every handle stored is postfixed with handle type and the handle type is chosen based on the handle field ID in the identity schema. On every authenticate request, IDA will expect handle postfixed with handle\_type as input.

Property mentioned below is introduced in ID repository to postfix handle type on every creation of identity.

`mosip.identity.fieldid.handle-postfix.mapping={'phone':'@phone'}`

Property mentioned below is introduced in `Id-authentication-default.properties` file to validate the handle value based on the postfix provided in the `inidivdualId` input.

`mosip.ida.handle-types.regex={ '@phone' : '^\\+91[1-9][0-9]{7,9}@phone$' }`

## Conclusion

Implementing custom handles provides a user-friendly approach to user authentication without burdening end users with the need to remember additional or system generated complex IDs.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mosip.io/1.2.0/id-lifecycle-management/identity-issuance/id-repository/custom-handle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.