Introduction

Running a national ID system is no mean task and involves numerous challenging aspects. The software system at the core is a critical infrastructure and needs to address high availability, reliability, scalability, security, resilience, and manageability. Choosing the right deployment architecture plays an important role in helping achieving architectural goals while also catering to the law of the land. Cost of implementing such an architecture also matters.

Mosip has a micro-services architecture that organizes functionality into myriad small services and execution units. Each of these can be scaled separately as well as replaced / upgraded. This makes the platform powerful and provides plenty of flexibility and configurability in the hands of the implementor. There is also the corresponding complexity of dealing with a higher number of components in the system in the areas of configuration, security, deployment, dependency management, monitoring and testing.

Deployment architecture choices

In order to get the best out of mosip and keep manageability high the deployment architecture plays a crucial role. Let us take a look at a few of the common deployment architecture options available based on various perspectives.

• Packaging choices

  • Option 'Jar' - Spring boot services in Virtual Machines|

  • Option 'Docker' - Dockers on a Kubernetes container management setup

• Infrastructure choices

  • Option 'On-Premise' - Deploy in a private or own data center

  • Option 'Cloud' - Deploy in a cloud

  • Option 'Hybrid' - Cloud + On Premises

• Platform choices

  • Option 'Open Source' - Proven community favored platforms

  • Option 'Cloud Native' - Cutting edge supported cloud technologies from AWS, Azure, GCP et al

  • Option 'Commercial' - Established and well supported priced packages

Security: Deployment with secure zones

The architecture proposed may be deployed on-premise or cloud. Here, all MOSIP modules are installed with clear separation between militarised and demilitarised zones.

Scalability: Cell based architecture

For linear scaling of capacity and provisioning of hardware, a cell based architecture (along with secure zones) may be preferred.

Cell based architecture

Rapid deployment: Hybrid architecture

A hybrid architecture may be considered where benefits of cloud and on-premise are leveraged. While cloud provides rapid deployment and ease of management, on-premise can facilitate data localization and any other policy requirements.

An example of hybrid architecture is given below:

This documentation is for setting up HDFS (v2.8.1) cluster with one namenode and one datanode

Setup HDFS version 2.8.1

Prerequisites

• Create 2 VMs. They’ll be referred to throughout this guide as,

• Install java (java-8-openjdk) to all the machines in the cluster and setup the JAVA_HOME environment variable for the same.

• Get your Java installation path.

Note: Take the value of the current link and remove the trailing /bin/java.

For example on RHEL 7, the link is /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.191.b12-1.el7_6.x86_64/jre/bin/java

So JAVA_HOME should be /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.191.b12-1.el7_6.x86_64/jre.

Edit ~/bashrc.sh:

• Export JAVA_HOME={path-tojava} with your actual java installation path.

For example on a Debian with open-jdk-8: export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.191.b12-1.el7_6.x86_64/jre

Note: In the further steps when u login to the hadoop account set the java path in ~/hadoop/etc/hadoop/hadoop-env.sh also.

• Get the IP of master and slave nodes using:
• Adjust /etc/hosts on all nodes according to your configuration.

Note:

While adding same machine ip to /etc/hosts, use private ip that machine instead of public IP. For other machine in the cluster use public IP. * Edit the Master node VM /etc/hosts file use private IP of Master node and public IP of the Slave node. * Edit the Slave node VM /etc/hosts file use private IP of Slave node and Public IP of Master node. * Example: 10.0.22.11 node-master.example.com 10.0.3.12 node-slave1.example.com

Creating Hadoop User

Create a hadoop user in every machine in the cluster to followup the documentation or replace the hadoop user in the documentation with your own user.

• Log in to the system as the root user.
• Create a hadoop user account using the useradd command.
• Set a password for the new hadoop user using the passwd command.
• Add the haddop user to the wheel group using the usermod command.
• Test that the updated configuration allows the user you created to run commands using sudo.

  • Use the su to switch to the new user account that you created.

  • Use the groups to verify that the user is in the wheel group.

  • Use the sudo command to run the whoami command. As this is the first time you have run a command using sudo from hadoop user account the banner message will be displayed. You will be also be prompted to enter the password for the hadoop account.

  • The last line of the output is the user name returned by the whoami command. If sudo is configured correctly this value will be root.

You have successfully configured a hadoop user with sudo access. You can now log in to this hadoop account and use sudo to run commands as if you were logged in to the account of the root user.

Distribute Authentication Key-pairs for the Hadoop User

The master node will use an ssh-connection to connect to other nodes with key-pair authentication, to manage the cluster.

• Login to node-master as the hadoop user, and generate an ssh-key:

  id_rsa.pub will contains the generated public key

• Copy the public key to all the other nodes.

  or

  Update the $HOME/.ssh/id_rsa.pub file contents of slave node to Master node $HOME/.ssh/authorized_keys file and also Update $HOME/.ssh/id_rsa.pub file contents of Master node to Slave node $HOME/.ssh/authorized_keys manually.

Verify ssh from Master node to slave node and vice versa.

Note: if ssh fails, try setting up again the authorized_keys to the machine.

Download and Unpack Hadoop Binaries

Login to node-master as the hadoop user, download the Hadoop tarball from Hadoop project page, and unzip it: cd wget https://archive.apache.org/dist/hadoop/core/hadoop-2.8.1/hadoop-2.8.1.tar.gz tar -xzf hadoop-2.8.1.tar.gz mv hadoop-2.8.1 hadoop

Set Environment variables in each machine in the cluster

Add Hadoop binaries to your PATH. Edit /home/hadoop/.bashrc or /home/hadoop/.bash_profile and add the following line: export HADOOP_HOME=$HOME/hadoop export HADOOP_CONF_DIR=$HOME/hadoop/etc/hadoop export HADOOP_MAPRED_HOME=$HOME/hadoop export HADOOP_COMMON_HOME=$HOME/hadoop export HADOOP_HDFS_HOME=$HOME/hadoop export YARN_HOME=$HOME/hadoop export PATH=$PATH:$HOME/hadoop/bin export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.191.b12-0.el7_5.x86_64/jre Run following command to apply environment variable changes, using source command: source /home/hadoop/.bashrc or source /home/hadoop/.bash_profile

Configure the Master Node

Configuration will be done on node-master and replicated to other slave nodes.

Set NameNode

Update ~/hadoop/etc/hadoop/core-site.xml: <configuration> <property> <name>fs.defaultFS</name> <value>hdfs://node-master.example:51000</value> </property> </configuration>

Set path for HDFS

• Edit ~/hadoop/etc/hadoop/hdfs-site.xml:
• Create directories

Configure Master

Edit ~/hadoop/etc/hadoop/masters to be: node-master.example.com

Configure Slaves

Edit ~/hadoop/etc/hadoop/slaves to be: This slaves file will specifies the datanode to be setup in which machine node-slave1.example.com

Create duplicate config files on each node

• Copy the hadoop binaries to slave nodes:

  or copy each configured files to other nodes

• Connect to node1 via ssh. A password isn’t required, thanks to the ssh keys copied above:
• Unzip the binaries, rename the directory, and exit node-slave1.example.com to get back on the node-master.example.com:
• Copy the Hadoop configuration files to the slave nodes:

Format HDFS

HDFS needs to be formatted like any classical file system. On node-master, run the following command: hdfs namenode -format Your Hadoop installation is now configured and ready to run.

Start HDFS

• Start the HDFS by running the following script from node-master: start-dfs.sh, stop-dfs.sh script files will be present in hadoop_Installation_Dir/sbin/start.dfs.sg

It’ll start NameNode and SecondaryNameNode on node-master.example.com, and DataNode on node-slave1.example.com, according to the configuration in the slaves config file.

• Check that every process is running with the jps command on each node. You should get on node-master.example.com (PID will be different):

  and on node-slave1.example.com:

Hdfs has been Configured Successfully

Note: If datanode and namenode has not started, look into hdfs logs to debug: $HOME/hadoop/logs/

Create HDFS users

• To create users for hdfs (regprocessor, prereg, idrepo), run this command:

Note: Configure the user in module specific properties file (ex- pre-registration-qa.properties) as mosip.kernel.fsadapter.hdfs.user-name=prereg**

• Create a directory and give permission for each user

Enabling configured port through firewall in each machine in cluster

Note: If different port has been configured , enable those port.

Securing HDFS

Install Kerberos

Before Installing Kerberos Install the JCE Policy File

Kerberos

Kerberos server(KDC) and the client needs to be installed. Install the client on both master and slave nodes. KDC server will be installed on the master node.

• To install packages for a Kerberos server:
• To install packages for a Kerberos client:

Configuring the Master KDC Server

• Edit the /etc/krb5.conf: Configuration snippets may be placed in this directory (includedir /etc/krb5.conf.d/) as well,

Note: Place this krb5.conf file in /kernel/kernel-fsadapter-hdfs/src/main/resources mosip.kernel.fsadapter.hdfs.krb-file=classpath:krb5.conf Or if kept outside resource then give absolute path mosip.kernel.fsadapter.hdfs.krb-file=file:/opt/kdc/krb5.conf

• Edit /var/kerberos/krb5kdc/kdc.conf
• Create the database using the kdb5_util utility.
• Edit the /var/kerberos/krb5kdc/kadm5.acl
• Create the first principal using kadmin.local at the KDC terminal:
• Start Kerberos using the following commands:

To set up the KDC server to auto-start on boot. ``` RHEL/CentOS/Oracle Linux 6

• Verify that the KDC is issuing tickets. First, run kinit to obtain a ticket and store it in a credential cache file.

  Next, use klist to view the list of credentials in the cache.

  Use kdestroy to destroy the cache and the credentials it contains.

Create and Deploy the Kerberos Principals and Keytab files

If you have root access to the KDC machine, use kadmin.local, else use kadmin. To start kadmin.local (on the KDC machine), run this command: sudo kadmin.local

To create the Kerberos principals

Do the following steps for masternode.

• In the kadmin.local or kadmin shell, create the hadoop principal. This principal is used for the NameNode, Secondary NameNode, and DataNodes.
• Create the HTTP principal.
• Create principal for all user of hdfs (regprocessor, prereg, idrepo)

To create the Kerberos keytab files

Create the hdfs keytab file that will contain the hdfs principal and HTTP principal. This keytab file is used for the NameNode, Secondary NameNode, and DataNodes. kadmin: xst -norandkey -k hadoop.keytab hadoop/admin HTTP/admin Use klist to display the keytab file entries; a correctly-created hdfs keytab file should look something like this: $ klist -k -e -t hadoop.keytab Keytab name: FILE:hadoop.keytab KVNO Timestamp Principal ---- ------------------- ------------------------------------------------------ 1 02/11/2019 08:53:51 hadoop/admin@NODE-MASTER.EXAMPLE.COM (aes256-cts-hmac-sha1-96) 1 02/11/2019 08:53:51 hadoop/admin@NODE-MASTER.EXAMPLE.COM (aes128-cts-hmac-sha1-96) 1 02/11/2019 08:53:51 hadoop/admin@NODE-MASTER.EXAMPLE.COM (des3-cbc-sha1) 1 02/11/2019 08:53:51 hadoop/admin@NODE-MASTER.EXAMPLE.COM (arcfour-hmac) 1 02/11/2019 08:53:51 hadoop/admin@NODE-MASTER.EXAMPLE.COM (camellia256-cts-cmac) 1 02/11/2019 08:53:51 hadoop/admin@NODE-MASTER.EXAMPLE.COM (camellia128-cts-cmac) 1 02/11/2019 08:53:51 hadoop/admin@NODE-MASTER.EXAMPLE.COM (des-hmac-sha1) 1 02/11/2019 08:53:51 hadoop/admin@NODE-MASTER.EXAMPLE.COM (des-cbc-md5) 1 02/11/2019 08:53:51 HTTP/admin@NODE-MASTER.EXAMPLE.COM (aes256-cts-hmac-sha1-96) 1 02/11/2019 08:53:51 HTTP/admin@NODE-MASTER.EXAMPLE.COM (aes128-cts-hmac-sha1-96) 1 02/11/2019 08:53:51 HTTP/admin@NODE-MASTER.EXAMPLE.COM (des3-cbc-sha1) 1 02/11/2019 08:53:51 HTTP/admin@NODE-MASTER.EXAMPLE.COM (arcfour-hmac) 1 02/11/2019 08:53:51 HTTP/admin@NODE-MASTER.EXAMPLE.COM (camellia256-cts-cmac) 1 02/11/2019 08:53:51 HTTP/admin@NODE-MASTER.EXAMPLE.COM (camellia128-cts-cmac) 1 02/11/2019 08:53:51 HTTP/admin@NODE-MASTER.EXAMPLE.COM (des-hmac-sha1) 1 02/11/2019 08:53:51 HTTP/admin@NODE-MASTER.EXAMPLE.COM (des-cbc-md5)

Creating keytab [mosip.keytab] file for application to authenticate with HDFS cluster

To view the principals in keytab

To deploy the Kerberos keytab file

On every node in the cluster, copy or move the keytab file to a directory that Hadoop can access, such as /home/hadoop/hadoop/etc/hadoop/hadoop.keytab.

To configure Kernel HDFS Adapter

Place this mosip.keytab file in /kernel/kernel-fsadapter-hdfs/src/main/resources and update the application properties for mosip.kernel.fsadapter.hdfs.keytab-file=classpath:mosip.keytab mosip.kernel.fsadapter.hdfs.authentication-enabled=true mosip.kernel.fsadapter.hdfs.kdc-domain=NODE-MASTER.EXAMPLE.COM mosip.kernel.fsadapter.hdfs.name-node-url=hdfs://host-ip:port

Note: Configure the user in module specific properties file (example: pre-registration-qa.properties as mosip.kernel.fsadapter.hdfs.user-name=prereg).

Enable security in HDFS

To enable security in hdfs, you must stop all Hadoop daemons in your cluster and then change some configuration properties. sh hadoop/sbin/stop-dfs.sh

Enable Hadoop Security

• To enable Hadoop security, add the following properties to the ~/hadoop/etc/hadoop/core-site.xml file on every machine in the cluster:
• Add the following properties to the ~/hadoop/etc/hadoop/hdfs-site.xml file on every machine in the cluster.

Configuring HTTPS in HDFS

Generating the key and certificate

The first step of deploying HTTPS is to generate the key and the certificate for each machine in the cluster. You can use Java’s keytool utility to accomplish this task: Ensure that firstname/lastname OR common name (CN) matches exactly with the fully qualified domain name (e.g. node-master.example.com) of the server. keytool -genkey -alias localhost -keyalg RSA -keysize 2048 -keystore keystore.jks

Creating your own CA

We use openssl to generate a new CA certificate: openssl req -new -x509 -keyout ca-key.cer -out ca-cert.cer -days 365 The next step is to add the generated CA to the clients’ truststore so that the clients can trust this CA: keytool -keystore truststore.jks -alias CARoot -import -file ca-cert.cer

Signing the certificate:

The next step is to sign all certificates generated with the CA. First, you need to export the certificate from the keystore: keytool -keystore keystore.jks -alias localhost -certreq -file cert-file.cer Then sign it with the CA: openssl x509 -req -CA ca-cert.cer -CAkey ca-key.cer -in cert-file.cer -out cert-signed.cer -days 365 -CAcreateserial -passin pass:12345678 Finally, you need to import both the certificate of the CA and the signed certificate into the keystore keytool -keystore keystore.jks -alias CARoot -import -file ca-cert.cer keytool -keystore keystore.jks -alias localhost -import -file cert-signed.cer

Configuring HDFS

Change the ssl-server.xml and ssl-client.xml on all nodes to tell HDFS about the keystore and the truststore

• Edit ~/hadoop/etc/hadoop/ssl-server.xml
• Edit ~/hadoop/etc/hadoop/ssl-client.xml

After restarting the HDFS daemons (NameNode, DataNode and JournalNode), you should have successfully deployed HTTPS in your HDFS cluster.

Often simply Postgres, is an object-relational database management system (ORDBMS) with an emphasis on extensibility and standards compliance. It can handle workloads ranging from small single-machine applications to large Internet-facing applications (or for data warehousing) with many concurrent users Postgresql Prerequisites On a Linux or Mac system, you must have superuser privileges to perform a PostgreSQL installation. To perform an installation on a Windows system, you must have administrator privileges.

Steps to install Postgresql in RHEL-7.5

Download and install PostgreSQL.

```
$ sudo yum install https://download.postgresql.org/pub/repos/yum/10/redhat/rhel-7-x86_64/pgdg-redhat10-10-2.noarch.rpm 
$ sudo  yum-config-manager --disable pgdg95
```

Check the postgresql packages

```
$ sudo yum update 
$ sudo yum list postgresql*
```

Installation command

```
$ sudo yum install postgresql10 postgresql10-server
$ sudo /usr/pgsql-10/bin/postgresql-10-setup initdb
$ sudo systemctl enable postgresql-10
```

Postgresql service stop/start/restart command

```
$ sudo systemctl start postgresql-10
$ sudo systemctl status postgresql-10 
$ sudo systemctl stop postgresql-10
```

To changing default port 5432 to 9001 and connection + buffer size we need to edit the postgresql.conf file from below path PostgreSQL is running on default port 5432. you decide to change the default port, please ensure that your new port number does not conflict with any services running on that port.

Steps to change the default port

Open the file and modify the below changes

```
$ sudo vi /var/lib/pgsql/10/data/postgresql.conf
```
listen_addresses = '*'   (changed to * instead of local host )
port = 9001       ( uncomment port=5432 and change the port number 
Open the port 9001 from the VM 

Use below command to open the port 9001 from RHEL 7.5 VM

```
$ sudo firewall-cmd --zone=public --add-port=9001/tcp --permanent
$ sudo firewall-cmd --reload
```

To increase the buffer size and number of postgreSql connection same fine modify the below changes also

```
$ sudo vi /var/lib/pgsql/10/data/postgresql.conf 

unix_socket_directories = '/var/run/postgresql, /tmp' max_connections = 1000
shared_buffers = 2GB
```

Start the service

```
$ sudo systemctl start postgresql-10
```

To change the default password

Login to postgrsql

```
$ sudo su postgres
bash-4.2$ psql -p 9001
postgres=# \password postgres
Enter new password:
Enter it again:
postgres=# \q
```

Restart the service:

```
$ sudo systemctl restart postgresql-10
```

It will ask new password to login to postgresql

Example for sourcing the sql file form command line $ psql --username=postgres --host=<server ip> --port=9001 --dbname=postgres

Open the file

```
$ sudo vim /var/lib/pgsql/10/data/pg_hba.conf
```

** Default lines are present in pg_hab.conf file**

** Modify with below changes in file /var/lib/pgsql/10/data/pg_hba.conf**

$ sudo systemctl status postgresql-10

Reference link: https://www.tecmint.com/install-postgresql-on-centos-rhel-fedora

HSM stands for Hardware Security Module and is an incredibly secure physical device specifically designed and used for crypto processing and strong authentication. It can encrypt, decrypt, create, store and manage digital keys, and be used for signing and authentication. The purpose is to safeguard and protect keys.

MOSIP highly recommends the following specifications for HSM:

1. Must support cryptographic offloading and acceleration.

2. Should provide Authenticated multi-role access control.

3. Must have strong separation of administration and operator roles.

4. Capability to support client authentication.

5. Must have secure key wrapping, backup, replication and recovery.

6. Must support 2048, 4096 bit RSA Private Keys, 256 bit AES keys on FIPS 140-2 Level 3 Certified Memory of Cryptographic Module.

7. Must support at least 10000+ 2048 RSA Private Keys on FIPS 140-2 Level 3 Certified Memory of Cryptographic Module.

8. Must support clustering and load balancing.

9. Should support cryptographic separation of application keys using logical Partitions.

10. Must support M of N multi-factor authentication.

11. PKCS#11, OpenSSL, Java (JCE), Microsoft CAPI and CNG.

12. Minimum Dual Gigabit Ethernet ports (to service two network segments) and 10G Fibre port should be available.

13. Asymmetric public key algorithms: RSA, DiffieHellman, DSA, KCDSA, ECDSA, ECDH, ECIES.

14. Symmetric algorithms: AES, ARIA, CAST, HMAC, SEED, Triple DES, DUKPT, BIP32.

15. Hash/message digest: SHA-1, SHA-2 (224, 256, 384, 512 bit).

16. Full Suite B implementation with fully licensed ECC including Brainpool, custom curves and safe curves.

17. Safety and environmental compliance

18. Compliance to UL, CE, FCC part 15 class B.

19. Compliance to RoHS2, WEEE.

20. Management and monitoring

21. Support Remote Administration —including adding applications, updating firmware, and checking the status— from NoC.

22. Syslog diagnostics support.

23. Command line interface (CLI)/graphical user interface (GUI).

24. Support SNMP monitoring agent.

25. Physical characteristics

26. Standard 1U 19in. rack mount with integrated PIN ENTRY Device.

27. Performance

28. RSA 2048 Signing performance – 10000 per second.

29. RSA 2048 Key generation performance – 10+ per second.

30. RSA 2048 encryption/decryption performance - 20000+.

31. RSA 4096 Signing performance - 5000 per second.

32. RSA 4096 Key generation performance - 2+ per second.

33. RSA 4096 encryption/decryption performance - 20000+.

34. Should have the ability to backup keys, replicate keys, store keys in offline locker facilities for DR. The total capacity is inline with the total number of keys prescribed.

35. Clustering minimum of 20 HSMs.

36. Less than 30 seconds for key replication across the cluster.

37. A minimum of 30 logical partitions and their license should be included in the cost.

The hardware compute and storage requirements for MOSIP core platform are estimated as below.

Production

Compute

Compute hardware estimates for a production deployment:

* Average throughput

** VCPU: Virtual CPU

We estimate 30% (approx) additional compute capacitiy for administration, monitoring and maintenance. This may be optimized by the System Integrator.

Notes

1. High availability is taken into consideration with assumed replication factor of 2 per service pod/docker

2. The above estimates do not include compute servers needed for

   1. Database

   2. HDFS/CEPH

   3. Bio SDK

   4. HSM

   5. ABIS

   6. Virus scan

   7. Load balancers

   8. External IAM

   9. Disaster recovery

Storage

Storage estimates for production deployment:

Database and HDFS/CEPH

MOSIP Storage Requirement Calculator XLS

Appication and system logs

• Application logs

The above estimates are approximate, and may inflate if, for example, there are too many exception traces.

The logs may be compressed and archived after a week or so. The compression ratio achieved with tar+gz utility is 15-20.

• System logs

To be estimated by System Integrator according to the deployment

Dev, QA, Staging, Preprod

Additional compute and storage is needed for the following setups.

* To be decided by the country/System Integrator.

Prerequisites

Install Java

Install java (java-8-openjdk) in all the machines in the cluster and setup the JAVA_HOME environment variable for the same.

sudo yum install java-1.8.0-openjdk-devel

Get your Java installation path.

update-alternatives --display java

Edit ~/bashrc.sh:

Export JAVA_HOME={path-tojava} with your actual java installation path. For example on a Debian with open-jdk-8:

export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.191.b12-1.el7_6.x86_64/jre

Download & install keycloak

Download and unzip Keycloak

sudo wget "https://downloads.jboss.org/keycloak/6.0.1/keycloak-6.0.1.tar.gz" 
sudo tar xzf keycloak-6.0.1.tar.gz

Install a database supported by keycloak

We have installed postgres as the database for keycloak; you can use any database supported by Keycloak.

Documentation for Keycloak Database Setup is available here.

Install Postgres in your VM. Guide to install PostgreSQL is available here.

Within the …​/modules/ directory of your Keycloak distribution, you need to create a directory structure to hold your module definition. The convention is use the Java package name of the JDBC driver for the name of the directory structure. For PostgreSQL, create the directory org/postgresql/main. Copy your database driver JAR into this directory and create an empty module.xml file within it too.

Module Directory

After you have done this, open up the module.xml file and create the following XML:

Module XML

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.3" name="org.postgresql">
    <resources>
        <resource-root path="postgresql-9.4.1212.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
    </dependencies>
</module>

The module name should match the directory structure of your module. So, org/postgresql maps to org.postgresql. The resource-root path attribute should specify the JAR filename of the driver. The rest are just the normal dependencies that any JDBC driver JAR would have.

Create a service to start Keycloak

sudo cat > /etc/systemd/system/keycloak.service <<EOF

[Unit]
Description=Jboss Application Server
After=network.target

[Service]
Type=idle
User=root
Group=root
ExecStart=/opt/keycloak-6.0.1/bin/standalone.sh -b 0.0.0.0
TimeoutStartSec=600
TimeoutStopSec=600

[Install]
WantedBy=multi-user.target

Enable SSL for Keycloak server

To enable SSL we need a certificate which here in example we will use Lets encrypt.

Follow the steps in this link to create a certificate for your domain.

We will create a keystore in which we will store certificate chain and private key and give them an alias

openssl pkcs12 -export -inkey{{private key pem path}} -in {{certificate pem path}} -password pass:{{keystore password}} -out {{output keystore name}} -name {{alias}}

Configure standalone xml

• Go to {{keycloak folder}}/standalone/configuration

• Open Standalone.xml and make following changes

  • Add a driver for postgres(Or your database)

    Copy

    <driver  name="postgresql"  module="org.postgresql">
    <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
    </driver>

  • Change the datasource properties

    Copy

    <datasource  jndi-name="java:jboss/datasources/KeycloakDS"  pool-name="KeycloakDS"  enabled="true"  use-java-context="true">
    <connection-url>jdbc:postgresql://<Host>:<Port>/{{database_name}}</connection-url>
    <driver>{{drivername}}</driver>
    <pool>
    <max-pool-size>pool size</max-pool-size>
    </pool>
    <security>
    <user-name>database username</user-name>
    <password>database password</password>
    </security>
    </datasource>

  • Register the datasource While registering change the schema name if you want.

    Copy

    <spi  name="connectionsJpa">
    <provider  name="default"  enabled="true">
    <properties>
    <property  name="dataSource"  value="java:jboss/datasources/KeycloakDS"/>
    <property  name="initializeEmpty"  value="true"/>
    <property  name="migrationStrategy"  value="update"/>
    <property  name="migrationExport"  value="${jboss.home.dir}/keycloak-database-update.sql"/>
    <property  name="schema"  value="public"/>
    </properties>
    </provider>

  • Change network configuration

    • Inet address for both public and management profile to access it remotely

      Copy

      <interfaces>
      <interface  name="management">
      <inet-address value="0.0.0.0"/>
      </interface>
      <interface  name="public">
      <inet-address value="0.0.0.0"/>
      </interface>
      </interfaces>

    • Default ports from 8080 -> 80 and 8443 -> 443 to not give ports at time of accessing Keycloak

      Copy

      <socket-binding  name="http"  port="${jboss.http.port:80}"/>
      <socket-binding  name="https"  port="${jboss.https.port:443}"/>

  • Adding a SSL certificate to Keycloak Here we will give the keystore we created to keycloak

    Copy

    <ssl>
    <keystore  path="your key store pass relative to the next property"  relative-to="jboss.server.config.dir"  keystore-password="yourpassword"  alias="your alias"/>
    </ssl>

Add keycloak admin user

Add Keycload admin user from keycloak bin directory run

./add-user-keycloak.sh -u {{username}} -p {{password}}

Keycloak server start

 systemctl start keycloak

Configure keycloak

• Create a new Realm (eg. mosip).

• Create clients for every module (i.e. ida, pre-registration, registration-processor, registration-client, auth, resident, mosip-client).

• Enable authorization and service account for every client and provide valid redirect uri. These clients will be used by all modules to get client tokens.

Configure User Federation

For this example we will be configuring LDAP as user federation

• Go to "User Federation".

• Create a new User Federation for LDAP.

• Make Edit Mode Writable.

• Configure field based on your LDAP(There are many vendors for ldap you can connect to any ldap vendor based on configurations).

• Go to Mappers and Create mappers for each field you want keycloak to take from LDAP.

isActive : user-attribute-ldap-mapper
username : user-attribute-ldap-mapper
rid : user-attribute-ldap-mapper
creation date : user-attribute-ldap-mapper
roles : role-ldap-mapper
last name : user-attribute-ldap-mapper
userPassword : user-attribute-ldap-mapper
mobile : user-attribute-ldap-mapper
dob : user-attribute-ldap-mapper
first name : user-attribute-ldap-mapper
email : user-attribute-ldap-mapper

• Sync Users and Roles from LDAP .

• Create INDIVIDUAL, RESIDENT Role from Keycloak in Realm Roles

• Assign Roles from LDAP and Keycloak to All Clients

IDA => ID_AUTHENTICATION
Registration-Processor => REGISTRATION_PROCESSOR
Registration-Client => 	REGISTRATION_ADMIN
						REGISTRATION_SUPERVISOR
						REGISTRATION_OFFICER
						REGISTRATION_OPERATOR
Resident => RESIDENT
Pre-Registration => PRE_REGISTRATION
					INDIVIDUAL
Auth => AUTH

Access token expiration action

SSL enable at keycloak

Update of configuration for keycloak

Global configuration

auth.server.validate.url=${mosip.base.url}/v1/authmanager/authorize/admin/validateToken
auth.server.admin.validate.url=${mosip.base.url}/v1/authmanager/authorize/admin/validateToken

Kernel configuration

mosip.keycloak.base-url=https://<keycloak.domain>
mosip.kernel.realm-id=<Mosip realm id> (EX mosip, should always be in lowercase)
mosip.kernel.open-id-url=${mosip.keycloak.base-url}/auth/realms/{realmId}/protocol/openid-connect/
mosip.kernel.base-url=${mosip.keycloak.base-url}/auth/realms/{realmId}
mosip.kernel.admin-url=${mosip.keycloak.base-url}/auth/admin/
mosip.kernel.roles-url=realms/mosip/roles
mosip.kernel.users-url=realms/mosip/users
mosip.kernel.role-user-mapping-url=/{userId}/role-mappings/realm

`#Domain should be updated
mosip.authmanager.base-url=https://<domain>/v1/authmanager

mosip.keycloak.authorization_endpoint=${mosip.keycloak.base-url}/auth/realms/mosip/protocol/openid-connect/auth
mosip.keycloak.token_endpoint=${mosip.keycloak.base-url}/auth/realms/mosip/protocol/openid-connect/token
mosip.admin.login_flow.name=authorization_code
mosip.admin.login_flow.response_type=code
mosip.admin.login_flow.scope=cls
mosip.admin.clientid=mosip-client
mosip.admin.clientsecret=<client secret of mosip client>
mosip.admin.redirecturi=${mosip.authmanager.base-url}/login-redirect/
mosip.admin_realm_id=<Mosip realm id> (EX mosip)

mosip.master.realm-id=master

`#Go to Mosip realm -> Go to Roles -> select INDIVIDUAL ROLE you will find hyperlink  in tab will have a id after roles-> /realms/mosip/roles/[e3bb3344-6445-4f6f-9e33-d5ec0d231327]
mosip.admin.individual_role_id=<role if of individual>

mosip.admin.pre-reg_user_password=mosip
db_3_DS.keycloak.ipaddress=<keycloak db url>
db_3_DS.keycloak.port=<keycloak db port>
db_3_DS.keycloak.username=<keycloak db username>
db_3_DS.keycloak.password=<keycloak db password>
db_3_DS.keycloak.driverClassName=<keycloak db driver class name>

mosip.keycloak.admin.client.id=admin-cli

`#First user we create when we started keycloak
mosip.keycloak.admin.user.id=<admin user name>

`#First user we create when we started keycloak
mosip.keycloak.admin.secret.key=<admin user password>

mosip.kernel.auth.client.id=<Auth Client id>
mosip.kernel.auth.secret.key=<Auth Secret id>

mosip.kernel.ida.client.id=<Ida Client id>
mosip.kernel.ida.secret.key=<Ida Secret id>

Pre-registration configuration

clientId=<pre-registration client id>
secretKey=<pre-registration-secret>
mosip.batch.token.authmanager.userName=<pre-registration client id>
mosip.batch.token.authmanager.password=<pre-registration-client-secret>

Registration processor configuration

token.request.clientId=<registration-processor-client-id>
token.request.secretKey=<registration-processor-client-secret>
KEYBASEDTOKENAPI=${mosip.base.url}/v1/authmanager/authenticate/clientidsecretkey
TOKENVALIDATE=${mosip.base.url}/v1/authmanager/authorize/admin/validateToken

ID authentication configuration

auth-token-generator.rest.uri=${mosip.base.url}/v1/authmanager/authenticate/clientidsecretkey
auth-token-validator.rest.uri=${mosip.base.url}/v1/authmanager/authorize/admin/validateToken
auth-token-generator.rest.clientId=<ida-client-id>
auth-token-generator.rest.secretKey=<ida-secret-key>
auth-token-generator.rest.appId=ida

Registration client configuration

AUTH_CLIENT_ID=<registration-client-id>
AUTH_SECRET_KEY=<registration-client-secret>

Resident services configuration

`#Token generation app id
resident.clientId=<resident-client-id>
resident.secretKey=<resident-client-secret>
KERNELAUTHMANAGER=${mosip.base.url}/v1/authmanager/authenticate/clientidsecretkey

MOSIP offers high configurability to customise and deploy for a country. Many components are available out of the box. However, for a specific deployment certain customisations and additions may be needed as follows:

1. ID Object

   • Definition

   • Schema

   • Schema and field custom validations on Reg Client and Reg Processor. (Ref validator)

2. Languages

   • Defining primary and secondary languages

   • Transliteration libraries integration in Reg Client

   • Messaging templates (master data and configuration files)

3. Master Data: Country specific master data

4. Adding/modifying Reg Processor flow

   • Adding a new stage (e.g. fetch data from CRVS system). (Camel configurations)

   • Remove or re-arrange the stages

   • Demographic dedup logic

5. Configurations

6. Registration Client App

   • Fields as per ID Object

   • Labels in preferred languages

   • Field validations

   • Screen flow changes

   • Integration with MDS

7. Residents Portal: UI implementation

8. Admin portal: UI modifications (if needed)

9. Integration with external components

   • Virus scanner

   • ABIS

   • Biometric SDKs (in Registration Client, Registration Processor & ID Authentication)

   • Manual Adjudication

   • IAM (OAuth 2.0 compliant)

   • HSM

   • Postal service

   • Email/SMS gateway

FAQ

What's there in MOSIP and what's not

This document defines the public and private services of MOSIP.

Public Services: MOSIP services available to the general public and can be accessed by UI or user token.

Private Services: MOSIP services available for service to service call and should be accessed by service token or restricted user.

Overview

The Sandbox is a safe environment isolated from your PC's underlying environment. You may use the sandbox to execute files without having to worry about malicious files or unstable programs impacting data on the system.

System Requirement

This section describes handy information that is useful to know when operating the Sandbox Installer which is tested under mentioned configuration.

*vCPU: Virtual CPU

** Console has all the persistent data stored under /srv/nfs. Recommended storage here is SSD or any other high IOPS disk for better performance

Introduction

The Multi-VM Sandbox Installer is a fully automated deplorer that incorporates all MOSIP modules into a virtual machine cluster that can be either cloud or on premise.

The sandbox can be used for development and testing, while the Ansible scripts run MOSIP on a multi-virtual machine (VM) setup.

Caution - The sandbox is not intended for use by serious pilots or for production purposes. Also, do not run the sandbox with any confidential data.

Minibox

In Minibox, note that for any form of load or multiple pod replication scenarios, this may not be sufficient. It is possible, however, to enable the feature to bring up MOSIP modules with lesser VMs as below:

Precondition

Terraform is a tool to securely and efficiently develop, edit, and update infrastructure. Using Terraform scripts available in _terraform/._the initial installation stage is achieved. AWS scripts are being used and maintained at present.

It is strongly recommended that the scripts be analyzed in depth before running them.

Virtual Machines (VMs) Setup

Before, MOSIP modules installation process that runs on a preset time or when a predefined condition, need to have VMs set up on all Machines. The user must ensure if the CentOS 7.8 OS is installed on all the machines:

1. Create user 'mosipuser' on console machine with password-less sudo su

2. The hostname must match hostnames in hosts.ini on all machines. Set the same with

   Copy

   $ sudo hostnamectl set-hostname <hostname>

3. Enable Internet access on all machines

4. Disable firewalld on all machines

5. Exchange ssh keys between console machines and K8s cluster machines so that ssh is password-less from console machines:

   Copy

   $[mosipuser@console.sb] ssh root@<any K8s node>
   $[mosipuser@console.sb] ssh mosipuser@console.sb

6. Make the console machine available via a public domain name (e.g. sandbox.mycompany.com)

   (When you do not intend to access the sandbox externally, this step can be skipped)

7. Ensure the date/time is in UTC on all machines

8. Open ports 80, 443, 30090 (postgres), 30616 (activemq), 53 (coredns) on console machine for external access

9. Make sure your firewall doesn't block the UDP ports (s)

Software Prerequisites

To ensure proper installation, install these pre-requisites manually:

• Git

• Git Clone

• Ansible

On the Installation Options, click git to install on your machine:

$ sudo yum install -y git

In User Home Directory, select Git Clone and switch to appropriate branch:

$ cd ~/
$ git clone https://github.com/mosip/mosip-infra
$ cd mosip-infra
$ git checkout 1.1.2
$ cd mosip-infra/deployment/sandbox-v2

Install Ansible and create shortcuts:

$ ./preinstall.sh
$ source ~/.bashrc

Sandbox Architectural View

Installing MOSIP

This section helps you to plan an installation of MOSIP suited to your environment. Before installing MOSIP, it is recommended that the scripts be analyzed in depth before running them.

Site Settings

• Suited to your configuration, update hosts.ini. Make sure your configuration matches the system names and IP addresses

• In group_vars/all.yml change sandbox_domain_name to domain name of the console machine

• By default, installation scripts will try to fetch Letsencrypt's new SSL certificate for the above domain. If you already have the same, however, then set the following variables in the file group group_vars/all.yml:

ssl:
get_certificate: false
email: ''
certificate: <certificate dir>
certificate_key: <private key path>

Network Interface

It is the interconnection between a computer and a public or private network. If it is other than “eth0” by your cluster machines, update it to group_vars/k8s.yml

network_interface: "eth0"

Ansible Vault

In the Ansible vault _secrets.yml_file, all the secrets (passwords) used in automation are stored. To access the file, the default password is 'foo'. Changing this password with the following command is recommended:

$ av rekey secrets.yml

The contents of secrets.yml can be viewed and edited based on following command:

$ av view secrets.yml
$ av edit secrets.yml

Install MOSIP

When this equipment is connected to your machine it allows you to install MOSIP modules using command:

$ an site.yml

If a message prompting you for password, enter default vault password "foo" to proceed installation.

MOSIP Configuration

This section provides the following major sections to describe how to configure and verify the proper interface. The sandbox installs with default general configuration. To configure MOSIP differently, refer to the following sections:

• DNS

• Local docker registry

• Private dockers

• Sandbox access

• Secrets

• Config server

• Pre-Reg captcha

• OTP

• Master data

• Pod replication

• Taints

• TPM

• Pre-Registration Schema

• Registration client

Domain Name System (DNS)

DNS translates human readable domain names to machine readable IP addresses. A private DNS (CoreDNS) is mounted on the console machine by default, and /etc/resolv.conf refers to this DNS on all machines.

However, if you want to use DNS cloud providers (like Route53 on AWS), disable the installation of a private DNS by setting the following flag:

group_vars/all.yml:
    coredns:
      enabled: false  # Disable to use Cloud provided DNS

Ensure your DNS routing is taken care of by your cloud deployment. Uncomment the Route53 code for AWS in the scripts given in the:

terraform/aws/sandbox

The corends.yml ``playbook configures the CoreDNS and updates the /etc/resolv.conf file for all devices. If a system needs to be restarted, re-run the playbook to restore /etc/resolv.conf.

Local Docker Registry

This part contains information about hosting your own registry using the Local Docker Registry.

Local Registry on Console

Instead of using the default Docker Hub, you may run a local Docker registry. This is particularly useful when the Kubernetes cluster is sealed for protection on the Internet. With this sandbox, a sample Docker registry implementation is available, and you can run the same by triggering the following in group_vars/all.yml.

    docker:
      local_registry:
        enabled: true
        image: 'registry:2'
        name: 'local-registry'
        port: 5000

Notice that this register is running on the computer on the console and can be accessed as console.sb:5000. Control is through http and not through https.

Ensure that in this registry you pull all the appropriate Dockers and update versions.yml.

Caution: If you delete/reset this registry or restart the console computer, all the registry contents will be lost and the Dockers will have to be removed again.

Additional Local Registries:

If you wish to have additional local registries for Dockers, then list them here:

    docker:
      registries:
        - '{{groups.console[0]}}:{{local_docker_registry.port}}'   # Docker registry running on console

The list here is necessary to ensure that http access from cluster machines is allowed for the above registries.

Private Dockers

When you set up a private registry, you assign a server to communicate with Docker Hub over the internet. If you are pulling Dockers in Docker Hub from the private registry, then provide secrets.yml with the Docker Hub credentials and set the following flag in:

group_vars/all.yml

Update with versions.yml your Dockers versions.

Sandbox Access

When installing the default Sandbox, you must have a public domain name, so that the domain name refers to the console computer. However, if you want to access your internal network's Sandbox (for example via VPN), set the following in group_vars/all.yml:

    sandbox_domain_name: '{{inventory_hostname}}'
    site:
      sandbox_public_url: 'https://{{sandbox_domain_name}}'
      ssl:
        ca: 'selfsigned'   # The ca to be used in this deployment.

A self-signed certificate is created and the sandbox access URL is https://{{inventory hostname}}'

Secrets

All secrets are stored in secrets.yml. Edit the file and change all of the passwords for a secure Sandbox. For creation and testing, defaults will be used, but be aware that the sandbox will not be secure with defaults. In order to edit secrets.yml.

$ av edit secrets.yml

If you update PostGres passwords, you will need to update their ciphers in the property files. See the section below on Config Server. To be able to find out the text password, all the passwords used in. properties were added to secrets.yml- some of them for purely informational purposes.

Caution : Make sure that secrets.yml is updated when you change any password in. properties.

Config Server

Config server is one of the more popular centralized configuration servers used in a micro service-based application. For all modules, configurations are defined through property files located in the GitHub repository. For example, for this sandbox, the properties are located within the sandbox folder at https://github.com/mosip/mosip-config.

You can have a repository of your own with a folder containing files for properties. On GitHub, the repo will be private. In group vars/all.yml, configure the following parameters as below (example):

config_repo:
  git_repo_uri: https://github.com/mosip/mosip-config
  version: 1.1.2
  private: false
  username: <your github username>
  search_folders: sandbox
  local_git_repo:
    enabled: false

If private: true, then, in group vars/all.yml, update your GitHub username as above. Please change the password to secrets.yml:

config_repo:
    password: {YOUR GITHUB PASSWORD}

The repo is cloned to the NFS mounted folder if local git repo is allowed, and the config server pulls the properties locally. This option is useful if the sandbox is secured without access to the Internet. You should search git-in locally for any changes. Remember, however, that you will have to push them manually if you want the changes to be reflects in the parent GitHub repo. When making improvements to the configuration repo, there is no need to restart the config-server pod.

If you have updated the default passwords in secrets.yml, create these password ciphers and update the changed password property files. After the config server is up, the ciphers can be created from the console machine using the following curl command:

$  curl http://mzworker0.sb:30080/config/encrypt -d  <string to be encrypted>

The above command connects via input to the Config server pod of the MZ cluster. You may also use the script to encrypt all the secrets at once by the following methods:

Context:

Several secrets are required in Ansible's secrets.yml in the config server property files. We use config server encryption to encrypt the secrets in order to prevent explicit text secrets in properties using the following command:

curl http://mzworker0.sb:30080/config/encrypt -d  <string to be encrypted>

The script here converts all secrets in secrets.yml using above command implemented in Python.

Prerequisites:

• Install required modules using

  Copy

  $ ./preinstall.sh

• Ensure config server is running

  Copy

  Config

• Set the server URL in config.py

• If the URL has an HTTPS certificate and the SSL server is self-signed, set

  Copy

    ssl verify=False

• Run the following command:

  Copy

  $ ./convert.py {secrets_file_path}

  In this sandbox secrets_file_path is /home/mosipuser/mosip-infra/deployment/sandbox-v2/secrets.yml

  Output is saved in out.yaml.

Pre-Reg Captcha

Captcha protects your website from fraud and abuse. It uses an advanced risk analysis engine and adaptive challenges to keep malicious software.

• Get Captcha for the sandbox domain from "Google Re-captcha Admin" if you would like to allow Captcha for Pre-Reg UI. Get reCAPTCHA v2 keys for "I'm not a robot"

• Set Captcha as:

  Copy

  google.recaptcha.site.key=sitekey
  google.recaptcha.secret.key=secret

OTP Setting

• As below, to receive OTP (one-time password) over email and SMS set properties:

  • SMS

    • File:

      kernel-mz.properties

• Properties:

  kernel.sms

• Email

  • File:

    kernel-mz.properties

• Properties

  Copy

  mosip.kernel.notification.email.from=emailfrom
  spring.mail.host=smtphost
  spring.mail.username=username
  spring.mail.password=password

• You may want to run MOSIP in Proxy OTP mode if you do not have access to Email and SMS gateways, in that case you can skip Proxy OTP Settings.

• To run MOSIP in Proxy OTP mode set the following:

  Copy

    Proxy:
        File: application-mz.properties
        Properites:
            mosip.kernel.sms.proxy-sms=true
            mosip.kernel.auth.proxy-otp=true
            mosip.kernel.auth.proxy-email=true

  Note : The default OTP is set to 111111.

Master Data

Before you start installing the sandbox, load country-specific master data:

• Ensure the Master Data .csv files are available in a folder, say my_dml

• Add the following line in group_vars/all.yml ``-> databases -> mosip_master

  Copy

        mosip_master:
        sql_path: '{{repos.commons.dest}}/db_scripts'
        dml: 'my_dml/'

Pod Replication

For production setups you may want to replicate pods more than the default replication factor of 1. Upgrade podconfig.yml to the same file. A separate production file can be generated and pointed to from group vars/all.yml ``--> podconfig file.

Taints

A taint allows a node to refuse pod to be scheduled unless that pod has a matching toleration. Kubernetes offers the functionality of taints to run a pod solely on a node. This is especially useful during performance tests where you would like to assign different nodes to non-MOSIP components.

By default, in the sandbox, taints are not added. The following modules have been provided with provisions to allow taints for:

• Postgres

• Minio

• HDFS

  Set the following in group vars/all.yml to allow taint. EXAMPLE:

  Copy

  postgres:
    ...
    ...
    node_affinity:
        enabled: true # To run postgres on an exclusive node
        node: 'mzworker0.sb' # Hostname**. Run only on this node, and nothing else should run on this node
    taint:
        key: "postgres" # Key for applying taint on node
        value: "only"

  The node here is the machine on which you would like to exclusively run the module.

Ensure the above setting is done before you install the sandbox.

TPM for Reg Client

By default, the sandbox installs a disabled Trusted Platform Module (TPM) Reg Client Downloader.

Reg Client Downloader:

    #Playbook
    to install
    reg-client
    downloader
        #Inputs:
        #kube_config
        #prepare folder on nfs
        -hosts:console
        gather facts:true
        vars:
            reg_prop: '{{reg_client}}'
        roles:
        -{role: reg-client-prep}

Convert helm template to helm values:

    - hosts: console
        vars:
        kube_config: '{{clusters.dmz.kube_config}}'
        install_name: 'reg-client-downloader' 
        helm_chart: '{{charts_root}}/reg-client-downloader'
        is_template: true
        helm_namespace: 'default'
        helm_values: '{{charts_root}}/reg-client-downloader/values.template.j2'
        helm_strings: ''
        roles:
            - {role:  helm}

To enable TPM to use trusted private/public Reg client machine private/public keys, do the following:

1. Update the registered client downloader TPM environment variable:

   Copy

    File: helm/charts/reg-client-downloader/values.template.j2
    Change:
    tpm: "Y"

2. If, before installing the sandbox, you have done the above, then you may skip this step. Otherwise, if the downloader reg client is already running on your sandbox, delete it and restart as follows:

   Copy

   $ helm2 delete reg-client-downloader

   (Wait for all resources to get terminated)

    $ sb
    $ an playbooks/reg-client-downloader.yml

1. Add the name and public key in MOSIP-master/machine-master and MOSIP-master/machine-master table of the registered client machine in DB. Using TPM Utility, you can get your machine's public key

    **TPM Utility**:

Utility to obtain public TPM keys along with the name of the computer

Prerequisites:

Requires Java 11

Build:

    $ mvn clean install

Run:

    $ java -jar tpmutility-0.0.1.jar

(Use jar-with-dependencies to run under target folder)

    Sample Output:
    {"machineName" : "S540-14IWL", "publicKey" : "AAEACwACAHIAIINxl2dEhLP4GpDMjUal1yT9UtduBlILZPKh2hszFGmqABAAFwALCAAAAQABAQDiSa_AdVmDrj-ypFywexe_eSaSsrIoO5Ns0jp7niMu4hiFIwsFT7yWx2aQUQcdX5OjyXjv_XJctGxFcphLXke5fwAoW6BsbeM__1Mlhq9YvdMKlwMjhKcd-7MHHAXPUKGVmMjIJe6kWwUWh7FaZyu5hDymM5MJyYZRxz5fRos_N9ykiBxjWKZK06ZpIYI6Tj9rUNZ6HAdbJH2RmBHuO0knpbXdB-lnnVhvArAt3KWoyH3YzodHeOLJRe_Y8a-p8zRZb5h1tqlcLgshpNAqb-WJgyq2xDb0RJwzuyjjHPmJrDqlBMXHestz-ADRwXQL44iVb84LcuMbQTQ1hGcawtBj", "signingPublicKey": "AAEABAAEAHIAAAAQABQACwgAAAEAAQEAw6CuS_sekZ02Z9_N3zz1fK_V3wm01PBcFM0nURerczjO2wqIxfmXpQQql3_S819nj_MwtkZ8K2ja0MRUJzJrmmbgBreFIGTa7Zhl9uAdzKghAA5hEaXV1YcxIl8m72vZpVX_dgqYzU8dccfRChsA-FxkVe5DCr_aXjVOUHjeXZRhQ1k-d7LzpBPVz-S69rx6W3bbxaZfV25HM93Hfm5P4aarYy0Wt0fJvv-Lmbyt0SIZFOQkYS8coW0-u8OiXm3Jur2Q8pu16q4F-Qpxqym-ACBFIsbkSCngQ_y4zGniK7WnS-dCSVhC-x1NscCq3PyXhoJOjSOdNqUkDX606Ic3SQ", "keyIndex": "BD:11:54:33:44:F9:5A:0B:B5:A6:B3:C1:F7:A8:28:47:0E:AA:20:21:01:16:37:89:D1:9C:8D:EC:96:5D:F5:A6", "signingKeyIndex": "41:EB:7E:7F:4F:A9:24:55:4C:5F:AB:3A:94:81:CF:75:C2:0B:92:DF:9B:89:47:D1:AD:B0:84:7A:F7:65:6A:88"}

Machine Master Table:

The publicKey, signingPublicKey, keyIndex and signingKeyIndex - all of them to be populated in the machine_master table of mosip_master DB.

1. Download the registered client from https://{{sandbox domain name}}/registration-client/1.1.3/reg-client.zip

Configure Pre-Reg for ID Schema

The sandbox comes with its default ID Schema (in Master DB, identity_schema table) and Pre-Reg UI Schema pre-registration-demographic.json. In order to use different schemas, do the following:

1. Ensure new ID Schema is updated in Master DB, identity_schema table

2. Replace mosip-config/sandbox/pre-registration-demographic.json with new Pre-Reg UI Schema

3. Map values in pre-registration-identity-mapping.json to pre-registration-demographic.json as below:

   Copy

         {
     "identity": {
         "name": {
             "value":< id of name field in your demograhic json >
             "isMandatory" : true
         },\
         "proofOfAddress": {
             "value" : < id of proof of address field in your demographic json>
         },
         "postalCode": {
              "value" : <  id of postal code field in your demographic json>
         }
     }
     }

4. Update the following properties in pre-registration-mz.properties preregistartion.identity.name=< identity.name.value (above)> preregistration.notification.nameFormat=< identity.name.value>

5. Restart the Pre-Reg Application service

Registration Client with Mock MDS and Mock SDK

Download Reg Client:

• Download zip file from:

  Copy

  https://{sandbox domain name}/registration-client/1.1.3/reg-client.zip

• Unzip the file and launch registered client by running run.bat

• Reg client will generate public/private keys in the following folder

  Copy

    c:\Users\<user name>\.mosipkeys

• You will need the public key and key index mentioned in readme.txt for the later step to update master DB

Run MDS:

• Run mock MDS as per procedure give here: Mock MDS

• Pickup device details from this repo. You will need them for device info updates in the later step

Add Users in Keycloak:

• Make sure keycloak admin credentials are updated in config.py

• Add users like registration officers and supervisors in csv/keycloak_users.csv with their roles

• Run

  Copy

        **$ ./keycloak_users.py**

  Update Master Data:

• In the master DB DML directory, change the following CSVs. The DMLs are located in the sandbox at /home/mosipuser/mosip-infra/deployment/sandbox-v2/tmp/commons/db-scripts/mosip-master/dml

  • master-device_type.csv

  • master-device_spec.csv

  • master-device_master.csv

  • master-device_master_h.csv

  • master-machine_master.csv

  • master-machine_master_h.csv

  • master-user_detail.csv

  • master-user_detail_h.csv

  • master-zone_user.csv

  • master-zone_user_h.csv

• Run

  Copy

  *update_masterdb.sh

  Example:

  Copy

        $ ./update_masterdb.sh /home/mosipuser/mosip-infra/deployment/sandbox-v2/tmp/commons/db_scripts/mosip_master

• CAUTION : The above will reset entire DB and load it fresh

• You may want to maintain the DML directory separately in your repo

• It is assumed that all other tables of master DB are already updated

Device Provider Partner Registration:

• Update the following CSVs in PMS DML directory. On sandbox the DMLs are located at /home/mosipuser/mosip-infra/deployment/sandbox-v2/tmp/partner-management-services/db_scripts/mosip_pms/dml

  • pms-partner.csv

  • pms-partner_h.csv

  • pms-policy_group.csv

• Run update_pmsdb.sh. Example:

  Copy

    $ ./update_regdevicedb.sh /home/mosipuser/mosip-infra/deployment/sandbox-v2/tmp/commons/db_scripts/mosip_regdevice

• CAUTION*: The above will reset entire DB and load it fresh

• Some example CSVs are located at csv/regdevice

IDA Check:

Disable IDA check in registration-mz.properties:

mosip.registration.onboarduser_ida_auth=N

Launch Reg Client:

1. Set Environment Variable mosip.hostname to {sandbox domain name}

2. Login as a user (e.g. 110011) with password (MOSIP) to login into the client

Integrations

Guide to Work with Real HSM

Introduction:

The default sandbox uses simulator of HSM called SoftHSM. To connect to a real HSM you need to do the following:

1. Create client.zip

2. Update MOSIP properties

3. Point MOSIP services to HSM

client.zip:

The HSM connects over the network. Client.zip, which is a package of self-dependent PKCS11client.zip file is extracted from the artifactory when Dockers launch, unzipped, and install.sh is executed.

The zip must fulfil the following:

• Contain an install.sh

• Available in the artifactory

install.sh

This script must fulfil the following:

• Have executable permission

• Set up all that is needed to connect to HSM

• Able to run inside Dockers that are based on Debian, inherited from OpenJDK Dockers

• Place HSM client configuration file in mosip.kernel.keymanager.softhsm.config-path (see below)

• Not set any environment variables. If needed, they should be passed while running the MOSIP service Dockers

Properties:

Update the following properties in Kernel and IDA property files:

mosip.kernel.keymanager.softhsm.config-path=/config/softhsm-application.conf
mosip.kernel.keymanager.softhsm.keystore-pass={cipher}<ciphered password>
mosip.kernel.keymanager.softhsm.certificate.common-name=www.mosip.io
mosip.kernel.keymanager.softhsm.certificate.organizational-unit=MOSIP
mosip.kernel.keymanager.softhsm.certificate.organization=IITB
mosip.kernel.keymanager.softhsm.certificate.country=IN

Ensure you restart the services after this change.

Caution: The password is highly critical. To encrypt it, make sure you use a really strong password (using Config Server encryption). In addition, Config Server access should be very tightly regulated.

Artifactory:

Artifactory is built as a Docker in the sandbox and accessed via services. In that Docker, replace the client.zip. The changed Docker can be uploaded to your own Docker Hub registry for subsequent use.

HSM URL

HSM is used by Kernel and IDA services. Point the TCP URL of these services to new HSM host and port:

hsmUrl: tcp://{hsm host}:{port}

The above parameter is available in the Helm Chart of respective service.

Integrating Antivirus Scanner

In MOSIP, virus scanners can be implemented at different levels. ClamAV is used as an antivirus scanner by default. If you want your anti-virus (AV) to be incorporated, the same can be achieved as follows:

Registration Client

Running your AV on the registration client machine is sufficient. Not required for integration with MOSIP.

Server

This is implemented as a part of Kernel ClamAV project project. MOSIP uses this project to scan registration packets. You may integrate your anti-virus (AV) in the following ways:

• Option 1

  The registration packets are stored in Minio. Several AVs provide traffic flow analysis in line with the stream to defend against hazards. This form of implementation based on the network can be carried out without any alteration of the MOSIP code. But to ensure that network traffic passes through your AV, a careful network configuration is required.

• Option 2

  To support your AV at the code level, the following Java code has to be altered. In VirusScannerImpl.java, the scanFile/scanFolder/scanDocument API must be implemented with your AV SDK.

BioSDK Integration

In reg client, reg proc, and ida, the biosdk library is included. The guide offers steps for these integrations to be enabled here.

Integration with IDA

It is expected that Biosdk will be available as an HTTP service for IDA. The ID Authentication module then calls this service. To build such a service, refer to the reference implementation. /service contains service code; while /client contains client code that is combined with the IDA that connects to the service. This service can be operated as a pod or hosted outside the cluster within the Kubernetes cluster.

It is important to compile the client code into biosdk.zip and copy it to Artifactory. It is currently available at the following address:/artifactory/libs-release-local/biosdk/mock/0.9/biosdk.zip. This zip is downloaded by IDA dockers and installed during docker startup.

Integration with Reg Proc

The above service works for regproc as well.

Integration of External Postgres DB

Sandbox Parameters

    TBD

****

Make sure the Postgres is configured as 'UTC' for the time zone. This configuration is set to postgresql.conf when you install Postgres.

Integration with External Print Service

Introduction

MOSIP provides a reference implementation of print service that interfaces with the MOSIP system.

Integration Steps

Ensure the Following:

1. Compliant libraries, is reqartifactoryervices to link to HSM. MOSIP services install the same thing before the services start. The HSM vendor must have this library. The 1. Websub runs as https://{sandbox domain name}/websub on MOSIP and is accessible externally via Nginx. Websub runs on DMZ and nginx in the sandbox as configured for this access

2. Your service is able to register a topic with Websub with a callback url

3. The callback url is accessible from MOSIP websub

4. The print policy was established (be careful about enabled/disabled encryption)

5. Print partner created and certs uploaded DB Timezone6. The private and certificate of print partner is converted to p12 keystore format. You may use the following command:

    $ $ openssl pkcs12 -export -inkey pvt_key.pem  -in cert.pem  -out key.p12

1. This p12 key and password is used in your print service

2. Your print service reads the relevant (expected) fields from received credentials

3. Your print service is able to update MOSIP data share service after successfully reading the credentials

Dashboards Guide

This guide includes numerous tips for using various dashboards made available as part of the default installation of the sandbox. The links to various dashboards are available at:

https://{sandbox domain name}/index.html

KIBANA

A default dashboard to display the logs of all MOSIP services is installed as part of the sandbox installation. To view the Dashboard:

• Go to Kibana Home

• On the drop down on the top left select Kibana->Dashboard

• In the list of dashboards search for "MOSIP Service Logs"

• Select the dashboard

Kubernetes Dashboard

• Dashboard links:

  MZ: https://{sandbox domain name}/mz-dashboard

  DMZ: https://{sandbox domain name}/dmz-dashboard

• On the console machine, the tokens for the above dashboards are accessible at_/home/mosipuser/mosip-infra/deployment/sandbox-v2/tmp_. For each dashboard, two tokens are created - admin and view-only. View-only privileges are restricted.

Grafana

• Link:

  https://{sandbox domain name}/grafana

• Recommended charts:

  11074 (for node level stats)

  4784 (for container level stats)

Admin

Open the MOSIP Admin portal from the home page of the sandbox. Login with superAdmin username, MOSIP password.

Sanity Checks

The Sanity Check Procedures are the steps to verify that an installation is ready to be tested by a system administrator. In quality audits sanity check is consider as a major activity. It performs a quick test to check the main functionality of the software.

Checks while Deployment

• During deployment all pods should be 'green' on the dashboard of Kubernetes, or both these commands would display pods in 1/1 or 2/2 state if you are on the command line.

  Copy

    $ kc1 get pods -A
    $ kc2 get pods -A

  Some pods that show status 0/1 Complete are Kubernetes jobs - they will not turn 1/1.

• Note the following namespaces

• To check pods in a particular namespace. Example:

  Copy

  $ kc2 -n monitoring get pods

• If any pod is 0/1 then the Helm install command times out after 20 minutes

• Following are some useful commands:

  Copy

        $ kc1 delete pod <pod name># To restart a pod
        $ kc2 describe pod <pod name># Details of a pod
        $ kc1 logs <pod name># Logs of a pod
        $ kc2 logs -f <pod name># **Running log
        $ helm1 list# All helm installs in mzcluster
        $ helm2 list# All helm installs in dmzcluster

  Some pods have logs available in logger-sidecar as well. These are application logs.

• To re-run a module, helm delete module and then start with playbook. Example:

  Copy

        $ helm1 delete regproc
        $ helm2 delete dmzregproc
        $ an playbooks/regproc.yml

Module Basic Sanity Checks

Quick Sanity Check of Pre-Registration

1. Open Pre-Reg home page:

2. https://{sandbox domain name}/pre-registration-ui/

3. Enter your email or phone no to create an account

4. Enter the OTP that you received via email/sms in the selected box, or enter 111111 for Proxy OTP mode

5. Accept the Terms and Condition and CONTINUE after filling the demographic data

6. Enter your DOB or age

7. Select any of the Region, Province, City, Zone from the dropdown

8. Select any pin code from the dropdown

9. Phone number should be 10 digits and must not start with 0

10. CONTINUE after uploading required document of given size and type or skip the document upload process. (Recommended: upload any one document for testing purposes.)

11. Verify the demographic data and document uploaded previously and CONTINUE. You may edit with BACK if required

12. Choose any of the Recommended Registration Centre registration and CONTINUE

13. Select date and time-slot for Registration and add it to Available Applicants by clicking on + and CONTINUE

14. Now your first Appointment booking is done. You may view or modify your application in Your Application section

Registration Processor Test Packet Uploader

Prerequisites

Python3 must have been installed during the standard deployment setup for the scripts here.

Auth Partner Onboarding