ES-1856 updated Readme file as per review comments (#1023)

* ES-1856 Signed-off-by: ase-101 <[email protected]> * ES-1856 Signed-off-by: ase-101 <[email protected]> * ES-1856 Signed-off-by: ase-101 <[email protected]> * Updated branch name Signed-off-by: ase-101 <[email protected]> --------- Signed-off-by: ase-101 <[email protected]>
mosip · Dec 10, 2024 · 2781a9b · 2781a9b
1 parent cefe1a8
commit 2781a9b
Show file tree

Hide file tree

Showing 14 changed files with 85 additions and 30 deletions.
diff --git a/README.md b/README.md
@@ -1,21 +1,23 @@
-[![Maven Package upon a push](https://github.com/mosip/esignet/actions/workflows/push_trigger.yml/badge.svg?branch=develop)](https://github.com/mosip/esignet/actions/workflows/push_trigger.yml)
+[![Maven Package upon a push](https://github.com/mosip/esignet/actions/workflows/push_trigger.yml/badge.svg?branch=release-1.5.x)](https://github.com/mosip/esignet/actions/workflows/push_trigger.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=mosip_esignet&id=mosip_esignet&metric=alert_status)](https://sonarcloud.io/dashboard?id=mosip_esignet)
 # eSignet Project
 ## Overview
+
+eSignet offers a seamless and straightforward solution for incorporating an existing trusted identity database into the digital realm via plugins.
+
 This repository contains limited OpenId protocol implementation with:
 * OAuth 2.0 RFC 6749 - Authorization code flow support
 * OAuth 2.0 RFC 7636 - PKCE security extension
 * OAuth 2.0 RFC 7523 - JWT profile for client authentication
 * RFC 7519 - ID token and access token as JWT
 * OpenID Connect Discovery 1.0 - /.well-known/openid-configuration
 * RFC 5785 - Followed for both openid and oauth well-knowns
-* Identity assurance 1.0
+* Identity Assurance 1.0
 
 ## High level overview of eSignet with external systems
 
-![esignet-architecture-overview.png](docs/esignet-architecture-overview.png)
+![esignet-overview.png](docs/esignet-overview.png)
 
-`Note: Kindly refer `[eSignet signup repository](https://github.com/mosip/esignet-signup)` for more details on eSignet signup module.`
 
 eSignet repository contains following:
 
@@ -43,7 +45,7 @@ Refer to [SQL scripts](db_scripts).
 The project requires JDK 11.
 1. Build:
     ```
-    $ mvn clean install -Dgpg.skip=true
+    $ mvn clean install -Dgpg.skip=true -Dmaven.gitcommitid.skip=true
     ```
 ## [Deployment in K8 cluster](deploy/README.md)
 

diff --git a/docker-compose/README.md b/docker-compose/README.md
@@ -4,21 +4,34 @@ This is the docker compose setup to run esignet UI and esignet-service with mock
 
 ## I am a developer, how to setup dependent services to edit and test esignet-service?
 
-1. Run `docker compose --file dependent-docker-compose.yml up` to start all the dependent services.
-2. Go to command line for the project root directory and run `mvn clean install -Dgpg.skip=true -DskipTests=true`
-3. Add [esignet-mock-plugin.jar](../esignet-service/target/esignet-plugins/esignet-mock-plugin.jar) to esignet-service classpath in your IDE.
-4. Start the [EsignetServiceApplication.java](../esignet-service/src/main/java/io/mosip/esignet/EsignetServiceApplication.java) from your IDE.
-5. Import files under [postman-collection](../postman-collection) folder into your postman to test/validate OIDC flow.
+1. Open terminal and go to "docker-compose" folder.
+2. Run `docker compose --file dependent-docker-compose.yml up` to start all the dependent services.
+3. Go to command line for the project root directory and run `mvn clean install -Dgpg.skip=true -DskipTests=true`
+4. Add [esignet-mock-plugin.jar](../esignet-service/target/esignet-plugins/esignet-mock-plugin.jar) to esignet-service classpath in your IDE.
+5. Start the [EsignetServiceApplication.java](../esignet-service/src/main/java/io/mosip/esignet/EsignetServiceApplication.java) from your IDE.
+6. Import files under [postman-collection](../postman-collection) folder into your postman to test/validate OIDC flow.
 
 ## How to bring up the complete eSignet setup for a Demo?
 
-1. Run [docker-compose.yml](docker-compose.yml) to start eSignet UI and backend service.
-2. Access eSignet UI at http://localhost:3000
-3. Access eSignet backend services at http://localhost:8088/v1/esignet/swagger-ui.html
-4. Onboard relying party in eSignet, import files under [postman-collection](../postman-collection) folder into your postman. And invoke requests under `OIDC Client Mgmt/Mock` folder in postman. Copy the client ID in the `Create OIDC client` response.
-5. Add a `SignIn with eSignet` button in the relying party website and embed [eSignet authorize URL](http://localhost:3000/authorize?nonce=ere973eieljznge2311&state=eree2311&client_id=client_id&redirect_uri=redirect_uri&scope=openid&response_type=code&acr_values=mosip:idp:acr:generated-code&claims_locales=en&ui_locales=en-IN) in the button. Make sure to replace the query parameter values in the url before embedding in the button.
-6. Add a user in the mock-identity-system.
-7. Now the setup is completely ready to start the OIDC flow. [Refer eSignet user guides](https://docs.esignet.io/end-user-guide) for more information.
+1. Open terminal and go to "docker-compose" folder.
+2. Run `docker compose --file docker-compose.yml up` to start eSignet UI and backend service.
+3. Access eSignet UI at http://localhost:3000
+4. Access eSignet backend services at http://localhost:8088/v1/esignet/swagger-ui.html
+5. Onboard relying party in eSignet, import all files under [postman-collection](../postman-collection) folder into your postman. Choose `eSignet-with-mock` environment in the postman and invoke below requests under `OIDC Client Mgmt` -> `Mock` folder in postman.
+
+    a. `Get CSRF token`
+
+    b. `Create OIDC client` -> Make sure to update redirect Urls and logo URL as per your requirement in the request body.
+
+6. Copy the client ID in the `Create OIDC client` response.
+7. Add a `SignIn with eSignet` button in the relying party website and embed [eSignet authorize URL](http://localhost:3000/authorize?nonce=ere973eieljznge2311&state=eree2311&client_id=client_id&redirect_uri=redirect_uri&scope=openid&response_type=code&acr_values=mosip:idp:acr:generated-code&claims_locales=en&ui_locales=en-IN) in the button. Update the below query parameter in the eSignet authorize URL before embedding in the button.
+
+   a. `client_id` -> value should be replace with the value copied in the step 6
+
+   b. `redirect_uri` -> As updated in step 5
+
+8. Add a user in the mock-identity-system. Invoke `Creat User` request under `User Mgmt` -> `Mock` folder in the postman. 
+9. Now the setup is completely ready to start the OIDC flow. [Refer eSignet user guides](https://docs.esignet.io/end-user-guide) for more information.
 
 `Note: To know more about the relying party onboard and query parameters used in the eSignet authorize URL `[refer eSignet docs](https://docs.esignet.io/integration/relying-party)
 

diff --git a/docker-compose/dependent-docker-compose.yml b/docker-compose/dependent-docker-compose.yml
@@ -23,7 +23,7 @@ services:
       - 8082:8082
     environment:
       - container_user=mosip
-      - active_profile_env=local
+      - active_profile_env=default,local
       - SPRING_DATASOURCE_URL=jdbc:postgresql://database:5432/mosip_mockidentitysystem?currentSchema=mockidentitysystem
       - SPRING_DATASOURCE_USERNAME=postgres
       - SPRING_DATASOURCE_PASSWORD=postgres

diff --git a/docker-compose/docker-compose.yml b/docker-compose/docker-compose.yml
@@ -16,7 +16,7 @@ services:
       - 8082:8082
     environment:
       - container_user=mosip
-      - active_profile_env=local
+      - active_profile_env=default,local
       - SPRING_DATASOURCE_URL=jdbc:postgresql://database:5432/mosip_mockidentitysystem?currentSchema=mockidentitysystem
       - SPRING_DATASOURCE_USERNAME=postgres
       - SPRING_DATASOURCE_PASSWORD=postgres

diff --git a/docs/design/eSignet-authorize-flow.md b/docs/design/eSignet-authorize-flow.md
@@ -0,0 +1,26 @@
+# Overview
+
+eSignet offers a seamless and straightforward solution for incorporating an existing trusted identity database into the 
+digital realm via plugins.
+
+## Design Objectives
+
+1. Should be an overlay solution on top of any of the existing identity API. Users can adopt the IDP solution and plugin the backend identity verification against their existing identity registry.
+2. Should be able to independently operate without much dependency on existing services of MOSIP
+3. Support all the mandatory features of OIDC (Open ID Connect) specification so the solution can be OIDC certified
+4. When there are multiple options for a OIDC feature, support only the most secure option.
+5. All integration libraries to ID system should be a runtime plugable to reuse the official container images which helps with easier upgrades.
+6. Number of containers / runable applications to be kept to a minimum to avoid management overhead.
+7. Standard interfaces to be used as much as possible for integrations between components
+8. Should manage all the transactional data in expiring cache to increase data retrieval performance
+9. The API endpoint exposed should be stateless (avoid stickiness) to support better horizontal scaling.
+10. IAM based API authorization should have configuration to switched off to allow external network based mechanisms to control authorization and avoid high dependency on IAM system
+11. All personally identifiable information (PII) should be kept encrypted in storage and transit
+
+## Authorization code flow
+
+![eSignet-design-OIDC-authorize-flow.png](../eSignet-design-OIDC-authorize-flow.png)
+
+## Authorization code flow using biometric authentication
+
+![esignet-with-bio-auth.png](../esignet-with-bio-auth.png)
diff --git a/docs/design/eSignet-authorize-qr-code-flow.md b/docs/design/eSignet-authorize-qr-code-flow.md
@@ -0,0 +1,20 @@
+# Overview
+
+eSignet offers QR code based login using Wallet apps. Wallet apps store verifiable credentials(VC). Both demographic and biometric data 
+are available in the VC. Biometric data in the VC could be leveraged to perform local 1:1 biometric match to authenticate into eSignet and access any relying party services.
+
+## Binding Process
+
+VC issued by an identity system against an individual ID. Issued VC should be mapped to a key pair, private key resides in the wallet app's secure storage. 
+The corresponding public key is mapped to the same individual ID in the identity system (VC issuer).
+
+![esignet-wallet-binding.png](../esignet-wallet-binding.png)
+
+## Wallet based authentication using QR code
+
+Below diagram depicts the QR code based authorization code flow in eSignet.
+
+![esignet-authorize-qr-code-flow.png](../esignet-authorize-qr-code-flow.png)
+
+
+
diff --git a/docs/design/eSignet-overview.md b/docs/design/eSignet-overview.md
diff --git a/docs/eSignet-design-OIDC-authorize-flow.png b/docs/eSignet-design-OIDC-authorize-flow.png
diff --git a/docs/esignet-authorize-qr-code-flow.png b/docs/esignet-authorize-qr-code-flow.png
diff --git a/docs/esignet-overview.png b/docs/esignet-overview.png
diff --git a/docs/esignet-wallet-binding.png b/docs/esignet-wallet-binding.png
diff --git a/docs/IdP - OIDC Flow - Biometrics.png → docs/esignet-with-bio-auth.png b/docs/IdP - OIDC Flow - Biometrics.png → docs/esignet-with-bio-auth.png
diff --git a/esignet-service/README.md b/esignet-service/README.md
@@ -21,7 +21,7 @@ Note: VCI implementations are permanently moved to Inji-Certify.
 
 4. All the required plugins are runtime dependency to esignet-service.
 
-![](/docs/esignet-service-basic-interations.png)
+![](../docs/esignet-service-basic-interactions.png)
 
 ## Local setup of eSignet with mock plugins
 
@@ -118,7 +118,7 @@ This approach gives you the flexibility to run eSignet in a standalone mode or c
 eSignet API documentation can be found [here](../docs/esignet-openapi.yaml)
 
 ## Databases
-Refer to [SQL scripts](db_scripts/mosip_esignet).
+Refer to [SQL scripts](../db_scripts/mosip_esignet).
 
 ## License
-This project is licensed under the terms of [Mozilla Public License 2.0](LICENSE).
+This project is licensed under the terms of [Mozilla Public License 2.0](../LICENSE).
diff --git a/postman-collection/eSignet.postman_collection.json b/postman-collection/eSignet.postman_collection.json
@@ -218,7 +218,7 @@
 								],
 								"body": {
 									"mode": "raw",
-									"raw": "{    \n    \"requestTime\": \"{{$isoTimestamp}}\",\n    \"request\": {\n        \"clientId\": \"{{client_id}}\",\n        \"clientName\": \"{{$randomCompanyName}}\",\n        \"publicKey\": {{client_public_key}},\n        \"relyingPartyId\": \"mock-relying-party-id\",\n        \"userClaims\": [\n            \"name\",\n            \"email\",\n            \"gender\",\n            \"phone_number\",\n            \"picture\",\n            \"birthdate\"\n        ],\n        \"authContextRefs\": [\n            \"mosip:idp:acr:generated-code\",\n            \"mosip:idp:acr:password\",\n            \"mosip:idp:acr:linked-wallet\"\n        ],\n        \"logoUri\": \"{{$randomImageUrl}}\",\n        \"redirectUris\": [\n             \"{{redirection_url}}\",\n             \"io.mosip.residentapp://oauth\",\n             \"http://loclahost:3000/**\",\n             \"http://loclahost:5000/registration/*\"\n        ],\n        \"grantTypes\": [\n            \"authorization_code\"\n        ],\n        \"clientAuthMethods\": [\n            \"private_key_jwt\"\n        ]\n    }\n}",
+									"raw": "{    \n    \"requestTime\": \"{{$isoTimestamp}}\",\n    \"request\": {\n        \"clientId\": \"{{client_id}}\",\n        \"clientName\": \"{{$randomCompanyName}}\",\n        \"publicKey\": {{client_public_key}},\n        \"relyingPartyId\": \"mock-relying-party-id\",\n        \"userClaims\": [\n            \"name\",\n            \"email\",\n            \"gender\",\n            \"phone_number\",\n            \"picture\",\n            \"birthdate\"\n        ],\n        \"authContextRefs\": [\n            \"mosip:idp:acr:generated-code\",\n            \"mosip:idp:acr:password\",\n            \"mosip:idp:acr:linked-wallet\"\n        ],\n        \"logoUri\": \"{{$randomImageUrl}}\",\n        \"redirectUris\": [\n             \"{{redirection_url}}\",\n             \"io.mosip.residentapp://oauth\",\n             \"http://localhost:3000/**\",\n             \"http://localhost:5000/registration/*\"\n        ],\n        \"grantTypes\": [\n            \"authorization_code\"\n        ],\n        \"clientAuthMethods\": [\n            \"private_key_jwt\"\n        ]\n    }\n}",
 									"options": {
 										"raw": {
 											"language": "json"
@@ -256,7 +256,7 @@
 								],
 								"body": {
 									"mode": "raw",
-									"raw": "{\n    \"requestTime\": \"{{$isoTimestamp}}\",\n    \"request\": {\n        \"logoUri\": \"{{$randomImageUrl}}\",\n        \"redirectUris\": [\n               \"{{redirection_url}}\",\n             \"io.mosip.residentapp://oauth\",\n             \"http://loclahost:3000/**\",\n             \"http://loclahost:5000/registration/*\"\n        ],\n        \"userClaims\": [\n            \"name\",\n            \"email\",\n            \"gender\",\n            \"phone_number\",\n            \"birthdate\",\n            \"picture\",\n            \"address\"\n        ],\n        \"authContextRefs\": [\n            \"mosip:idp:acr:generated-code\",\n            \"mosip:idp:acr:password\",\n            \"mosip:idp:acr:linked-wallet\",\n            \"mosip:idp:acr:biometrics\",\n            \"mosip:idp:acr:static-code\"\n        ],\n        \"status\": \"ACTIVE\",\n        \"grantTypes\": [\n            \"authorization_code\"\n        ],\n        \"clientName\": \"{{$randomCompanyName}}\",\n        \"clientAuthMethods\": [\n            \"private_key_jwt\"\n        ]\n    }\n}",
+									"raw": "{\n    \"requestTime\": \"{{$isoTimestamp}}\",\n    \"request\": {\n        \"logoUri\": \"{{$randomImageUrl}}\",\n        \"redirectUris\": [\n               \"{{redirection_url}}\",\n             \"io.mosip.residentapp://oauth\",\n             \"http://localhost:3000/**\",\n             \"http://localhost:5000/registration/*\"\n        ],\n        \"userClaims\": [\n            \"name\",\n            \"email\",\n            \"gender\",\n            \"phone_number\",\n            \"birthdate\",\n            \"picture\",\n            \"address\"\n        ],\n        \"authContextRefs\": [\n            \"mosip:idp:acr:generated-code\",\n            \"mosip:idp:acr:password\",\n            \"mosip:idp:acr:linked-wallet\",\n            \"mosip:idp:acr:biometrics\",\n            \"mosip:idp:acr:static-code\"\n        ],\n        \"status\": \"ACTIVE\",\n        \"grantTypes\": [\n            \"authorization_code\"\n        ],\n        \"clientName\": \"{{$randomCompanyName}}\",\n        \"clientAuthMethods\": [\n            \"private_key_jwt\"\n        ]\n    }\n}",
 									"options": {
 										"raw": {
 											"language": "json"