Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This guide contains all the information required for successful deployment and running of Resident Portal. It includes information about the Database and template scripts, seed data, roles, OIDC client setup, etc.
Resident Service DB Scripts to be run: DB scripts
The master-data templates required for the Resident portal are added to the template and template type DML excel files in mosip/mosip-data repository. These scripts need to be applied to the corresponding table.
mosip-resident-client needs to have below roles in keycloak:
RESIDENT
SUBSCRIBE_AUTH_TYPE_STATUS_UPDATE_ACK_GENERAL
SUBSCRIBE_AUTHENTICATION_TRANSACTION_STATUS_GENERAL
SUBSCRIBE_CREDENTIAL_STATUS_UPDATE_GENERAL
SUBSCRIBE_REGISTRATION_PROCESSOR_WORKFLOW_COMPLETED_EVENT_GENERAL
CREDENTIAL_REQUEST
Here is the document which explains how resident-oidc partner is onboarded through partner-onboarder after deployment.
For more details on how to configure the Resident OIDC client, refer here.
This repository contains the UI code for the Resident portal. To know more about the features and functions present on the portal, refer here.
The code is written in Angular JS.
Install node.js- To build the angular code using angular cli that runs on node, recommended Node: 14.17.3, Package Manager: npm 6.14.13
Install angular cli – To install angular cli for building the code into deployable artifacts. Follow the following steps to install angular cli on your system.
npm install -g @angular/cli (to install angular cli)
ng --version (to verify angular is installed in the system) We recommend Angular CLI: 7.2.1
Check out the source code from GIT – To download the source code from git, follow the steps below to download the source code on your local system.
git clone https://github.com/mosip/resident-ui.git (to clone the source code repository from git)
Build the code
Follow the steps below to build the source code on your system.
Navigate to the resident-ui directory inside the cloned repository.
Run the command ng build "--prod" "--base-href" "." "--output-path=dist" in that directory to build the code.
Build Docker image
Follow the steps below to build the docker image on your system.
docker build -t name . (replace name with the name of the image you want, "." signifies the current directory from where the docker file has to be read.)
Example: docker build -t residentui .
Run the Docker image
Follow the steps to build a docker image on your system.
docker run –d –p 80:80 --name container-name image-name (to run the docker image created with the previous step,-d signifies to run the container in detached mode, -p signifies the port mapping left side of the":" is the external port that will be exposed to the outside world and the right side is the internal port of the container that is mapped with the external port. Replace container-name with the name of your choice for the container, replace image-name with the name of the image specified in the previous step)
Example: docker run -d -p 8080:8080 --name nginx residentui
Now you can access the user interface over the internet via a browser.
Example: http://localhost:8080/#/dashboard
Build & deploy the code locally
Follow the steps below to build the source code on your system.
Navigate to the resident-ui directory inside the cloned repository. Then, run the following command in that directory:
npm install
ng serve
Now, you can access the user interface via the browser.
Example: http://localhost:4200
Resident Services are the self-services used by residents themselves via a portal. The Resident Portal is a web-based UI application that provides residents of a country with services related to their Unique Identification Number (UIN).
The documentation here will guide you through the prerequisites required for the developer's setup.
Below is a list of tools required in Resident Services:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)
Follow the steps below to set up Resident Services on your local system:
Download lombok.jar and settings.xml from here.
Install Apache Maven.
Copy the settings.xml to ".m2" folder C:\Users\<username>\.m2.
Install Eclipse.
Open the lombok.jar file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update. Specify the eclipse installation location if required by clicking the ‘Specify location…’ button. Then, click Install/Update the button to proceed.
Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse to see if lombok.jar is added. By doing this, you will not have to add the dependency of lombok in your pom.xml file separately as it is auto-configured by Eclipse.
Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.
For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.
Open the project folder where pom.xml is present.
Open the command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true to build the project and wait for the build to complete successfully.
After building a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.
After successful importing of the project, update the project by right-clicking on Project → Maven → Update Project.
For the environment setup, you need an external JAR that is available here with different versions. Download the below-mentioned JARs with appropriate latest/appropriate versions. You will need to input the appropriate artifact ID and version and other inputs.
a. icu4j.jar
b. kernel-auth-adapter.jar
c. kernel-ref-idobjectvalidator.jar
d. kernel-transliteration-icu4j.jar
E.g.: You can download kernel-auth-adapter.jar and add to the project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close).
Clone mosip-config repository.
a. As Resident Services is using two properties files- resident-default.properties and application-default.properties. But for the local running of the application, you need to provide additional/overriding properties such as secrets, passwords, and properties passed by the environment which can be added to new files application-dev-default.properties (common properties for all modules) and resident-dev-default.properties (Resident service-specific properties).
b. You will have to create both the property files according to your environment and put them in mosip-config folder (cloned). The same files are available below for reference.
These two files are loaded by the application by specifying the application names in the Application VM arguments like- Dspring.cloud.config.name=application,resident,application-dev, resident-dev (also detailed in a later section).
To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.
Put both files in the same folder and point to the property- Dspring.cloud.config.server.native.search-locations to mosip-config folder in config-server-start.bat file and also check the version of kernel-config-server.jar towards the end of the command.
Example:
As mentioned earlier, you will have to create property files according to your environment like resident-env-default and application-env-default (here env represents environment name). Both files will contain different configurations such as resident-env-default will have config properties (e.g., secrets, passcodes, etc) used for the resident-services module only and application-env-default is used for environment-specific changes and can be used for other modules as well.
In this example, currently, these two files are created for the dev environment and hence the files have suffixes of -dev. If you want to run it for a different environment such as qa, create these two files with -qa suffixes, and then you will also need to provide the appropriate VM argument for that referring to qa environment.
For instance,
Add mosip.resident.client.secret=*********** property to be able to use a decrypted passcode and run it on your local machine.
If you check the URLs present in application-default the file, they are set to module-specific URLs, but you need to use internal/external environment URLs to access the APIs by using an application-dev-default file.
In application-dev-default file, assign environment domain URL to mosipbox.public.url , and change all other URLs with ${mosipbox.public.url}.
It results in mosipbox.public.url=internal/externalAPI (e.g., mosipbox.public.url=https://api-internal.dev.mosip.net) and it will connect with the Development environment.
Run the server by opening the config-server-start.bat file.
Open Eclipse and run the project for one time as a Java application, so that it will create a Java application which you can see in debug configurations, and then change its name. (e.g.: project name with the environment - "Resident-dev").
Open the Arguments tab and specify Application VM arguments: For example, for a development environment:
Save this run configuration as ‘Resident-dev’ .
For qa environment, you can create Resident-qa run configuration with VM argument as below.
Example:
Click Apply and then debug it (starts running). In the console, you can see a message like Started ResidentBootApplication in 34.078 seconds (JVM running for 38.361).
For API documentation, refer here.
The APIs can be tested with the help of Postman or Swagger-UI.
Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster. It is a widely used tool for API testing. Below you will find the APIs postman collection of resident-services.
Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of resident-services for the dev-environment from https://api-internal.dev.mosip.net/resident/v1/swagger-ui.html and localhost from http://localhost:8099/resident/v1/swagger-ui.html.
Download the JSON collection available below and import it to your postman. Resident-Service-APIs.postman_collection-latest.json.
Create an environment as shown in the image below.
This environment is created for dev. Give the variable name as url and set both values as https://api-internal.dev.mosip.net.
Similarly, create another environment as shown below.
This environment is created for localhost. Give the variable name as url and set both values as http://localhost:8099.
Resident services are self-service tools utilized by residents through an online portal. The Resident Portal is a web-based user interface application that offers services related to the residents' Unique Identification Number (UIN). Through this portal, residents can perform various operations related to their UIN or VID and can also raise any concerns they may have.
The key features provided on the Resident portal are:
Avail UIN services using UIN/ VID (through e-Signet):
View My History: This feature enables the Resident to view the history of transactions associated with their UIN.
Manage My VID: Residents can create, delete, and download VID cards based on requirements.
Secure My ID: Residents can lock or unlock their authentication modalities such as fingerprint authentication, iris authentication, email OTP authentication, SMS OTP authentication, thumbprint authentication, and face authentication.
Track My Requests: This feature enables the Residents to enter an Event ID associated with the logged-in user’s UIN to track the status of the event.
Get Personalized Card: The residents can download a personalized card which essentially means that they can choose the attributes that they would want to be added to their cards.
Share My Data: This feature enables Residents to choose the data that they want to share with a MOSIP-registered partner.
Update My Data: This feature enables the Resident to update their identity data, address, email ID, phone number, and notification language preference.
Logout: Once the Resident is done with the activities that he wanted to perform, he can end the active session by logging out from the portal.
Get Information
About Registration Centers: Residents can get a list of Registration Centers near them or Registration Centers based on the location hierarchy.
List of supporting documents: Residents can get the list of all the supporting documents as Proof of Identity, Proof of Address, Proof of Relationship, etc.
Get My UIN (using UIN/ VID/ AID): Using this feature, the Resident can download their password-protected UIN card if the UIN card is ready or they can view the status of their Application ID (AID) if the UIN card is still under progress.
Verify email ID and/ or phone number: Using this feature, the Resident can verify if the email ID/ Phone number given during registration is correct or not. This will be done by verifying the OTP sent over the registered email ID/ Phone number.
Book an appointment for new enrollment (via the pre-registration portal): Using this feature, the Resident can book an appointment to visit the Registration center.
Ancillary features
Multi-lingual support: Residents can view and use the Resident Portal in multiple languages including RTL languages.
Get Notifications (email and bell notifications): Residents will be getting bell-icon notifications for the asynchronous events if they have an active session i.e. they have logged into the Resident Portal.
View profile details of the logged-in user (name, photo, and last login details): The Resident will be able to view the name, and photo of the logged-in user. They will also be able to see the last login details of the Resident.
Responsive UI support: Support for the application to work seamlessly on various resolutions.
Below is an image summarizing the features provided in the Resident portal.
The relationship of Resident services with other services is listed below.
Note: The numbers do not signify the sequence of operations or the control flow.
Audit Manager: Resident services sends all the audit logs to the Audit Manager.
Digital card service: Resident services use this service to download the PDF of the UIN card or VID card.
Credential Request Generator Service: This service is used to share the credentials with various partners like print partners, authentication partners, and digital card partners.
ID Repository Identity Service: Resident services use this service to retrieve the identity information of a credential and to lock/unlock authentication types.
ID Repository VID service: This service is used to generate/revoke various types of VIDs.
ID Authentication: This service is used by Resident services to authenticate users.
MOSIP e-Signet: This is used to authenticate and authorize the users in the event of login using UIN/ VID.
Resident UI: This is the interface through which users can interact with the Resident Services.
WebSub: This is used to get asynchronous notifications from IDA for acknowledgment purposes.
Registration Processor: This is used to sync and upload packets for features about changes in identity data.
Packet Manager: Resident services use this service to create packets.
Partner Management Service: Resident services use this service to get information about various partners and policies.
Keycloak: Resident services use this to authenticate to access the MOSIP internal APIs. The Resident Services communicates with endpoints of other MOSIP modules via a token obtained from Keycloak.
Master data service: Resident services invoke the Master Data services to get various templates and machine details.
Notification service: Resident services use this service to send various notifications through email or SMS.
Key Manager: Resident services use Key Manager to encrypt or decrypt the data used across features.
The design of the Resident portal embodies the following principles:
One-stop solution: The Resident portal is designed to have components that aim to solve all the queries, issues, or discrepancies of the residents and act as a one-stop solution for all the requirements.
Self-Sovereign: Once the ID is issued by an authority, the user/resident/citizen chooses to control and manage their data in their choice of devices.
Inclusive: The Resident portal aims to be available in all browsers while also catering to the needs of visually impaired, dyslexic, and color-blind folks.
Presence assurance: This web-based UI application would put in all its efforts to ensure easy access to all the residents with high availability.
Works Remote: The Resident portal should be able to share credentials when data needs to be shared remotely without physical presence.
Trusted: The identity verification process on the device should be trusted so that it can be used in service delivery without any concerns.
Grievance redressal: The Resident portal ensures that in case of any concerns or grievances, the issue is raised and resolved through the portal itself.
Resident Portal is currently compatible and certified with the following list of browsers:
1.
Chrome
124.0.6367.208
2.
Firefox
125.0.1
3.
Edge
124.0.2478.51
Below are the steps to create the Resident OIDC client as standard steps in DevOps after e-Signet and Resident deployment.
Have a user created in keycloak with the below roles as needed for the Authorization token in the API requests:
i. ZONAL_ADMIN,
ii. PARTNER_ADMIN,
iii. POLICY_MANAGER,
iv. MISP_PARTNER,
v. PMS_ADMIN
Authenticating user to take the token and use it in all APIs invoked in further steps:
Swagger URL - https://api-internal.dev2.mosip.net/v1/authmanager/swagger-ui/index.html?configUrl=/v1/authmanager/v3/api-docs/swagger-config#/authmanager/getAllAuthTokens
Request Body:
Step 1: Creating a policy group for resident OIDC Client
Note: Since policymanager service swagger does not work, you can use postman for APIs in it.
POST - https://api-internal.dev2.mosip.net/v1/policymanager/policies/group/new
Request Body:
Make note of the prolicyGroupId from the response.
Step 2: Creating a policy for Resident OIDC client
POST - https://api-internal.dev2.mosip.net/v1/policymanager/policies
Request Body:
Step 3: Publishing policy
POST - https://api-internal.dev2.mosip.net/v1/policymanager/policies/{{policyId}}/group/{{policyGroupId}}/publish Path params: * policyId - resident-oidc-client-policy * policyGroupId - from previous response
Step 4: Resident OIDC Client Partner self registration
Swagger URL: https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/partner-service-controller/partnerSelfRegistration
Request Body:
Step 5: Upload ROOT Certificate as CA certificate
i. Get certificate from keymanager with below parameters:
Swagger URL: https://api-internal.dev2.mosip.net/v1/keymanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config#/keymanager/getCertificate
AppID: "ROOT", refID: ""
ii. Uploaded it as CA certificate:
Swagger URL - https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/partner-service-controller/uploadCACertificate
Request Body (Example only):
Step 6: Upload RESIDENT certificate as CA certificate
i. Get certificate from keymanager with below parameters:
Swagger URL: https://api-internal.dev2.mosip.net/v1/keymanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config#/keymanager/getCertificate
AppID: "RESIDENT", refID: ""
ii. Uploaded it as CA certificate:
Swagger URL - https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/partner-service-controller/uploadCACertificate
Request Body (Example only):
Step 7: Upload RESIDENT : IDP_USER_INFO certificate as Partner certificate
i. Get certificate from keymanager with below parameters:
Swagger URL: https://api-internal.dev2.mosip.net/v1/keymanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config#/keymanager/getCertificate
AppID: "RESIDENT", refID: "IDP_USER_INFO"
ii. Uploaded it as Partner certificate:
Swagger URL - https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/partner-service-controller/uploadPartnerCertificate
Request Body (Example only):
Step 8: Create policy Mapping request:
Swagger URL: https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/partner-service-controller/mapPolicyToPartner
Path param:
partnerId : resident-oidc-client-partner
Request Body:
Output:
Make not of the mappingKey.
Step 9: Approve policy mapping:
Swagger URL - https://api-internal.dev2.mosip.net/v1/partnermanager/partners/policy/{{mapping key}}
Note: This mapping key will be returned as an output from policy mapping request.
Request Body:
Step 1: Prepare the RESIDENT JWKS public key JSON.
i. Get certificate from keymanager with below parameters
Swagger URL: https://api-internal.dev2.mosip.net/v1/keymanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config#/keymanager/getCertificate
AppID: "RESIDENT", refID: ""
ii. Store the certificate as resident-oidc.cerfile. Make sure to replace chars with line breaks and save it*
iii. Get the KeyID of the above certificate using Get All Certificates API
Swagger URL: https://api-internal.dev2.mosip.net/v1/keymanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config#/keymanager/getAllCertificates
AppID: "RESIDENT", refID: ""
From the response get the keyId. This will be the kid attribute in the OIDC client creation step.
iv. Get JWKS public key JSON from certificate
Use the certpem2jwksjson.jar with below command to get the JWKS of that. (Attached the Java code of that for creating automted step of this)
In the console, the JSON text of the public key of the certificate will be printed. Copy it.
v. Correct the kid in JWKS public key JSON
In the JSON public key, replace the kid value with the keyId in the earlier step.
Step 2: Create the OIDC client in PMS
Swagger URL: https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/client-management-controller/createClient
In the request body, make sure to replace thebelow attributes:
publicKey - the JWKS public key JSON from earlier step
logoUri - Correct hostname for the Resident UI
redirectUris - Correct the hostname for Resident Service
Request Body (Example only):
The response will contain the Resident OIDC client ID in clientId attribute.
Step 3: Configure the Resident OIDC client in resident-default.properties.
Configure the above obtained Resident OIDC client ID resident-default.properties with property name mosip.iam.module.clientID.
Note: This will need a restart of the resident service if it is already deployed.
The following guide outlines some important properties that can be customized for a given installation. Please note that this list is not exhaustive but serves as a checklist for reviewing properties that are likely to differ from the default settings. For a complete list of properties, refer to the files listed below.
Resident Service uses the following configuration files:
Properties used for configuring the database.
URL pattern for logging filter. For example, "/callback/*" .Defaults to "/*".
This will print the request details such as URL, headers, and body for debugging purposes. The default is false.
This will print the repository method calls for debugging purposes. The default is false.
These are the authentication types allowed for a resident and default unlock duration.
Templates type codes for authentication types
Templates type codes for authentication types status
Below are the properties used for validation purpose.
Properties used for machine specification and center
Property used to define the endpoints that should not be part of authentication.
This property is used to define the keys of the properties to be exposed to UI.
When enabling MOSIP eSignet comment Mock Keycloak config, vise versa.
This property will directly apply the certs URL without the need for constructing the path from the issuer URL. This is useful to keep a different certs URL for integrating with MOSIP IDP for offline token validation.
Used in open-id-connect based login with UIN/VID in MOSIP-IDP
Used for login purposes
Properties used to define application and reference id.
To configure the 'Object Store Configuration', update the 'Object Store URL' and other properties as below:
object.store.s3.url=
Property used whether to enable virus scanner flag
Property used to get the vid policy json
Property used to get the UI schema json
Property used to get the identity mapping json
This property is used to get the data format from MVEL file
Below websub properties used for authentication type status event
Below websub properties used for authentication transaction status event
Below websub properties used for credential status event
Below websub properties used for regproc complete workflow event
Properties used to get the data format from MVEL file.
Configure Time limit for OTP Flooding scenario (in minutes).
Define property name in below format- resident.<attribute name>.template.property.attribute.list
Define property name in below format- resident.event.type.<eventType>.template.property
Define property name in below format- resident.service-type.<serviceType>.template.property
Define property name in below format- resident.id-auth.request-type.<authTypeCode>.<statusCode>.descr
Define property name in below format- resident.auth-type-code.<authTypeCode>.code
Below property will retrieve VID when requested. Default is false so, UIN will be retrieved. Endpoints using below property- /individualId/otp, /aid/status.
Commenting or removing this property will disable reference validator.
For validating request time as per before & after time limit (in seconds) in contact-details/update API.
The java.time.format.FormatStyle enum to use for date time formatting based on locale. Allowed values with examples are:
FULL ('Tuesday, April 12, 1952 AD' or '3:30:42pm PST')
LONG('January 12, 1952')
MEDIUM ('Jan 12, 1952')
SHORT ('12.13.52' or '3:30pm')
Current value is MEDUIM. For more details refer to the enum.
Usage: resident.attribute.separator.<attribute>=<separator string>
Async thread for audit calls. Limit the number of async threads created in Resident services. This count is divided into 4 thread groups configured in 'io.mosip.resident.config.Config' class.
This property is used in all downloaded PDF files.
These properties are used in reg-center feature for map zoom in & out.
Transliteration work around property since eng to fra directly is not supported in icu4j.This can be added for any other unsupported language also.
For example, resident-transliteration-workaround-for-<fromLanguageCode>-<toLanguageCode> = fromLanguageCode-intermediateLanguageCode-toLanguageCode.
For this, intermediate language code transliteration should work in both ways.
This is a policy url to fetch delimeter to download card after updating uin.
Below config is used to get identity mapping and get remaining update count for the Identity Attributes .
This is used in Resident in Update UIN feature to show remaining update count for the Identity Attribute.
This file contains Mvel method definitions for masking attributes, getting passwords, and formatting attributes.
This is used in Resident for downloading PDF cards and for masking attributes in the share credential feature and personalize card feature.
https://github.com/mosip/mosip-config/blob/pla-1.2.0.1/credentialdata.mvel
The table below outlines the frameworks, tools, and technologies employed by Resident Portal.
7.2.1
AngularJS is a toolset for building the framework most suited to your application development. It is fully extensible and works well with other libraries.
16.2.0
Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine.
The table below outlines the frameworks, tools, and technologies employed by Resident Services.
Java SE 11
OpenJDK 11
Language Runtime in Docker Image
GNU General Public License, version 2, with the Classpath Exception
Ubuntu Server
20.04
Docker base image Operating System
Free
Spring
5
Application Framework
Apache License 2.0
Apache commons
Version compatible with Spring 5
Utilities
Apache License 2.0
Hibernate
5.2.17.Final
ORM
Apache Software License 2.0
Hibernate validator
6.0.12.Final
validator
Apache Software License 2.0
mvel2
2.4.7.Final
Expression language
Apache License 2.0
Jackson
2.9.x
JSON marshal/unmarshal
Apache Software License 2.0
Junit
4.x and above
Unit Testing
Common Public License - v 1.0
mockito
2.22.0
Junit - Mock Objects
MIT
power-mock
2.0.7
Junit - Mock Static Classes
Apache Software License 2.0
logback
1.2.3
Log
GNU Lesser GPL Version 2.1
velocity
1.7
Templating
Apache Software License 2.0
Swagger
Open API - 3
API Documentation
Apache Software License 2.0
Tomcat server
8
Application Server
Apache Software License 2.0
PostgreSQL
Server: 10
Database
Postgres License BSD 2-clause "Simplified License"
Sonar
7.2
Code quality Checking
Open Source License
Micrometer Prometheus
1.4.2
Metrics
Apache Software License 2.0
gson
2.8.4
JSON parser
Apache Software License 2.0
h2 database
1.4.197
JUnit Test DB
EPL 1.0, MPL 2.0
lombok
1.18.8
Development - reduce the boilerplate code
MIT
IText PDF
5.5.13.3
PDF Generation
AGPL 3.0
icu4j
63.1
Transliteration
Unicode-3.0
The Resident Portal is a user-friendly web-based platform designed to assist residents in accessing various services associated with their Unique Identification Number (UIN). This portal offers a range of essential services such as:
UIN services using UIN/VID (through e-Signet):
View My History
Manage My VID
Secure My ID
Track My Requests
Get Personalised Card
Share My Data
Logout
Get Information
About Registration Centers
List of supporting documents
Get My UIN (using UIN/ VID/ AID)
Verify email ID and/ or phone number
Responsive UI support- Support for the application to work seamlessly on various resolutions.
Book an appointment for new enrolment (via the pre-registration portal)
Ancillary features
Font size
Get Notifications (email and bell notifications)
View profile details of the logged in user (name, photo, and last login details)
Below is the detailed explanation of each of the features mentioned above.
Residents can use these services to view, update, change, manage or share their data. They can also report an issue in case of a grievance.
Pre-requisites: To login into the Resident Portal, the resident should have their unique virtual ID (VID) or Unique Identification Number (UIN) and also have access to the registered email ID/ phone number to be able to receive the OTP.
Resident accesses the Resident Portal dashboard page.
Resident clicks on UIN Services.
The login screen appears and the resident can choose one of the options to log in.
To login with OTP authentication, the resident clicks on Log in here> More ways to login > Login with OTP.
Resident needs to enter valid VID in the Enter Your VID text field and check the box I'm not a robot.
Next, the resident clicks on the Get OTP button.
The resident receives the OTP on the registered phone number and email ID.
The resident needs to enter the valid OTP received within stipulated time and click the Verify button.
The resident is then navigated to the Consent page. On this page, the Essential and Voluntary claims are displayed. Additionally, they will also have to allow access to their data in Authorize Scope section to avail various services. Based on the consent provided by the resident, the services will be made available for modification.
The resident has the choice to select from the list of Voluntary claims while the Essential claims are mandatory.
The resident should now click the Continue button. The system navigates the resident to the UIN Services menu page from where they can avail various services.
Note: Consent page will be available only for first time login.
The residents can view the history of all the transactions associated with their logged-in UIN/ VID. They can also view their details and if any unaccounted entry is found, a report can be raised against the same.
The residents can perform the following:
Search: The residents can enter an Event ID to search a particular event.
Filter based on date (From date and To date): The Residents can put a “from” and “to” date in order to get the list of all the events performed in the chosen date range.
Filter based on status (Success/ In Progress/ Failure): The Residents can filter based on the status of the event. E.g.: If they want to view all “In Progress” events, they can choose the status as “In Progress”. Additionally, they can also select any combination of the above three options.
Filter based on History Type (Authentication, ID Management, Data Update, Data Share, Service Requests): The Residents can filter based on the type of event. Additionally, they can also choose any combination of the above five options.
Authentication Request: This includes all the authentication and e-KYC requests.
ID Management Request: This includes the below services:
Manage My VID (Generate/Revoke VID)
Verify phone number/email ID
Secure My ID (Lock/unlock various authentication types)
Data Update Request: This includes the below services:
Update my UIN (demographic data and contact data)
Data Share Request: This includes the below services:
Share with a partner
Service Request: This includes the below services:
Download configured card
Physical card
Get my UIN
Book an appointment (lost UIN, Update UIN, Pre-registration, other)
Go button: Residents can click on the Go button once they are done selecting all the required filters.
Download the PDF of the results: The residents can download the PDF version of the search result populated.
Clicking on the accordion/ the caret of a particular event, the following options will appear:
a. View Details: The residents can view the details about an event by clicking on View Details. They will be redirected to Track My Request page with pre-filled EID where they can see further details about the event.
b. Pin Event to the top: The residents can pin the events to the top of the list based on their preference. Currently, this is configured for up to 3 events but it can be customized as per country’s requirements. Also, the resident can unpin the pinned events by clicking Unpin from Top.
c. Report a grievance: The residents can report a grievance in case of fraud or for any event not initiated by them. On clicking Report an Issue, the resident will be redirected to the Grievance Redressal Form page where they will see a set of pre-filled data as well as a set of data to be filled.
Pre-filled data:
Name
Event ID (EID)
Registered Email ID
Registered Mobile Number
Data to be filled:
Alternate Email ID
Alternate Mobile Number
Comments
Once the event is completed, a message is displayed containing the grievance tracking ID.
Below are the images with different filters on this page.
On clicking Manage My VID, the resident will be taken to a page where they can view details of the existing VIDs, generate new VID, revoke existing VID or download a VID card.
The following types of VIDs can be seen based on the VID policy:
Perpetual VID
Temporary VID
One-time VID
Note: The resident can get to know about the features of a particular VID by hovering over the “i” symbol.
The residents can perform the following:
Create a new VID : The residents can click on the Create button against any of the VID type selected. They can click on Yes to proceed. Once the event is completed, a message is displayed containing the Event ID along with a link to track the service.
Revoke an existing VID: The residents can click on the Delete icon to revoke an existing VID. They can click on Yes to proceed. Once the event is completed, a message is displayed containing the Event ID along with a link to track the service.
Download a VID card:
a. The residents can click on the Download icon to initiate the download process. They can click on Download to proceed. Once the event is completed, a message is displayed containing the Event ID, a link to track the service and the password combination.
b. Once the card is ready to download, they will receive a notification for the same under the bell icon displayed on the top right corner of the screen and as an Email notification.
c. On clicking on the notification, the resident will be taken to Track My Request page with pre-filled EID.
d. On this screen, the resident will be able to download the card by clicking on Download My VID card button on the bottom left corner of the screen.
e. The downloaded card will be a password protected PDF. The residents can view the downloaded VID card by entering the password combination displayed on the screen.
View VID number: All the VID numbers will be masked by default. The residents can view the unmasked version of VID by clicking on eye icon next to the VID number.
On clicking Secure My ID, the residents can view the status of all the authentication types. They can choose to lock or unlock authentication types like the following:
Email authentication
Mobile authentication
Demographic authentication
Fingerprint authentication
Iris authentication
Face authentication
The residents can perform the following,
View the current status of authentication types: The lock icon on each card indicates the current status of the authentication type. E.g.: If the lock is open, the authentication type is unlocked which means the residents can authenticate themselves using that particular authentication type and vice versa.
Lock/ unlock the authentication types: To lock/ unlock a particular authentication type, the residents can click on lock/ unlock button. Once the preferences of each authentication type is selected, the residents can click on Submit to save the changes and click Yes to proceed. Once the event is completed, a message is displayed containing the Event ID along with a link to track the service.
On clicking Track My Requests, the residents can track the status of an EID associated with the logged-in UIN/ VID. They can also view and download the detailed information about the entered EID like:
Event ID- This is the unique ID provided against each event
Event Type- This is the feature that is being availed. E.g.: Lock/unlock authentication types
Event Status- This is the status of the event which can hold values like Success, Failure or In-Progress
Individual ID- This is the type of individual ID that was used to login. E.g.: VID or UIN
Summary- This the the detailed description of the event.
Timestamp- This the time when the event occurred.
Authentication Mode- This is the authentication mode used to login. E.g.: OTP or Biometric or QR code
Partner Logo- This is the logo of the registered partner.
Partner Name- This is the name of the registered partner.
Attribute List- This is the list of attributes shared with the registered partner.
Purpose- This is the purpose of sharing data with the registered partner as input by the resident.
The resident can reach Track My Requests page by the following ways:
UIN services > View history > Click on the event tile > View details
By clicking the bell icon
UIN services > Track My Requests
Note:
Residents can download their updated UIN /VID card.
Report a grievance: The residents can report a grievance in case of fraud or for any event not initiated by them. On clicking Report an Issue, the resident will be redirected to the Grievance Redressal Form page where they will see a set of pre-filled data as well as a set of data to be filled.
On clicking Get Personalised Card, the residents can select the data to be added to their credential. They can preview the chosen data and download it. To be able to download the card, residents should select at least 3 attributes from the list mentioned below:
Name- Name of the resident. They can choose the format in which they want the name to be displayed.
Date of Birth- Date of birth of the resident. They can choose the format in which they want the date of birth to be displayed.
UIN- Unique Identification Number. They can choose to mask or unmask the UIN.
Perpetual VID- Perpetual Virtual ID. They can choose to mask or unmask the VID.
Phone number- Registered phone number of the resident. They can choose to mask or unmask the phone number.
Email ID- Registered email ID of the resident. They can choose to mask or unmask the email ID.
Address- Address of the resident. They can choose the format in which they want the address to be displayed.
Gender
Photo
These details can be previewed as and when the attributes are chosen.
Once the event is completed, a message is displayed containing the Event ID along with a link to track the service.
On clicking Share My Data, the residents can choose the data to be shared with any of the registered partners to avail various third party services.
To share the data, residents should select at least 3 attributes from the list mentioned below:
Name- Name of the resident. They can choose the format in which they want the name to be displayed.
Date of Birth- Date of birth of the resident. They can choose the format in which they want the date of birth to be displayed.
UIN- Unique Identification Number. They can choose to mask or unmask the UIN.
Perpetual VID- Perpetual Virtual ID. They can choose to mask or unmask the VID.
Phone number- Registered phone number of the resident. They can choose to mask or unmask the phone number.
Email ID- Registered email ID of the resident. They can choose to mask or unmask the email ID.
Address- Address of the resident. They can choose the format in which they want the address to be displayed.
Gender
Photo
These details can be previewed as and when the attributes are chosen.
Additionally, the residents have to:
Select the partner with whom they want to share their data from a dropdown list of registered partners.
Enter the purpose of sharing the data with the registered partner.
On clicking the Share button, the resident will have to provide consent to share their data with the external partner.
Once the event is completed, a message is displayed containing the Event ID along with a link to track the service.
The Resident Portal menu bar contains the following:
Font Size- Residents can alter the size of the font based on their preferences.
Language- Residents can select the language of preference.
Bell icon Notification- Residents can view the notifications of all the asynchronous events in chronological order.
Profile Icon- Residents can view the following:
Name of the logged in user
Photo of the logged in user
Last login details
Logout option
The residents can book an appointment for registration using the pre-registration portal. To do so, they can click on Book an appointment tile which will redirect them to the pre-registration portal. To know more about pre-registration portal, refer to this link Pre-registration.
The residents can use this feature to verify their registered email ID or phone number.
Steps to verify email ID/ phone number:
Resident clicks either on Verify email ID or Verify phone number option
Enter the UIN/VID.
Select I’m not a robot against the captcha and click on Send OTP.
Resident enters the OTP received on the requested channel and clicks on Submit.
Based on the scenario, any of the below three messages will be displayed:
a. Email ID/ phone number successfully verified: On successful verification, a message is displayed on the screen saying that the phone number/ email ID has been successfully verified.
b. Email ID/ phone number was already verified: If the verification has been previously completed, a message is displayed saying the email ID/ phone number was already verified.
c. Email ID/ phone number does not exist: If there is no email ID/ phone number linked to the UIN/VID, a message is displayed saying no email ID/ phone number was found associated to this UIN/VID.
The residents can use this feature for one of the following:
Download their UIN card
Check the status of their Application ID (AID)
Steps to download the UIN:
Resident clicks on Get My UIN
Enter the AID/UIN/VID.
Select I’m not a robot against the captcha and click on Send OTP.
Resident enters the OTP received on the registered email ID/ phone number and clicks on Submit.
The default PDF of UIN card will be downloaded and a success message is seen stating that the UIN has been successfully downloaded.
Steps to check the status of the AID:
Note: If the UIN is not ready, then the AID is used to get status else UIN card will be downloaded using AID too.
Resident clicks onGet My UIN.
Enter the AID.
Select I’m not a robot against the captcha and click on Send OTP.
Resident enters the OTP received on the registered email ID/ phone number and clicks on Submit.
The status of the AID will be shown.
Residents can view the list of supported documents in the PDF format and download the same. Also, some sample documents are available for reference.
Residents can search for Registration Centres on the basis of below two mechanisms:
Nearby centers: The resident will be asked to allow permission for location access in order to enable the system to suggest the nearest Registration Centres.
Manually look for centers: If the Resident wants to manually look for a center, they can do so by choosing a level in location hierarchy from the drop-down (e.g.: Region, Province, Postal Code) and entering the value against the same.
They can also download the PDF version of the result displayed on the screen for reference.
Update My Data
Identity data
Name
DOB
Gender
POI document
Address
Full address
POA document
Contact Information
Phone number
Email ID
Preferred Language
Identity Data: Residents can update their identity data like Name, Date of Birth, Gender certain number of times (number of times the identity data can be updated is configurable). To update the Identity Data, the residents will have to do the following:
a. Go to “Update My Data”
b. Click on “Identity” tab
c. Enter the new Name/ new Date of Birth/ new Gender in preferred language.
d. The resident will then have to choose the type of document from drop-down.
e. Upload a valid supporting document as Proof of Identity to back their change in identity request.
f. Once the document is uploaded, the “Preview” button will be made clickable
g. The Residents will then be taken to the preview screen where they can view the updated data and the uploaded supporting document which they can modify if required. When the resident is satisfied with all the data entered, he can go ahead and submit the data update request by clicking on “Update” button.
h. The Resident will then have to accept the terms and conditions and click on “Submit” button to submit the data update request.
i. Once the event is completed, a message will be displayed containing the Event ID along with a link to track the service.
j. A bell icon and an email notification will be triggered using which the residents can view the status of the application.
k. Once the update is successful, the card can be downloaded with new data by clicking on the particular notification.
Note: The Resident can update the Proof of Identity document itself with no change in data.
Address: Residents can update their partial address or full address on the basis of their requirement any number of times. To update the Address, the residents will have to do the following:
a. Go to “Update My Data”
b. Click on “Address” tab
c. Enter the new address.
d. The resident will then have to choose the type of document from drop-down.
e. Upload a valid supporting document as Proof of Address to support their change in address request.
f. Once the document is uploaded, the preview button will be enabled.
g. The Residents will be taken to the preview screen where they can view the updated data and the uploaded supporting document which they can modify if required by clicking on the pencil icon.
h. When the resident is satisfied with all the data entered, they can go ahead and submit the data update request by clicking on “update”.
i. The Resident will also have to accept the terms and conditions in order to proceed and click on “Submit” button to proceed.
j. Once the event is successful, a message will be displayed consisting of the Event ID along with a link to track the service.
k. A bell icon and an email notification will be triggered using which the residents can view the status of the application.
l. Once the update is successful, the card can be downloaded with new data by clicking on the particular notification.
Note: Additionally, the Resident can also update the Proof of Address document itself with no change in data.
Contact Data: Residents can update their existing email ID and phone number. To update the Contact Data, the residents will have to do the following:
a . Go to “Update My Data”.
b. Click on “Contact Data” tab.
c. Enter the new email ID or Phone number (whichever needs to be updated).
d. The Resident will receive an OTP over their new email ID/ Phone number and thereby entering the OTP received on the new email ID/ phone number.
e. Once the event is completed, a message will be displayed consisting of the Event ID along with a link to track the service.
f. A bell icon and an email notification will be triggered using which the residents can view the status of the application.
g. Once the update is successful, the card can be downloaded with new data by clicking on the particular notification.
Notification Language Preference: Residents can update the language in which all the notifications are being sent to them. The residents can change the notification language as many times as they want to. To update the Notification Language, the residents will have to do the following:
a. Go to “Update My Data”
b. Go to “Language Preference” tab
c. Click on the “New Notification Language” drop-down.
d. Choose the new Notification Language and click in “Submit” button.
e. On clicking on “Submit”, a message will be displayed consisting of the Event ID along with a link to track the service.
Multi-Lingual Support:
The Residents can view the entire portal in the language that they prefer using the language change option on the top right corner of the screen. On choosing any language, all the labels/ texts/ success or error messages, PDF downloads will be displayed in the chosen language.
To change the language, the residents will have to do the following:
Click on the language option from the header menu.
On clicking the language option, a drop-down will open that will have the list of languages in which the Resident Portal can be rendered in.
On choosing any language, the screen will be refreshed and the entire portal will be rendered in the chosen language.
Menu option in English.
Menu option in French
Menu option in Arabic
Note: Only one update request can be raised at a time. A second update request can only be initiated when there are no existing requests in progress. If the user still wants to request another data update, they can discard the request in progress (only the requests that are in "Draft" stage in ID Repository can be discarded) and then raise a new data update request.
Resident Portal is a self-help web-b portal that can be used by the residents of a country to avail of the services related to their Unique Identification Number (UIN). The architecture, interface overview, and key services provided are discussed below:
Architecture
Interface overview
Key Services
UIN services
View My History
Secure My ID
Manage My VID
Track My Request
Download My Personalized Card
Update My Data
Share My Credential
Get Information
Supporting Document
Registration Center
Verify Email ID/Phone number
Get My UIN
Booking an Appointment
Below is a detailed explanation of each of the features along with the list of relevant APIs.
The Resident Portal menu bar contains the following:
Font Size- Residents can alter the size of the font based on their preferences.
Language- Residents can select the language of preference.
Bell icon Notification- Residents can view the notifications of all the asynchronous events in chronological order.
Profile Icon- Residents can view the following:
Name of the logged in user
Photo of the logged in user
Last login details
Logout option
A dashboard view to quickly locate the 'Key Services'
The residents can view the history of all the transactions associated with their logged-in UIN/ AID/ VID. They can also view their details and if any unaccounted entry is found, a report can be raised against the same.
On clicking “Secure My ID”, the residents can view the status of all the authentication types. They can choose to lock or unlock authentication types like the following:
Email OTP authentication
Phone OTP authentication
Demographic authentication
Fingerprint authentication
Iris authentication
Face authentication
Fetch Authentication Types - Lock status of the individual
Applies the Authentication Types Lock/Unlock request in IDA
On clicking “Manage My VID”, the resident will be taken to a page where they can view details of the existing VIDs, generate new VID, revoke existing VIDs, or download a VID card.
The following types of VIDs can be seen based on the VID policy:
Perpetual VID
Temporary VID
One-time VID
Fetch Active VIDs of the Individual
Revoke the VID of the Individual
Store the Credential Request ID and a new Event ID
Notify that the VID card is Ready to Download status.
Download PDF Card
On clicking “Track My Requests”, the residents can track the status of an Event ID (EID) associated with the logged-in UIN/ VID. They can also view and download the detailed information about the entered EID.
On clicking “Get Personalized Card”, the residents can select the data to be added to their credential. They can preview the chosen data and download it. Residents should select at least 3 attributes.
Creates the personalized card and signs it
On clicking “Share My Data”, the residents can choose the data to be shared with any of the registered partners to avail various third party services.
Submits the share credential request
Notifies resident about the credential shared status for the event ID
Fetch existing AID in progress
Submits the update request
Notifies that the UIN card is ready to Download status
Notify for IDENTITY_UPDATED for the Event Id
Get the Status for the AID
Validate the Access token and ID token
Fetch Supporting Documents PDF
Fetch registration centers
The residents can use this feature to verify their registered email ID or phone number.
The residents can use this feature for one of the following:
Download their UIN card
Check the status of their Application ID (AID)
Get PDF card for AID if ready
Check if PDF card URL is notified by Digital card service.
Validates the Action token and ID token.
UI specs of resident module are used to configure the form fields across Resident Portal. UI specs are saved as a JSON file with a list of fields. Each field has a set of attributes/ properties that can be configured which affects the look and feel along with the functionality of the field.
Below is the list of all the properties available for each field in the Resident Portal UI specs:
The residents can book an appointment for registration using the pre-registration portal. To do so, they can click on “Book an appointment” tile which will redirect them to the pre-registration portal. To know more about pre-registration portal, refer to this link [ ]
Property Name
Details
Sample Value
id
The id property is the unique id provided to a field to uniquely identify it. The id can be alpha-numeric without any spaces between them.
"id":"zone"
description
This is a non-mandatory property used to describe the field.
"description": "zone"
labelName
This property defines label name for the field. This property has sub-attributes as the language code (eng, fra, ara) to store data in different languages based on the country's configuration.
"labelName": { <br>"eng": "Zone", <br>"ara": "منطقة", <br>"fra": "Zone"}
controlType
This property defines the kind of UI component to be used to capture data in UI. Currently the values that can be used are: <br/> • textbox (creates multiple textboxes for each field to capture input in all the languages configured for the setup)<br/>• dropdown <br/>• fileupload <br/> • date (creates a date picker)<br/> • ageDate (creates a date picker along with number toggle to provide age directly)<br/> • checkbox (creates a toggle checkbox for the field which can be checked or unchecked)<br/> • button (creates dropdown options as buttons, which user can select easily)
inputRequired
This property decides if the field is to be displayed in the UI form or not. It is useful for some internal fields which do not need any input from the user.
required
This is a mandatory property which decides if the field is a required form field or not. If true, user must provide some value for the field.
type
This property defines the data type of the value corresponding to this field. The data types supported are “number”, “string” and “simpleType”.<br/> The type “simpleType” means that language specific value will be saved along with the language code.
fieldType
This property is relevant when control type is “dropdown” or “button”. It defines if the field is of type “default” or “dynamic”. <br/>If it is “dynamic” then all the options for the dropdown are populated from the “master.dynamic_field” table otherwise they are populated from corresponding table example “master.gender”
subType
This is relevant for 2 cases:<br/>1. When control type is “dropdown”/ “button” and the type is “dynamic” then “subtype” can be used to populate the options for the field with the data available in “master.dynamic_field” table.<br/>2. When the control type is “fileupload”, then the property ”subtype” is used to map the field to a “code” in the “master.doc_category” table.
validators
This property enables us to add the list of language specific validators for the field. <br/>* Each validator can have the below fields,<br/>“langCode”,<br/>“type”,<br/>“validator”,<br/>“arguments”,<br/>“errorMessageCode”<br/><br/>* The “type” defines the validation engine type.<br/>* The “validator” gives the pattern/ methodName/ scriptName/ expression<br/>* The “arguments” array to is used to hold parameter or dependent field ids required for validation<br/>* The “errorMessageCode” can be given to add custom error message which will be shown to the user when the validation fails. The error message corresponding to this code will be picked from language specific i18n translation files. In case “errorMessageCode” is not given then generic error message will be displayed to the user when validation fails. <br/><br/>Currently, regex is supported by MOSIP.<br/>If “langCode” is not added then same “validator” is used for all languages of the field.
<br>"validators": [{ <br>"langCode": "eng", <br>"type": "regex", <br>"validator": "^(?=.{0,50}$).*", <br>"arguments": [], <br>"errorMessageCode": "UI_1000"<br>},{ <br>"langCode": "ara", <br>"type": "regex", <br>"validator": "^[A-Z]+$", <br>"arguments": []<br>},{ <br>"langCode": "fra", <br>"type": "regex",<br>"validator": "^[A-Z]+$", <br>"arguments": []<br>}]
locationHierarchyLevel
This attribute is mandatory for the location dropdown fields. <br/>The value will be as per corresponding location hierarchy level from the master.loc_hierarchy_list table.
{<br>"id":"region",<br>"controlType":"dropdown",<br>"fieldType":"default",<br>"type":"simpleType",<br>"parentLocCode":"MOR",<br>"locationHierarchyLevel":1<br>..}
parentLocCode
This attribute is to be used only for location dropdown fields and it is optional. <br/>The corresponding location dropdown will be pre populated in UI based on the value in “parentLocCode”. <br/>If this attribute is NOT mentioned in UI specs, then the dropdown will be populated based on selection in its parent dropdown, as before. <br/>For the first dropdown, in case this attribute is not mentioned in UI specs then the value from “mosip.country.code” configuration will be used for backward compatibility.
{<br>"id":"region",<br>"controlType":"dropdown",<br>"fieldType":"default",<br>"type":"simpleType",<br>"parentLocCode":"MOR",<br>"locationHierarchyLevel":1<br>..}
alignmentGroup
* This property is used to group the fields on the screen. <br>* If it is skipped, then all the fields will appear in same sequence (horizontally layout) as they appear in UI specs. <br>* If you want the first and fifth field to be in same row in the screen, you can add this attribute with same group name. <br>* The UI is responsive so it will accommodate as many fields in one row as they will fit comfortably.
containerStyle
This is used to optionally apply some CSS styles to the UI field container.
"containerStyle": {<br>"width": "600px",<br>"margin-right": "10px"<br>}
