Add documentation for Onfido Connector

README.md

@@ -1,2 +1,27 @@
-# identity-verification-onfido
-Onfido identity verification connector to WSO2 Identity Server.
+# Identity Verification with Onfido
+
+Onfido is a leading global identity verification platform that empowers businesses to securely and efficiently 
+verify the identities of their users. Utilizing advanced AI and machine learning technologies,
+Onfido verifies various types of identity documents, such as passports, driver's licenses, 
+and national IDs, and performs facial biometric checks.
+
+The WSO2 Onfido Identity Verification Connector integrates Onfido's powerful identity verification 
+capabilities into WSO2 Identity Server, allowing businesses to seamlessly incorporate Onfido into 
+their authentication and onboarding processes. This integration ensures the authenticity and 
+integrity of user identities.
+
+By leveraging the Onfido Identity Verification Connector, businesses can streamline their identity 
+verification processes, reduce manual verification efforts, and enhance security. 
+The connector offers a simple and effective way to integrate Onfido's functionalities, 
+helping businesses comply with regulatory requirements and mitigate fraud risks.
+
+This connector is compatible with WSO2 IS version 7.0.0 and above.
+
+## Getting started
+To get started with the identity verification with Onfido, 
+go to [IDV with Onfido - Configuration Guidelines](docs/config.md).
+Once you have completed your configurations, you can verify your users using OnFido.
+
+## Technical workflow
+To understand the underlying flow of the HYPR authenticator, see the
+[Technical workflow of Onfido Identity Verification Provider](docs/technical-workflow.md)

docs/config.md

@@ -0,0 +1,174 @@
+# Configuring the Onfido Identity Verification Connector
+
+To use the Onfido Identity Verification Connector with WSO2 Identity Server, you need to configure the connector within 
+the WSO2 Identity Server. Follow the instructions below to set up the Onfido connector using a 
+sample application.
+
+To test this setup, your organization must first have an Onfido account. You will then need to create 
+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. 
+Make sure to download and set up the correct version of the
+[Identity Server](https://wso2.com/identity-and-access-management) in your environment.
+
+## Setting up and Installing the Onfido Connector
+
+### Step 1: Extracting the Project Artifacts
+
+1. Clone the `identity-verification-onfido` repository.
+2. Build the project by running `mvn clean install` in the root directory.
+
+**Note:** The latest project artifacts can also be downloaded from the Connector Store.
+
+### Step 2: Deploying the Onfido Authenticator
+
+1. Navigate to `identity-verification-onfido/components → org.wso2.carbon.identity.verification.onfido.connector → target`.
+2. Copy the `org.wso2.carbon.identity.verification.onfido.connector-<version>-SNAPSHOT.jar` file.
+3. Navigate to `<IS_HOME>/repository/components/dropins`.
+4. Paste the `.jar` file into the dropins directory.
+5. Alternatively, you can drag and drop the `.jar` file into the dropins directory.
+6. Next, navigate to `identity-verification-onfido/ui-metadata` and copy the `onfido` directory.
+7. Paste it into `<IS_HOME>/repository/resources/identity/extensions/identity-verification-providers` directory.
+
+### Step 3: Deploying the Onfido Webhook REST API
+
+1. Navigate to `identity-verification-onfido/components → org.wso2.carbon.identity.verification.onfido.api → org.wso2.carbon.identity.verification.onfido.api.dispatcher → target`.
+2. Copy the `idv#onfido.war` file.
+3. Navigate to `<IS_HOME>/repository/deployment/server/webapps`.
+4. Paste the `.war` file into the webapps directory.
+5. Next, navigate to `<IS_HOME>/repository/conf`.
+6. Open the `deployment.toml` file.
+7. Add the following lines of code:
+
+    ```toml
+    [[resource.access_control]]
+    context = "(.*)/idv/onfido/v1/(.*)/verify"
+    secure = "false"
+    http_method = "POST"
+
+    [tenant_context]
+    enable_tenant_qualified_urls = "true"
+    enable_tenanted_sessions = "true"
+    rewrite.custom_webapps = ["/idv/onfido/"]
+    ```
+
+## 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:
+   - **API Token**: The API token generated via the Onfido dashboard.
+   - **Workflow ID**: The unique identifier for the Workflow created using Onfido Studio.
+   - **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:
+   - 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. 
+   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.
+
+### 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).
+For a practical example, refer to the [Onfido Sample App - Configuration Guidelines](samples/react-sample-app/README.md).
+
+### Core Steps:
+
+1. **Import Onfido SDK:**
+   - Add the [onfido-sdk-ui](https://github.com/onfido/onfido-sdk-ui) to your project.
+
+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:
+
+     ```json
+     {
+         "idVProviderId": "<Onfido identity verification provider's ID>",
+         "claims": "<List of WSO2 claims that require verification>",
+         "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.
+
+3. **Launch the Onfido SDK:**
+
+   - Extract the `sdk_token` and `onfido_workflow_run_id` from the response of the initiation request. 
+   Use these to launch the Onfido SDK in your application.
+
+4. **Complete the Verification Process:**
+
+   - After the user completes the document submission and face capture (as defined in the workflow) via the Onfido SDK, 
+   make another POST request to the `<Base URL>/api/users/v1/me/idv/verify` endpoint with the following properties in the API request body:
+
+      ```json
+      {
+          "idVProviderId": "<Onfido identity verification provider's ID>",
+          "claims": "<List of WSO2 claims that require verification>",
+          "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.
+
+
+5. **Optional: Reinitiate the Verification Process**
+
+   - In some cases, a user might interrupt the Onfido verification process before completing their 
+   document submission or face capture (as defined in the workflow) via the SDK. To allow users to continue the 
+   verification process from where they left off, you can reinitiate the process.
+   - Reinitiation is only allowed when the workflow status of the claim is `AWAITING_INPUT`. 
+   This status indicates that the process is paused, awaiting further input from the user.
+   - To reinitiate the verification process, make a POST request to the `<Base URL>/api/users/v1/me/idv/verify` 
+   endpoint with the following properties in the API request body:
+
+     ```json
+     {
+         "idVProviderId": "<Onfido identity verification provider's ID>",
+         "claims": "<List of WSO2 claims that require verification>",
+         "properties": [
+             {
+                 "key": "status",
+                 "value": "REINITIATED"
+             }
+         ]
+     }
+     ```
+
+   - 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.
+
+
+### Configuring Onfido Webhooks
+
+Onfido offers webhooks to notify your system about changes in the status of identity verifications. 
+You can learn more about Onfido webhooks by visiting their [official documentation](https://documentation.onfido.com/#about-webhooks).
+
+To integrate Onfido webhooks with WSO2 Identity Server, use the provided Open API endpoint as the webhook URL:
+
+`<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.
+
+**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).

docs/onfido-setup-guide.md

@@ -0,0 +1,66 @@
+## Creating a Workflow in Onfido Studio
+
+Onfido Studio allows you to create dynamic end-user verification journeys using the Workflow Builder, 
+a no-code, drag-and-drop interface available directly through the Onfido Dashboard. 
+This interface lets you build, maintain, and update workflows without requiring developer involvement.
+
+When using the WSO2 Onfido connector for identity verification, you need to create a workflow that, 
+at a minimum, includes document data capture. Optionally, you can also integrate face capture into the workflow.
+
+### Important Notes:
+
+- **Workflow Inputs:** You must configure the workflow to accept the necessary user attributes for verification. 
+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].
+
+### Follow these steps to create a simple workflow for user attribute verification:
+
+#### Step 1 : Access Workflow Builder:
+
+- Log in to the Onfido Dashboard. 
+- Navigate to the **Workflows** section.
+
+#### Step 2 : Create a New Workflow:
+
+- Click on the **New Workflow** button.
+- Click on **New Version** to be redirected to the Workflow Builder page.
+
+#### 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.
+
+  ![Workflow output](images/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).
+
+#### Step 5 : Configure Workflow Outputs:
+
+- Set up the workflow to return data comparison results by following these steps:
+    1. Go to the workflow output configuration section.
+    2. Under the **Configure** tab, add a new property named `data_comparison` and set its format to `Other`.
+      ![Workflow output](images/worflow-output-configure.png)
+    3. Navigate to the **Sources** tab, and under both `APPROVE APPLICANT` and `DECLINE APPLICANT`, select 
+   `Document report - Breakdown - Data comparison - Breakdown`.
+      ![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).
+
+#### 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 
+will only mark the attribute verification as successful if the workflow returns an approved status for the applicant.
+
+#### Step 7 : Save the Workflow:
+
+- Review the workflow and click **Save** to finalize the setup.
+
+By following these steps, you will have successfully created a minimalistic workflow in Onfido Studio for user
+attribute verification.

docs/technical-workflow.md

@@ -0,0 +1,54 @@
+### Technical Workflow - Onfido Identity Verification
+
+The Onfido Identity Verification Connector integrates seamlessly with WSO2 Identity Server to enable secure and efficient
+user identity verification. The following outlines the technical workflow that supports this integration, as illustrated
+in the accompanying sequence diagram:
+
+1. **Admin Configuration in Onfido Dashboard**:
+   - The administrator logs into the Onfido Dashboard to create a verification workflow and generate the necessary API 
+   credentials, such as the API token and Webhook token. These credentials are essential for configuring the Onfido 
+   Identity Verification Provider in WSO2 Identity Server.
+
+
+2. **Configuring Onfido in the Identity Server Console**:
+   - The administrator configures the Onfido Identity Verification Provider within the WSO2 Identity Server console using
+   the API credentials obtained from the Onfido Dashboard. This setup enables the Identity Server to communicate with 
+   Onfido for verification purposes
+
+
+3. **Setting Up the Application for Identity Verification**:
+   - The application developer configures the application to integrate with the Onfido Identity Verification Provider. 
+   This setup allows the application to use Onfido for verifying user identities as part of the authentication process.
+
+
+4. **User Authentication and Verification Initiation**:
+   - When a user attempts to authenticate through the application, they first need to successfully complete the 
+   authentication process. If the user's claims are not yet verified, the application triggers the identity verification
+   process. This is done by making an API call to WSO2 Identity Server, which initiates the verification process.
+   - WSO2 Identity Server then creates an applicant in Onfido, starts the verification workflow, and generates 
+   an SDK token. This token is used to launch the Onfido SDK within the application, allowing the user to begin the 
+   verification process.
+
+
+5. **Launching and Completing the Verification Process**:
+   - The Onfido SDK, launched using the SDK token and Workflow Run ID, guides the user through the verification process. 
+   The user is prompted to submit the required documents and complete any additional verification steps, such as 
+   capturing a live photo.
+   - Once the user completes these steps, the application sends a request to WSO2 Identity Server to finalize the 
+   verification process. This ensures that the user's verification status is updated accordingly in the Identity Server.
+
+
+6. **Webhook Configuration and Status Update**:
+   - Onfido sends status updates to WSO2 Identity Server via webhooks, providing real-time notifications of any changes 
+   in the verification status. WSO2 Identity Server uses these updates to automatically update the user's identity 
+   verification claim metadata.
+   - Accurate webhook configuration is essential to ensure that the user's verification status is correctly reflected 
+   in WSO2 Identity Server.
+
+The sequence diagram below visually represents this technical workflow, illustrating how each step in the process is 
+carried out to ensure secure and reliable user identity verification.
+
+![Onfido Identity Verification Sequence Diagram](images/onfido_sd.png)
+
+This diagram outlines the integration between Onfido's identity verification process and WSO2 Identity Server, 
+highlighting the secure and efficient verification experience provided to end-users.