Merge pull request #23 from AfraHussaindeen/main_doc-update

Update the onfido doc

docs/config.md

@@ -10,8 +10,9 @@ a workflow in the Onfido Studio and generate the necessary tokens.
 ## Prerequisites
 
 1. You need to have an Onfido account for this connector to work. 
-Please [contact](https://public.support.onfido.com/s/contactsupport) the Onfido team and they will be happy to help.
-2. This version of the connector is tested with WSO2 Identity Server version 7.0. 
+Please [contact](https://onfido.com/signup/) the Onfido team and they will be happy to help. Ensure that comparison 
+checks are enabled to the account. For more details, refer to the [Onfido Comparison Checks documentation](https://documentation.onfido.com/api/latest/#data_comparison).
+2. This version of the connector is tested with WSO2 Identity Server version 7.0 and above. 
 Make sure to download and set up the correct version of the
 [Identity Server](https://wso2.com/identity-and-access-management) in your environment.
 3. By default, the Identity Verification Provider feature is not enabled in 
@@ -66,52 +67,97 @@ deployment.toml file:
 ## Configuring Onfido Identity Verification Provider in WSO2 Identity Server Console
 
 1. Log in to the WSO2 Identity Server console using your admin credentials.
-2. In the WSO2 Identity Server Console, navigate to **Identity Verification Providers**.
-3. Click **+ New Identity Verification Provider** to create a new Identity Verification Provider (IDVP).
-4. You will be redirected to a page displaying a set of available IDVP templates.
-5. Click on `Create` under the Onfido IDVP.
-6. Enter a name for the Onfido IDVP and add the necessary configurations for the Onfido IDVP:
+2. In the WSO2 Identity Server Console, navigate to **Connections** on the left-hand panel.
+3. Click **New Connection**.
+4. From the displayed templates click on `Create` under the Onfido connector.
+5. Enter a name for the Onfido connector and add the necessary configurations for the Onfido connector:
    - **API Token**: The API token generated via the Onfido dashboard.
-   - **Workflow ID**: The unique identifier for the Workflow created using Onfido Studio.
+   - **Workflow ID**: The unique identifier for the Workflow created using Onfido Studio. 
+   For more information refer [Onfido Workflow Setup Guide](onfido-setup-guide.md).
    - **Base URL**: The regional base URL for Onfido API calls.
-7. Once you have entered the configuration details, click on `Create`.
-8. You will be redirected to the Setup Guide for the newly created Onfido IDVP. Follow the instructions displayed:
+6. Once you have entered the configuration details, click on `Create`.
+7. You will be redirected to the Setup Guide for the newly created Onfido connector. Follow the instructions displayed:
    - Log in to your Onfido dashboard and navigate to the Webhook configuration section. Generate a Webhook token by 
    providing the displayed URL and selecting only the `workflow_run.completed` event.
-   - Return to the WSO2 console and navigate to the **Settings** tab of the newly created Onfido IDVP. 
+   - Return to the WSO2 console and navigate to the **Settings** tab of the newly created Onfido connector. 
    Enter the obtained token in the Webhook Token field, then click `Update` to finish the setup.
-   - If you need to provide additional attribute mappings, navigate to the **Attributes** tab and 
-   configure the mappings.
-9. After completing the configuration and mapping, your Onfido IDVP will be ready for use with WSO2 Identity Server. 
-You can now integrate Onfido's identity verification process into your applications.
+8. Now that you have created a connection for Onfido, ensure that the attributes used in Onfido are correctly mapped to 
+the attributes in Identity Server. To do this:
+   - Navigate to the **Attributes** tab of the newly created Onfido connector.
+   - Verify that first name and last name are already configured as mandatory attributes. 
+   - To add other attribute mappings, click **Add Attribute Mapping**. 
+   - Enter the attribute name used in Onfido. 
+   - Select the corresponding Identity Server Claim URI. 
+   - Click **Add Attribute Mapping** and then **Update**.
+9. After completing the configuration and attribute mapping, your Onfido connector will be ready for use with WSO2 
+Identity Server. You can now integrate Onfido's identity verification process into your applications.
+
+> **Note :**
+> 
+> In WSO2 Identity Server 7.0, the steps differ slightly. To create a new Identity Verification Provider:
+> 1. Log in to the WSO2 Identity Server console using your admin credentials.
+> 2. Navigate to Identity Verification Providers in the left-hand menu.
+> 3. Click + New Identity Verification Provider.
+> 4. Follow steps 4-9 as listed above to complete the setup process.
 
 ### Integrating Onfido Identity Verification into Your Application
 
-To integrate Onfido's identity verification into your application, use the Identity Verification User APIs provided 
-by WSO2. You can find the API documentation [here](https://github.com/wso2/identity-api-user/blob/master/components/org.wso2.carbon.identity.api.user.idv/org.wso2.carbon.identity.api.user.idv.v1/src/main/resources/idv.yaml).
+To integrate Onfido's identity verification into your application use the [Onfido SDK](https://documentation.onfido.com/sdk/). 
+The Onfido SDK guides users through the verification process, including capturing and uploading documents or 
+photos for biometric checks. The actual verification can then be handled by Identity Server's 
+[Identity Verification User APIs](https://github.com/wso2/identity-api-user/blob/master/components/org.wso2.carbon.identity.api.user.idv/org.wso2.carbon.identity.api.user.idv.v1/src/main/resources/idv.yaml).
+
 For a practical example, refer to the [Onfido Sample App - Configuration Guidelines](samples/react-sample-app/README.md).
 
-### Core Steps:
+Follow the steps below to integrate Onfido Identity Verification into your external application:
 
-1. **Import Onfido SDK:**
-   - Add the [onfido-sdk-ui](https://github.com/onfido/onfido-sdk-ui) to your project.
+1. **Integrate Onfido SDK:**
+   - Add the Onfido SDK into your external application project. For detailed instructions, refer to the
+     [Onfido SDK documentation](https://documentation.onfido.com/sdk/).
 
 2. **Initiate Verification with Onfido:**
-   - Make a POST request to the `<Base URL>/api/users/v1/me/idv/verify` endpoint with the following properties in the 
-   API request body:
+   - To initiate verification with Onfido, make a POST request to the `<Base URL>/api/users/v1/me/idv/verify` 
+   endpoint with the following payload.
 
      ```json
      {
          "idVProviderId": "<Onfido identity verification provider's ID>",
-         "claims": "<List of WSO2 claims that require verification>",
+         "claims": [
+              "http://wso2.org/claims/givenname",
+              "http://wso2.org/claims/lastname"
+         ],
          "properties": [
              {
                  "key": "status",
                  "value": "INITIATED"
              }
          ]
      }
-   - **Note:** Ensure that the claims for both first name and last name are included in the claims list. These are mandatory.
+     ```
+   - **Note:**
+      - The `idVProviderId` can be found in the Setup Guide page of the created Onfido connector.
+      - It is mandatory to include the Claim URIs for first name and last name. Make sure to add any other claims that
+        were configured with the Onfido connector for verification.
+
+   - The response may look similar to the following:
+     ```json
+     {
+       "idVProviderId": "<Onfido identity verification provider's ID>",
+       "claims": [
+          {
+             "id": "<ID>",
+             "uri": "<WSO2 Claim URI>",
+             "isVerified": false,
+             "claimMetadata": {
+                "onfido_applicant_id": "<Onfido applicant ID>",
+                "onfido_workflow_run_id": "<Onfido workflow run ID>",
+                "sdk_token": "<Onfido SDK token>",
+                "onfido_workflow_status": "awaiting_input"
+             }
+          }
+        ]
+     }
+     ```
 
 3. **Launch the Onfido SDK:**
 
@@ -126,16 +172,19 @@ For a practical example, refer to the [Onfido Sample App - Configuration Guideli
       ```json
       {
           "idVProviderId": "<Onfido identity verification provider's ID>",
-          "claims": "<List of WSO2 claims that require verification>",
+          "claims": [
+              "http://wso2.org/claims/givenname",
+              "http://wso2.org/claims/lastname"
+          ],
           "properties": [
               {
                   "key": "status",
                   "value": "COMPLETED"
               }
           ]
       }
-   - **Note:** Ensure that the claims for both first name and last name are included in the claims list. These are mandatory.
-
+   - **Note:** It is mandatory to include the Claim URIs for first name and last name. Make sure to add any other claims that
+     were configured with the Onfido connector for verification.
 
 5. **Optional: Reinitiate the Verification Process**
 
@@ -150,7 +199,10 @@ For a practical example, refer to the [Onfido Sample App - Configuration Guideli
      ```json
      {
          "idVProviderId": "<Onfido identity verification provider's ID>",
-         "claims": "<List of WSO2 claims that require verification>",
+         "claims": [
+              "http://wso2.org/claims/givenname",
+              "http://wso2.org/claims/lastname"
+          ],
          "properties": [
              {
                  "key": "status",
@@ -160,8 +212,10 @@ For a practical example, refer to the [Onfido Sample App - Configuration Guideli
      }
      ```
 
-   - After reinitiating the verification process, follow Step 3 to relaunch the Onfido SDK using the new `sdk_token`, and then proceed to Step 4 to complete the verification process.
-   - **Note:** Ensure that the claims for both first name and last name are included in the claims list. These are mandatory.
+   - After reinitiating the verification process, follow Step 3 to relaunch the Onfido SDK using the new `sdk_token`, 
+   and then proceed to Step 4 to complete the verification process.
+   - **Note:** It is mandatory to include the Claim URIs for first name and last name. Make sure to add any other claims that
+     were configured with the Onfido connector for verification.
 
 
 ### Configuring Onfido Webhooks
@@ -173,9 +227,11 @@ To integrate Onfido webhooks with WSO2 Identity Server, use the provided Open AP
 
 `<Base URL>/idv/onfido/v1/<idvp_id>/verify`
 
-You can find this URL in the console under the settings tab corresponding to the Onfido IDVP you created. 
-By configuring this endpoint, WSO2 Identity Server will automatically update the verification status of users based on the notifications received from Onfido.
+You can find this URL in the console under the **Settings** tab corresponding to the Onfido connector you created. 
+By configuring this endpoint, WSO2 Identity Server will automatically update the verification status of users based on 
+the notifications received from Onfido.
 
 **Note:** 
 - Webhook configuration is mandatory, as the verification status of the user claims won't be updated unless it is configured.
-- Additionally, ensure that the workflow is configured to output the data comparison breakdown results. For more details, refer to the [Onfido Workflow Setup Guide](onfido-setup-guide.md).
+- Additionally, ensure that the workflow is configured to output the data comparison breakdown results. 
+For more details, refer to the [Onfido Workflow Setup Guide](onfido-setup-guide.md).

docs/onfido-setup-guide.md

@@ -14,7 +14,7 @@ Ensure that the required attributes are supported for verification.
 - **Workflow Outputs:** It's mandatory to configure the workflow outputs to include data comparison results, 
 which will be sent in the webhook response. Make sure that Comparison Checks are enabled and the workflow output 
 is configured appropriately. For more details, refer to 
-(Onfido's Comparison Checks documentation)[https://documentation.onfido.com/api/latest/#data_comparison].
+[Onfido's Comparison Checks documentation](https://documentation.onfido.com/api/latest/#data_comparison).
 
 ### Follow these steps to create a simple workflow for user attribute verification:
 
@@ -30,14 +30,19 @@ is configured appropriately. For more details, refer to
 
 #### Step 3 : Design the Workflow:
 
-- Use the drag-and-drop interface to create the workflow. Ensure it includes the necessary steps for document and, 
-optionally, face capture, as shown in the reference image.
+- Use the drag-and-drop interface to design the workflow, ensuring it includes the necessary steps for document 
+capture and, optionally, face capture, as shown in the sample reference image. In this case, the workflow includes 
+document verification and face similarity reports for identity verification.
 
-  ![Workflow output](images/workflow.png)
+  ![Sample Workflow](images/onfido-sample-workflow.png)
 
 #### Step 4 : Configure Workflow Inputs:
 
-- Set up the workflow to accept the user attributes you wish to verify. For details on configuring inputs, refer to the [Onfido Studio Input Data documentation](https://documentation.onfido.com/getting-started/onfido-studio-product/#workflow-input-data).
+- Configure the workflow to accept first name and last name as input attributes. For detailed instructions on 
+setting up inputs, refer to the [Onfido Studio Input Data documentation](https://documentation.onfido.com/getting-started/onfido-studio-product/#workflow-input-data).
+- Note : If you wish to use the sample application, ensure that you also enable date of birth.
+
+  ![Workflow input](images/onfido-workflow-input.png)
 
 #### Step 5 : Configure Workflow Outputs:
 
@@ -50,12 +55,17 @@ optionally, face capture, as shown in the reference image.
       ![Workflow output](images/workflow-output-sources.png)
     4. Click the **Done** button.
 - For more information, refer to the [Onfido Studio Output Data documentation](https://documentation.onfido.com/getting-started/onfido-studio-product/#workflow-output-data).
+- **Note** : To ensure the accuracy of user attribute verification, it is crucial to configure the output in the specified format. 
+The verification status depends on the result of the data comparison combined with the workflow status. 
+Additionally, make sure Comparison Checks are enabled in your Onfido account to receive these results in the 
+webhook response. For more information, refer to [Onfido's Comparison Checks documentation](https://documentation.onfido.com/api/latest/#data_comparison).
 
 #### Step 6 : Set Workflow Conditions:
 
-- Define the conditions that will determine if an applicant is approved. Since this workflow focuses on user attribute 
-verification, ensure that at least the condition **Document report - Breakdown - Data comparison - Result** is set to 
-**clear**. You can add additional conditions based on your requirements, but keep in mind that the WSO2 Identity Server 
+- To specify the criteria for approving or declining an applicant, click on the if/else condition task block. 
+Set the condition to check that both the document report and optionally face capture report results are marked as clear.
+If both are **clear**, the applicant can be approved. Otherwise, the application should be declined.
+You can add additional conditions based on your requirements, but keep in mind that the WSO2 Identity Server 
 will only mark the attribute verification as successful if the workflow returns an approved status for the applicant.
 
 #### Step 7 : Save the Workflow:
@@ -64,3 +74,29 @@ will only mark the attribute verification as successful if the workflow returns
 
 By following these steps, you will have successfully created a minimalistic workflow in Onfido Studio for user
 attribute verification.
+
+## Creating an API Token in Onfido Dashboard
+
+To create an API token:
+
+1. Log in to the [Onfido Dashboard](https://dashboard.onfido.com/).
+2. Go to **Settings** > **Developers** > **Tokens**.
+3. Click **Generate API token**.
+4. Select **Live** as the environment and click **Generate**.
+5. Copy the generated API token and store it securely for later use.
+
+## Creating a Webhook Token in Onfido Dashboard
+
+Onfido provides webhooks to notify your system about changes in the status of identity verifications. 
+Once Onfido is integrated, WSO2 Identity Server can automatically update users' verification status based on 
+notifications from Onfido. For more information, refer to the [Onfido webhooks documentation](https://documentation.onfido.com/api/latest/#webhooks).
+
+Follow the steps below to create a webhook token:
+
+1. On the [Onfido Dashboard](https://dashboard.onfido.com/), navigate to **Settings** > **Developers** > **Webhooks**.
+2. Click Create webhook.
+3. Once you Add Onfido as a connector in WSO2 Identity Server, a URL will be generated for the connector. 
+Copy the URL from the **Setup Guide** tab of your Onfido connector in WSO2 Identity Server.
+4. Paste the copied URL into the webhook URL field and select only the **workflow_run.completed** event.
+5. Click **Save**.
+6. Copy the webhook token, as it will be needed to complete the webhook configuration in Asgardeo.