Overview

This service creates request for credential issuance.

1. Keymanager encrypts/decrypts data.

2. Auth Adapter integrates with Keycloak for authentication.

The documentation here will guide you through the prerequisites required for the developer' setup.

Software setup

Below are a list of tools required in ID Repository (Credential Request Generator Service) setup:

1. JDK 11

2. Any IDE (like Eclipse, IntelliJ IDEA)

3. Apache Maven (zip folder)

4. pgAdmin

5. Postman

6. Git

7. Notepad++ (optional)

8. lombok.jar (file)

9. settings.xml (document)

Follow the steps below to set up ID Repository Services on your local system:

1. Download lombok.jar and settings.xml from here.

2. Unzip Apache Maven and move the unzipped folder in C:\Program Files and settings.xml to "conf" folder C:\Program Files\apache-maven-3.8.4\conf.

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

4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse to see if the lombok.jar is added. By doing this, you don't have to add the dependency of lombok in your pom.xml file separately as it is auto-configured by Eclipse.

5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Code setup

For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.

Importing and building of a project

1. Open the project folder where pom.xml is present.

2. Open command prompt from the same folder.

3. Run the command mvn clean install -Dgpg.skip=true to build the project and wait for the build to complete successfully.

4. After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.

5. After successful importing of project, update the project by right-click on Project → Maven → Update Project.

Environment setup

1. For the environment setup, you need an external JAR that is available here with different versions. (E.g.: You can download kernel-auth-adapter.jar and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close).

2. Clone mosip-config repository.

3. Create an empty folder inside the mosip-config with sandbox-local name and then copy and paste all config files inside sandbox-local folder except .gitignore, README and LICENSE.

4. As ID Repository is using two properties files, id-repository-default and application-default, you will have to configure them according to your environment. The same files are available here for reference.

Properties to be updated:

application-default.properties

• mosip.mosip.resident.client.secret = <current_password>.

• db.dbuser.password=<password>.

• mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/(i.e. sandbox-local folder location).

• Comment this out auth.server.admin.issuer.internal.uri in application-default.properties file because you already have this auth.server.admin.issuer.uri , and hence there is no need of auth.server.admin.issuer.internal.uri.

• mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json)

id-repository-default.properties

• mosip.credential.service.database.hostname

• mosip.credential.service.database.port

5. To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.

6. Put both the files in the same folder and change the location attribute to sandbox-local folder in config-server-start.bat file and also check the version of kernel-config-server.jar towards the end of the command.

Example:

java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=/home/vipul/Desktop/tspl/mosip-config/sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar.

7. Run the server by opening the config-server-start.bat file.

The server should now be up and running.

Below are the configurations to be done in Eclipse:

1. Open Eclipse and run the project for one time as 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 environment - "Credential-request-generator-dev").

2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master in VM arguments.

3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net or qa3.mosip.net).

4. Click Apply and then debug it (starts running).

Credential Request Generator Service API

• For API documentation, refer here.

• The APIs can be tested with the help of Swagger-UI.

• Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of credential-request-generator-services for localhost from https://localhost:8094/v1/credentialrequest/swagger-ui/index.html?configUrl=/v1/credentialrequest/v3/api-docs/swagger-config#/.

What is .well-known folder?

The ".well-known" folder is a convention used in web development to provide a standardized location for certain files or resources that need to be publicly accessible and discoverable. It typically resides at the root level of a website or web server. The purpose of this folder is to make it easy for web clients (browsers, applications, or services) to find important files or resources related to web services and security.

Why should we use ".well-know" directory in MOSIP?

MOSIP can use the ".well-known" directory to serve the following purposes:

• Standardization: To provide a standardized location for specific public files and resources related to web services and security. It makes it easier for developers and web clients using MOSIP to know where to look for important information.

• Security: Security-related files and resources can be placed in the ".well-known" directory, such as the public certificate for encryption and signature verification can be placed here.

• Interoperability: By following the ".well-known" convention, web developers using MOSIP can ensure interoperability with various web standards and protocols. For example, MOISP shares the context file which contains the structure of its Verifiable Credentials.

• Ease of Configuration: Web servers can be configured to serve files from the ".well-known" directory without needing custom configurations for each specific resource. This simplifies the server setup and maintenance process.

• Transparency: For matters related to security policies and contact information, such as in the "security.txt" file, placing them in a well-known location makes it transparent and easily accessible to anyone interested in the website's security practices.

How is ".well-known" directory used in MOISP?

MOSIP's ".well-know" directory contains three files,

• controller.json

• mosip-context.json

• public-key.json

controller.json

The "controller.json" file is used in MOSIP to share the details of the public key using which a MOSIP-issued verifiable credential can be asserted.

{
  "@context": "https://w3id.org/security/v2",
  "id": "https://api.collab.mosip.net/.well-known/controller.json",
  "assertionMethod": [
    "https://api.collab.mosip.net/.well-known/public-key.json"
  ]
}

mosip-context.json

The "mosip-context.json" file contains the schema of the subject in the MOSIP-issued verifiable credential.

{
  "@context": [{
       "@version": 1.1
    },"https://www.w3.org/ns/odrl.jsonld", {
    "mosip": "https://api.collab.mosip.net/mosip#",
    "schema": "http://schema.org/",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "vcVer": "mosip:vcVer",
    "UIN": "mosip:UIN",
    "addressLine1": {
        "@id": "https://api.collab.mosip.net/mosip#addressLine1",
        "@context": {"value": "rdf:value", "lang": "@language"}
    },
    "addressLine2": {
        "@id": "https://api.collab.mosip.net/mosip#addressLine2",
        "@context": {"value": "rdf:value", "lang": "@language"}
    },
    "addressLine3": {
        "@id": "https://api.collab.mosip.net/mosip#addressLine3",
        "@context": {"value": "rdf:value", "lang": "@language"}
    },
    "city": {
        "@id": "https://api.collab.mosip.net/mosip#city",
        "@context": {"value": "rdf:value", "lang": "@language"}
    },
     "gender": {
        "@id": "https://api.collab.mosip.net/mosip#gender",
        "@context": {"value": "rdf:value", "lang": "@language"}
    },
     "residenceStatus": {
        "@id": "https://api.collab.mosip.net/mosip#residenceStatus",
        "@context": {"value": "rdf:value", "lang": "@language"}
    },

    "dateOfBirth": "mosip:dateOfBirth",
    "email": "mosip:email",
    "fullName": {

        "@id": "https://api.collab.mosip.net/mosip#fullName",

        "@context": {"value": "rdf:value", "lang": "@language"}
    },
  "phone": "mosip:phone",
    "postalCode": "mosip:postalCode",
    "province": {

        "@id": "https://api.collab.mosip.net/mosip#province",
        "@context": {"value": "rdf:value", "lang": "@language"}
    },
    "region": {
        "@id": "https://api.collab.mosip.net/mosip#region",

        "@context": {"value": "rdf:value", "lang": "@language"}
    },
    "biometrics": "mosip:biometrics"
  }]
}

public-key.json

The "public-key.json" file contains the public key using which the signature of the MOSIP-issued verifiable credential can be asserted.

{
  "@context": "https://w3id.org/security/v2",
  "type": "RsaVerificationKey2018",
  "id": "https://api.collab.mosip.net/.well-known/public-key.json",
  "controller": "https://api.collab.mosip.net/.well-known/controller.json",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\r\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA07+Esb/PSV2e5p/afi4O\r\n6ICRD699POqCWzt9obGBPHdmPTD3QYU3c/CnEPNHBzvQKWcaIWRmwTi8yGAwyUU9\r\n5ESU9/o78ACHrcFRIdluuiQuhDP4ojQLDpX/dPULPc/dt96b5t1uPhELnySq/EPr\r\n6hcqGuMyLl/yfKr/vQdaTqKmmrm8gTTnzsQ4jvpeucrDEBqm5LtSzYQb4PRMQe0u\r\nhrnZjbVmoUKCNpXXrKMfswqLhz2gInkN7+SJToCEcEj1f2tJYUsL0LufceEQQFy0\r\nKaq+Xu1Jx1OwnRP1HhS8aepLct8O1H3e0DrMCLgSZ89HiSpWQ+0DMKDMdROCm7uU\r\noQIDAQAB\r\n-----END PUBLIC KEY-----"
}

Overview

VID Service provides functionality to create/update Virtual IDs mapped against an UIN. It also provides the facility to update the status of VID. VIDs are created based on the VID policy defined in the configuration.

The documentation here will guide you through the prerequisites required for the developer' setup.

Software setup

Below are a list of tools required in ID Repository VID Services setup:

1. JDK 11

2. Any IDE (like Eclipse, IntelliJ IDEA)

3. Apache Maven (zip folder)

4. pgAdmin

5. Postman

6. Git

7. Notepad++ (optional)

8. lombok.jar (file)

9. settings.xml (document)

Follow the steps below to set up ID Repository (VID Services) on your local system:

1. Download lombok.jar and settings.xml from here.

2. Unzip Apache Maven and move the unzipped folder in C:\Program Files and settings.xml to "conf" folder C:\Program Files\apache-maven-3.8.4\conf.

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

4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse to see if the lombok.jar is added. By doing this, you don't have to add the dependency of lombok in your pom.xml file separately as it is auto-configured by Eclipse.

5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Code setup

For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.

Importing and building of a project

1. Open the project folder where pom.xml is present.

2. Open command prompt from the same folder.

3. Run the command mvn clean install -Dgpg.skip=true to build the project and wait for the build to complete successfully.

4. After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.

5. After successful importing of project, update the project by right-click on Project → Maven → Update Project.

Environment setup

1. For the environment setup, you need an external JAR that is available here with different versions. (E.g.: You can download kernel-auth-adapter.jar and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close).

2. Clone mosip-config repository.

3. Create an empty folder inside the mosip-config with sandbox-local name and then copy and paste all config files inside sandbox-local folder except .gitignore, README and LICENSE.

4. As Id Repository is using two properties files, id-repository-default and application-default, you will have to configure them according to your environment. The same files are available here for reference.

Properties to be updated:

application-default.properties

• mosip.mosip.resident.client.secret = <current_password>.

• db.dbuser.password=<password>.

• mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/(i.e. sandbox-local folder location).

• Comment this out auth.server.admin.issuer.internal.uri in application-default.properties file because you already have this auth.server.admin.issuer.uri , and hence there is no need of auth.server.admin.issuer.internal.uri.

• mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json)

id-repository-default.properties

• mosip.idrepo.db.url

• mosip.idrepo.db.port

• Comment out all the lines containing mosip.biometric.sdk.providers.finger, mosip.biometric.sdk.providers.face and mosip.biometric.sdk.providers.iris.

• mosip.idrepo.mosip-config-url=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/(i.e. sandbox-local folder location).

5. To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.

6. Put both the files in the same folder and change the location attribute to sandbox-local folder in config-server-start.bat file and also check the version of kernel-config-server.jar towards the end of the command.

Example:

java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar.

7. Run the server by opening the config-server-start.bat file.

The server should now be up and running.

Below are the configurations to be done in Eclipse:

1. Open Eclipse and run the project for one time as 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 environment - "vid-service-dev").

2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master in VM arguments.

3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net or qa3.mosip.net).

4. Click Apply and then debug it (starts running).

VID Service API

• For API documentation, refer here.

• The APIs can be tested with the help of Swagger-UI.

• Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of resident-services for localhost from http://localhost:8091/idrepository/v1/swagger-ui/index.html?configUrl=/idrepository/v1/v3/api-docs/swagger-config#/.

Overview

• Identity Service stores, updates, retrieves identity information.

• Also, retrieves and updates UIN status.

The documentation here will guide you through the prerequisites required for the developer' setup.

Software setup

Below are a list of tools required in ID Repository Services (Identity Service) setup:

1. JDK 11

2. Any IDE (like Eclipse, IntelliJ IDEA)

3. Apache Maven (zip folder)

4. pgAdmin

5. Postman

6. Git

7. Notepad++ (optional)

8. lombok.jar (file)

9. settings.xml (document)

Follow the steps below to set up ID Repository- Identity Services on your local system:

2. Unzip Apache Maven and move the unzipped folder in C:\Program Files and settings.xml to "conf" folder C:\Program Files\apache-maven-3.8.4\conf.

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

4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse to see if the lombok.jar is added. By doing this, you don't have to add the dependency of lombok in your pom.xml file separately as it is auto-configured by Eclipse.

5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Code setup

Importing and building of a project

1. Open the project folder where pom.xml is present.

2. Open command prompt from the same folder.

3. Run the command mvn clean install -Dgpg.skip=true to build the project and wait for the build to complete successfully.

4. After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.

5. After successful importing of project, update the project by right-click on Project → Maven → Update Project.

Environment setup

3. Create an empty folder inside the mosip-config with sandbox-local name and then copy and paste all config files inside sandbox-local folder except .gitignore, README and LICENSE.

Properties to be updated:

application-default.properties

• mosip.mosip.resident.client.secret = <current_password>.

• db.dbuser.password=<password>.

• mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/(i.e. sandbox-local folder location).

• Comment this out auth.server.admin.issuer.internal.uri in application-default.properties file because you already have this auth.server.admin.issuer.uri , and hence there is no need of auth.server.admin.issuer.internal.uri.

• mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json)

id-repository-default.properties

• mosip.idrepo.db.url

• mosip.idrepo.db.port

• Comment out all the lines containing mosip.biometric.sdk.providers.finger, mosip.biometric.sdk.providers.face and mosip.biometric.sdk.providers.iris.

• Comment out this property mosip.kernel.idobjectvalidator.referenceValidator.

• mosip.idrepo.mosip-config-url=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/(i.e. sandbox-local folder location).

6. Put both the files in the same folder and change the location attribute to sandbox-local folder in config-server-start.bat file and also check the version of kernel-config-server.jar towards the end of the command.

Example:

java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar.

7. Run the server by opening the config-server-start.bat file.

The server should now be up and running.

Below are the configurations to be done in Eclipse:

1. Open Eclipse and run the project for one time as 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 environment - "Identity-Service-dev").

2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master in VM arguments.

3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net or qa3.mosip.net).

4. Click Apply and then debug it (starts running).

Identity service API

• The APIs can be tested with the help of Swagger-UI.

• Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of identity-services for localhost from http://localhost:8090/idrepository/v1/identity/swagger-ui/index.html?configUrl=/idrepository/v1/identity/v3/api-docs/swagger-config#/.

Overview

ID Repository contains the records of identity of an individual, and provides API based mechanism to store, retrieve and update identity details by other MOSIP modules. ID Repository is used by Registration Processor, ID Authentication and Resident Services.

Services

ID Repository module consists of the following components:

1. Identity service

2. VID service

3. Credential service

4. Credential Request Generator service

5. Credential Feeder

6. Salt generator

Identity service

• Stores, updates, retrieves identity information.

• Also, retrieves and updates UIN status.

Identity service uses Biometric SDK (server) to extract templates from provided biometric data.

Above is the entity relationship diagram illustrated for Identity service. NOTE: The numbers do not signify sequence of operations or control flow. Arrows indicate the data flow.

1. Key Manager encrypts/decrypts data.

2. Credential request generator issues credentials for new/updated UIN data.

3. Object Store stores/retrieves biometrics and demographic documents.

4. All demographic data of UIN and references to biometric and demographic files stored in object store are stored in mosip_idrepo DB.

5. Partner management service retrieves online verification partners to issue credentials.

6. Audit logs are logged into Audit Manager.

7. Biometric SDK extracts the templates for input biometric data.

8. Auth Adapter integrates with KeyCloak for authentication.

9. Masterdata service retreives Identity schema based on input schema version.

10. WebSub publishes events related to UIN updation and auth type status updates.

11. Kernel ID generator generates UIN.

12. VID service fetches the list of VIDs associated with UIN to issue credential of update UIN and to create and activate draft VID.

VID service

VID Service provides functionality to create/update Virtual IDs mapped against an UIN. It also provides the facility to update status of VID. VIDs are created based on the VID policy defined in the configuration.

1. Key Manager encrypts/decrypts data.

2. Credential request generator issues credentials for new/updated UIN data. 3 All VID related data is stored in mosip_idmap DB.

3. Partner management service retrieves online verification partners to issue credentials.

4. Audit logs are logged into Audit Manager.

5. Auth Adapter integrates with KeyCloak for authentication.

6. WebSub publish events related to VID updation.

7. Kernel ID generator generates VID.

8. Identity service checks the status of UIN to create VID.

Credential service

1. Key Manager encrypts/decrypts data and also used to sign data.

2. WebSub subscribes to get notifications related to credential status from IDA.

3. DataShare creates datashare url for sharable attributes.

4. Identity service retrieves identity data for UIN/VID.

5. Partner management service retrieves policies related to credential type and also retrieves policy for bio-extraction.

6. Auth Adapter integrates with KeyCloak for authentication.

Credential types

A credential can be defined as any document, object, or data structure that vouches for the identity of a person through some method of trust and authentication. Simply put, a credential is the thing that a person presents—in person or remotely—to say "this is who I am." The types of credentials issued in an ID system vary along multiple dimensions, depending on whether they are physical (i.e., they must be physically carried by a person in order to use them), or digital (i.e., they are machine readable and therefore can be used in a digital environment).

A credential type essentially maps to partner and data share policy.

Default credential types provided as part of sandbox deployment are given below:

1. auth: Represents individual's data shared with Online Verification Partners (further used for Authentication and eKYC).

2. qrcode: qrcode type is used for qrcode partners to issue qrcode related credential data.

3. euin: It is used to issue credential data to partners who wish to download euin card using euin policy.

4. reprint: Reprint auth type is used for issuing credential information to reprint partners.

5. vercred: To issue verifiable credentials to partners, vercred credential type is used.

These types are defined in partner_policy_credential_type table of mosip_pms database.

New credential types may be defined as per needs of a country.

Credential request generator service

This service creates request for credential issuance.

1. Key Manager encrypts/decrypts data.

2. Auth Adapter integrates with KeyCloak for authentication.

Credential feeder

This job will feed the existing UIN/ VID identity information to newly deployed IDA instance.

Salt generator

This is a one-time job that populates salts that are used to hash and encrypt data for Identity and VID services. This job must be executed before deploying these services. The following tables are populated:

• uin_hash_salt in mosip_idrepo DB.

• uin_encrypt_salt in mosip_idmap DB.

In MOSIP sandbox, the job is run here.

Developer Guide

To know more about the developer setups, read:

1. Credential Request Generator Service Developers Guide

2. Identity Service Developers Guide

3. VID Service Developers Guide

API

Refer API Documentation.

Source code

Github repo.