[INJIMOB-2258] sync changes from release-0.15.0 & release-0.16.0 (#1826)

* [INJIMOB-2258] sync docs from release-0.15.0 Signed-off-by: KiruthikaJeyashankar <[email protected]> * [INJIMOB-2091] update OpenID4VP swift library version (#1815) * [INJIMOB-2091] update OpenID4VP swift library version Other changes: - Modify authenticateVerifier method call's labels as per library Signed-off-by: KiruthikaJeyashankar <[email protected]> * [INJIMOB-2901] rename encodedAuthorizationRequest to urlEncodedAuthorizationRequest Signed-off-by: KiruthikaJeyashankar <[email protected]> --------- Signed-off-by: KiruthikaJeyashankar <[email protected]> * [INJIMOB-2978] update module dependencies (#1821) * [INJIMOB-2258]: bump up vc-verifier verion and update ovp library Signed-off-by: Alka Prasad <[email protected]> * [INJIMOB-2978] update module dependencies Other changes - update openid4vp swift library version Co-Authored by: Abhishek Paul <[email protected]> Signed-off-by: KiruthikaJeyashankar <[email protected]> * [INJIMOB-2258] update swift openid4vp package Signed-off-by: KiruthikaJeyashankar <[email protected]> --------- Signed-off-by: Alka Prasad <[email protected]> Signed-off-by: KiruthikaJeyashankar <[email protected]> Co-authored-by: Alka Prasad <[email protected]> * [INJIMOB-2091] update OpenID4VP swift library version to develop Signed-off-by: KiruthikaJeyashankar <[email protected]> --------- Signed-off-by: KiruthikaJeyashankar <[email protected]> Signed-off-by: Alka Prasad <[email protected]> Co-authored-by: Alka Prasad <[email protected]>
mosip · Feb 27, 2025 · 5c01a00 · 5c01a00
1 parent d5b7a3c
commit 5c01a00
Show file tree

Hide file tree

Showing 14 changed files with 329 additions and 83 deletions.
diff --git a/android/app/build.gradle b/android/app/build.gradle
@@ -269,11 +269,11 @@ dependencies {
     implementation("com.facebook.react:react-android")
     implementation 'com.facebook.soloader:soloader:0.10.1+'
     implementation("io.mosip:pixelpass-aar:0.7.0-SNAPSHOT")
-    implementation("io.mosip:secure-keystore:0.3.0-SNAPSHOT")
+    implementation("io.mosip:secure-keystore:0.3.0")
     implementation("io.mosip:tuvali:0.5.2-SNAPSHOT")
-    implementation("io.mosip:inji-vci-client:0.2.0-SNAPSHOT")
+    implementation("io.mosip:inji-vci-client:0.2.0")
     implementation("com.google.code.gson:gson:2.10.1")
-    implementation("io.mosip:vcverifier-aar:1.1.0-SNAPSHOT"){
+    implementation("io.mosip:vcverifier-aar:1.2.0-SNAPSHOT"){
         exclude group: 'org.bouncycastle', module: 'bcpkix-jdk15on'
     }
 

diff --git a/android/app/src/main/java/io/mosip/residentapp/InjiOpenID4VPModule.java b/android/app/src/main/java/io/mosip/residentapp/InjiOpenID4VPModule.java
@@ -50,11 +50,11 @@ public void init(String appId) {
     }
 
     @ReactMethod
-    public void authenticateVerifier(String encodedAuthorizationRequest, ReadableArray trustedVerifiers,
+    public void authenticateVerifier(String urlEncodedAuthorizationRequest, ReadableArray trustedVerifiers,
             Boolean shouldValidateClient,
             Promise promise) {
         try {
-            AuthorizationRequest authenticationResponse = openID4VP.authenticateVerifier(encodedAuthorizationRequest,
+            AuthorizationRequest authenticationResponse = openID4VP.authenticateVerifier(urlEncodedAuthorizationRequest,
                     convertReadableArrayToVerifierArray(trustedVerifiers), shouldValidateClient);
             String authenticationResponseAsJson = gson.toJson(authenticationResponse, AuthorizationRequest.class);
             promise.resolve(authenticationResponseAsJson);

diff --git a/docs/authorization-server-wellknown-discovery.md b/docs/authorization-server-wellknown-discovery.md
@@ -0,0 +1,112 @@
+## VC Download Flow with Authorization Server Wellknown Discovery
+
+This document outlines the process of initiating the authorization flow during the Verifiable Credential (VC) download, utilizing the Authorization Server's well-known metadata. The flow adheres to OpenID4VCI specifications to ensure compliance and interoperability.
+
+## Introduction to Authorization Server Metadata Discovery
+
+- Credential Issuer metadata includes an optional `authorization_servers` property, which specifies the authorization servers the issuer relies on for authorization purposes.
+
+- From a wallet's perspective, the `authorization_servers` property plays a crucial role in identifying the supported authorization servers associated with the Credential Issuer. This enables the wallet to determine the appropriate authorization mechanisms, ensuring seamless and compliant credential issuance as per the OpenID4VCI specification.
+
+
+## VC Download Flow with Authorization Server Metadata Discovery - Sequence Diagram
+
+**Actors Involved**
+1. Inji Wallet (Mobile App)
+2. Issuing Authority / Credential Issuer
+3. Authorization Server
+4. mimoto (Wallet backend)
+
+```mermaid
+sequenceDiagram
+  participant Inji_Wallet as Inji Wallet (Mobile App)
+  participant mimoto as mimoto (Wallet backend)
+  participant Issuing_Authority as Issuing Authority / CredentialIssuer
+  participant Authorization_Server as Authorization Server
+  
+  Inji_Wallet ->> Issuing_Authority: 1. Request Credential issuer metadata via wellknown
+  Issuing_Authority ->> Inji_Wallet: 2. Return the credential issuer metadata
+  Note over Inji_Wallet: Authorization Server Metadata Discovery
+rect rgba(191, 223, 255, 0.3)
+    Inji_Wallet ->> Inji_Wallet: 3.1 Analyzes credential issuer metadata<br> to retrieve authorization server
+    Inji_Wallet ->> Authorization_Server: 3.2 Get authorization server metadata<br>GET /.well-known/oauth-authorization-server HTTP/1.1<br>Host: authorization server host
+    Authorization_Server ->> Inji_Wallet: 3.3 Return authorization server metadata
+    Inji_Wallet ->> Inji_Wallet: 3.4 Check if wallet supports to initiate authorization flow &<br>gather information to initiate authorization request
+end
+  Inji_Wallet ->> Authorization_Server: 4. Initiate authorization flow
+  Note right of Inji_Wallet: Other flows of authorization flow & VC download proceeds
+  Authorization_Server ->> Inji_Wallet: 5. On successful authentiction return authorization code (auth_code)
+  Inji_Wallet ->> mimoto: 6. get accessToken in exchange with authorization code
+  mimoto ->> Authorization_Server: 7. token exchange<br/>(API call to token_endpoint with authorization_code & other client related details)
+  Authorization_Server ->> mimoto: 8. On success, return access_token
+  mimoto ->> Inji_Wallet: 9. return access_token
+  Inji_Wallet ->> Issuing_Authority: 10. Credential request
+  Issuing_Authority ->> Inji_Wallet: 11. Credential response
+```
+
+
+## Retrieving Authorization Server Metadata
+
+Authorization server metadata is derived from the `authorization_servers` property of the credential issuer metadata. This process enables the wallet to identify and interact with the appropriate authorization server for credential issuance, in accordance with the OpenID4VCI specification.
+
+#### Steps Involved:
+
+1. **Fetch Credential Issuer Metadata** – Retrieve the metadata associated with the credential issuer.
+2. **Extract the `authorization_servers` Property** – Identify the list of authorization servers supported by the issuer.
+3. **Select an Authorization Server** – The first entry from the `authorization_servers` array is selected as the default authorization server. (As per OpenID4VCI, when multiple entries exist, each should be iterated and checked for compatibility with the wallet. This step is currently not implemented.)
+4. **Discover Authorization Server Metadata** – Perform a well-known discovery request to obtain the metadata of the selected authorization server.
+
+
+#### Authorization Server Metadata Discovery Request
+
+A well-known endpoint is used to retrieve metadata:
+
+```http request
+GET /.well-known/oauth-authorization-server HTTP/1.1
+Host: authorization-server-host
+```
+
+Sample Authorization Server Metadata Response
+
+```http request
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+      "issuer": "https://server.example.com",
+      "authorization_endpoint": "https://server.example.com/authorize",
+      "token_endpoint": "https://server.example.com/token",
+      "jwks_uri": "https://server.example.com/jwks.json",
+      "token_endpoint_auth_methods_supported": ["private_key_jwt"],
+      "token_endpoint_auth_signing_alg_values_supported": ["RS256"],
+      "scopes_supported":["profile", "email", "phone"],
+      "response_modes_supported": ["query"],
+      "grant_types_supported": ["authorization_code"],
+      "response_types_supported": ["code"]
+ }
+```
+
+## Assessing Wallet Compatibility with Authorization Server for Authorization Flow in VC download
+
+To determine whether the wallet supports the authorization server's requirements and can proceed with the authorization flow, it validates and processes the authorization server metadata in compliance with the OpenID4VCI specification.
+
+#### Steps Involved:
+
+1. **Validate Supported Grant Types** – Verify that the `grant_types_supported` field in the authorization server metadata includes a grant type that the wallet supports. (Currently, the wallet supports only the authorization_code grant type.)
+2. **Extract the Authorization Endpoint** – Retrieve the `authorization_endpoint` from the authorization server metadata, which will be used to initiate the authorization process.
+3. **Initiate the Authorization Flow** – Begin the authentication process with the authorization server using the retrieved endpoint.
+4. **Proceed with Credential Retrieval** – Once authorization is successfully completed, the wallet continues with the subsequent steps of the VC download process.
+
+### Handling errors in wellknown discovery
+To ensure a smooth authorization flow, the wallet must handle potential errors that may arise during the well-known discovery process. Below are key error handling scenarios:
+
+##### 1. Unsupported Grant Type
+- If the grant_types_supported field in the authorization server metadata does not include a grant type supported by the wallet (authorization_code), the authorization process is terminated. 
+- The user is notified with an appropriate error message indicating that the wallet is incompatible with the authorization server.
+##### 2. Network and API Errors
+- Errors encountered while making requests to the authorization server’s well-known endpoint (e.g., network failures, timeouts, or invalid responses) are handled gracefully.
+- Appropriate error handling mechanisms, such as retry logic or error display, are implemented to inform the user.
+
+## Aligning with OpenID4VCI Specification
+
+The implementation adheres to OpenID4VCI Draft 13 and RFC 8414 (OAuth 2.0 Authorization Server Metadata) to ensure standardized discovery and interaction with authorization servers. 
diff --git a/docs/mdoc-support.md b/docs/mdoc-support.md
@@ -0,0 +1,91 @@
+## Support of credential format mso_mdoc
+
+This document provides a comprehensive overview of the process for downloading and rendering an mDoc, adhering to the OpenID4VCI specification. It details the necessary steps to retrieve, validate, and present credentials in the mso_mdoc format.
+### Actors involved
+1. Inji Wallet
+2. Issuing authority
+3. _inji-vci-client_ (Library for downloading credential)
+4. _vc-verifier_ (library for verification of downloaded VC)
+5. _pixelpass_ (In case of mdoc, this library for converting base64 url encoded mdoc credential to JSON for rendering purpose)
+
+###  Sequence diagram - download & view mso_mdoc credential format VC
+
+```mermaid
+sequenceDiagram
+  participant Inji_Wallet as Inji Wallet (Mobile App)
+  participant InjiVCIClient as inji-vci-client
+  participant VCVerifier as vc-verifier
+  participant Pixelpass as Pixelpass
+  participant Issuing_Authority as Issuing Authority
+  Inji_Wallet -) InjiVCIClient: 1. Request mso_mdoc credential
+  InjiVCIClient ->> Issuing_Authority: 2. Credential Request
+  Issuing_Authority ->> InjiVCIClient: 3. Return mso_mdoc format specific Credential response (base64 url encoded string)
+  InjiVCIClient -) Inji_Wallet: 4. Return mdocCredential
+  Inji_Wallet -) VCVerifier: 5. Verify mdocCredential
+  VCVerifier -) Inji_Wallet: 6. Return Verification Result
+  Inji_Wallet ->> Inji_Wallet: 7. Save Verified VC
+  Inji_Wallet -) Pixelpass: 8. convert mdocCredential(base64 url encoded CBOR) to JSON for rendering
+  Pixelpass -) Inji_Wallet: 9. Return mdocInJson
+  Inji_Wallet ->> Issuing_Authority: 10. Get credential issuer metadata for rendering VC to user (GET /.well-known/openid-credential-issuer)
+  Issuing_Authority ->> Inji_Wallet: 11. Return credential issuer metadata
+  Inji_Wallet ->> Inji_Wallet: 12. use the issuer metadata for rendering VC
+
+```
+
+#### Steps involved
+##### 1. Make credential request
+
+Establish communication with the _inji-vci-client_ to submit a credential request to the issuing authority.
+
+````
+{
+   "format": "mso_mdoc",
+   "doctype": "org.iso.18013.5.1.mDL",
+   "claims": {
+      "org.iso.18013.5.1": {
+         "given_name": {},
+         "family_name": {},
+         "birth_date": {}
+      },
+   },
+   "proof": {
+      "proof_type": "jwt",
+      "jwt": "eyJraWQiOiJkaWQ6ZXhhbXBsZ...KPxgihac0aW9EkL1nOzM"
+   }
+}
+````
+##### 2. Receive the credential response
+The _inji-vci-client_ submits the credential request to the issuing authority. Once the response is received, it is returned to the Wallet.
+
+```
+{  
+	"credential": "<base-64-url-encoded-cbor-data>"  
+}  
+```
+##### 3. Perform vc verification
+
+After obtaining the credential from the issuing authority through the _inji-vci-client_ library, a verification process ensures that the issued Verifiable Credential (VC) remains unaltered. For credentials in the mso_mdoc format, the following validations are performed using the _vc-verifier_ library:
+
+1. [x] Confirm the credential has not been tampered with. (Cryptographic Signature/Hash Verification)
+2. [x] Issuing Country Validation.
+3. [x] Document Type Check.
+4. [x] Confirms the credential is within its valid usage period. (Validity Information Check)
+5. [x] Verifies the integrity of the certificate chain to ensure that the credential is issued by a legitimate and authorized issuer. (Document Signer certification validation) [currently not implemented]
+
+##### 4. Rendering of mso_mdoc VC
+
+- In the case of an mso_mdoc format Verifiable Credential (VC), the issuer provides the credential as Base64-encoded CBOR data. The Wallet interacts with the _pixelpass_ library to convert this encoded CBOR data into JSON format, which is then used for rendering the credential.
+- The processed credential is not stored in persistent storage or shared via Bluetooth to optimize storage efficiency and transmission size. Instead, it is maintained only within the state machine context, ensuring that repeated interactions with PixelPass are avoided for rendering.
+- Once the processed VC is obtained, the issuer's well-known configuration is used to determine how the credential should be displayed, including labeling and field ordering.
+
+- #####  VC Detail View Rendering:
+  - Field Labels:
+  The labels displayed for each field are derived from the Credential Issuer's metadata claims under the display attribute.
+  Reference: OpenID4VCI Spec - Credential Issuer Metadata. 
+  - Field Ordering:
+    - As per OpenID4VCI Draft 13, the order property in the issuer’s well-known configuration defines the order of fields to be displayed.
+    This property contains an array of claims.display.name values, specifying the sequence in which the Wallet should present the fields. 
+    -   Example:
+       ` org.iso.18013.5.1\~given_name` (` Format: {namespace}\~{claim-value-name}`)
+
+This structured approach ensures that the credential is rendered accurately and efficiently while maintaining a lightweight storage and transmission footprint.
diff --git a/docs/wla-auth.md b/docs/wla-auth.md
@@ -0,0 +1,41 @@
+# WLA Auth
+
+Inji Wallet enables seamless authentication to online portals using verifiable credentials. Through a QR code-based deep-linking technique, users can authenticate biometrically via their mobile wallet and securely grant data sharing permissions to access online services.
+
+## Wallet Local Authentication - Sequence Diagram
+
+Actors Involved
+
+- Inji Wallet (Mobile App)
+- User
+- Authorization Server
+- Online Portal
+
+```mermaid
+sequenceDiagram
+    participant User as User
+    participant Wallet as Wallet<br/>(Downloaded and binded VC)
+    participant Online Portal as Online Portal
+    participant Authorization Server as Authorization Server
+
+    User -->> Online Portal: Opens online portal in mobile
+    Note over Online Portal: Display the Sign-In options
+    User -->> Online Portal: Clicks on Sign-in with Authorization Server
+    Online Portal -->> Authorization Server: Redirects to Authorization Server
+    Note over Authorization Server: Displays options to login
+    User -->> Authorization Server: Clicks on Login with Wallet
+    Note over Authorization Server: Generates QR code with token<br/>and redirect scheme
+    User -->> Authorization Server: Clicks on the QR Code
+    Authorization Server -->> Wallet: Checks the redirect scheme and<br/>launches the correct activity
+
+    Note over User,Authorization Server: Authentication and Consent Flow
+    Wallet -->> User: Prompts for biometric authentication
+    User -->> Wallet: Provides biometric authentication
+    Wallet -->> Authorization Server: Sends authentication confirmation
+    Authorization Server -->> Wallet: Requests consent for data sharing
+    Wallet -->> User: Displays consent screen with requested permissions
+    User -->> Wallet: Reviews and grants consent
+    Wallet -->> Authorization Server: Sends consent confirmation
+
+    Authorization Server -->> Online Portal: Logged in Successfully
+```