Merge pull request #15 from ashensw/docs

Update docs with the new changes
wso2-extensions · Nov 12, 2021 · ced55f4 · ced55f4
2 parents 16fe0f3 + 809fb93
commit ced55f4
Show file tree

Hide file tree

Showing 6 changed files with 78 additions and 59 deletions.
diff --git a/docs/config.md b/docs/config.md
@@ -2,20 +2,16 @@
 
 To use TypingDNA with WSO2 Identity Server, first you need to configure the authenticator with WSO2 Identity Server. The following topics provide instructions on how to configure the TypingDNA with WSO2 Identity Server as a risk-based authentication (RBA) option:
 
-* [Installing the connector & extensions](#installing-the-connector--extensions)
+```
+Note: TypingDNA is supported with WSO2 Identity Server 5.12.0-alpha10 version onwards.
+```
+* [Enabling TypingDNA in the WSO2 Identity Server](#enabling-typingdna-in-the-wso2-identity-server)
+* [Deploying TypingDNA Artifacts](#deploying-typingdna-artifacts)
 * [Setting up the TypingDNA account](#setting-up-the-typingdna-account)
 * [Configuring the TypingDNA in WSO2 Identity Server](#configuring-the-typingdna-in-wso2-identity-server)
 * [Configuring the application to use TypingDNA](#configuring-the-application-to-use-typingdna)
 
-### Installing the connector & extensions  
-
-#### Adding plugins to authentication endpoint.
-
-1. Download the TypingDNA connector and other required artifacts from the [WSO2 store](https://store.wso2.com/store/assets/isconnector/list).
-3. Copy the files inside plugins folder and paste them to `<IS-Home>/repository/deployment/server/webapps/authenticationendpoint/plugins` directory.
-4. Copy the `typing-dna.js` file to `<IS-Home>/repository/deployment/server/webapps/authenticationendpoint/js` directory.
-
-#### Enable TypingDNA in the WSO2 Identity Server.
+### Enabling TypingDNA in the WSO2 Identity Server
 
 1. Stop WSO2 Identity Server if it is already running.
 2. Add the below configuration in the `<IS-Home>/repository/conf/deployment.toml` file.
@@ -25,7 +21,7 @@ To use TypingDNA with WSO2 Identity Server, first you need to configure the auth
     enabled_features=["security.loginVerifyData.typingDNA"]
    ```
 
-#### Deploying TypingDNA Artifacts.
+### Deploying TypingDNA Artifacts
 
 You can either download the TypingDNA artifacts or build the authenticator from the source code.
 
@@ -35,10 +31,9 @@ You can either download the TypingDNA artifacts or build the authenticator from
   iii. Copy the `org.wso2.carbon.identity.conditional.auth.typingdna.functions-x.x.x.jar` file into the `<IS-Home>/repository/components/dropins` directory.   
   iv. Copy the `api#identity#typingdna#v_.war` file into the `<IS-Home>/repository/deployment/server/webapps` directory.
 
-2. To build from the source code.  
+2. To build from the source code:  
   i. Stop WSO2 Identity Server if it is already running.  
-  ii. To build the authenticator, navigate to the identity-conditional-auth-typingdna directory and execute the following 
-   command in a command prompt.  
+  ii. To build the authenticator, navigate to the identity-conditional-auth-typingdna directory and execute the following command in a command prompt:  
 
    ```
    mvn clean install
@@ -48,44 +43,73 @@ You can either download the TypingDNA artifacts or build the authenticator from
    * `api#identity#typingdna#v_.war` file is created in the `components/org.wso2.carbon.identity.conditional.auth.typingdna.api/target` 
    directory.  
 
-   * Copy the `org.wso2.carbon.identity.conditional.auth.typingdna.functions-x.x.x.jar` file into the 
-   `<IS-Home>/repository/components/dropins directory` and `api#identity#typingdna#v_.war` file into the
-   `<IS-Home>/repository/deployment/server/webapps`
+   * Copy the org.wso2.carbon.identity.conditional.auth.typingdna.functions-x.x.x.jar file into the
+     <IS-Home>/repository/components/dropins directory and the api#identity#typingdna#v_.war file into the <IS-Home>/repository/deployment/server/webapps directory.
+
+### Setting up the TypingDNA account
 
-### Setting up the TypingDNA account  
+Follow the topics given below to set up your TypingDNA account.
 
-#### Create a TypingDNA account.
+#### Create a TypingDNA account
 
-You can craete a TypingDNA account from [here](https://www.typingdna.com/clients/signup).
-Refer [this doc](files/Account%20Creation.pdf) for detailed information.
+[Create your TypingDNA account](https://www.typingdna.com/clients/signup).
+See [the instructions](files/Account%20Creation.pdf) for details.
 
-#### Configuring TypingDNA API settings.
-Skip this part if you are using developer/free TypingDNA account.
+#### Configuring TypingDNA API settings
+Skip this part if you are using a developer/free TypingDNA account.
 
-1. Login to typingdna with your account and Configure the following.
-2. Enable the Auto-Enroll & Enable Force Initial Enrollments & Update Settings.
+1. Login to typingdna with your account and configure the following.
+2. Enable the **Auto-Enroll**, **Enable Force Initial Enrollments** and Update Settings.
 
-![Alt text](images/screen-shot-2.png?raw=true)
+    ![Alt text](images/screen-shot-2.png?raw=true)
 
 ### Configuring the TypingDNA in WSO2 Identity Server
 
-1. Login to console.
-2. Go to `Manage -> configurations -> other settings`
-3. Select TypingDNA Configuration.
-4. Enable TypingDNA & configure API Key, Secret. You can get the Key & Secret from TypingDNA
-   [dashboard](https://www.typingdna.com/clients/).
-   Refer [this doc](files/Sign%20In.pdf) for detailed information.
+1. Start the WSO2 Identity Server and log in to the management console using admin credentials.
+2. Go to `Identity Providers -> Resident -> Other settings -> TypingDNA Configuration`.
+4. Enable TypingDNA and configure **API Key** and **Secret**. You can get the key and secret from the TypingDNA [dashboard](https://www.typingdna.com/clients/).
+   [Learn more](files/Sign%20In.pdf).
 5. Enable Advance TypingDNA-API mode if you have pro/enterprise typingDNA account (This advance mode will allow you
-   to use TypingDNA’s advance APIs & configurations for the authentication).  
-6. Configure the region ( type eu or us ).
+   to use TypingDNA’s advance APIs and configurations for the authentication).  
+6. Configure the region ( type **eu** or **us** ).
 
-![Alt text](images/screen-shot-3.png?raw=true)
+    ![Alt text](images/screen-shot-3.png?raw=true)
 
 ### Configuring the application to use TypingDNA
 
-1. Go to `Develop -> Application` & Select the sample application you have configured.
-2. Go to `Sign-in Method`.
-3. Add `Typing-Biometric-Based` script in `templates->user`.
-   Refer [this doc](files/adaptive-script-description.md) to get detailed information about TypingDNA adaptive template.
+1. Go to `Service Providers -> List`, select the sample application you have configured, and click `Edit`.
+2. Expand `Local and Outbound Authentication Configuration` and click `Advanced Configuration`.
+3. Configure two authentication steps (2FA) in the login flow and use the Typing DNA adaptive script as shown below.
+
+    ```
+    // This script will step up 2FA authentication if the user's typing behaviour mis-match with enrolled behaviour.
+    
+    // You can use score(num 0-100), result(boolean), confidence(num 0-100), comparedPatterns in your logic to promote 
+    2nd step. Only the typingVerified.result is used in the sample script. 
+    
+    var onLoginRequest = function(context) {
+        executeStep(1, {
+            onSuccess: function (context) {
+                verifyUserWithTypingDNA(context, {
+                    onSuccess: function(context,data){
+                        // Change the definition here if you want.
+                        var userVerified = data.result;
+    
+                        // data.isTypingPatternReceived indicates whether a typing patterns is received from login portal.
+                        if (data.isTypingPatternReceived && !userVerified){
+                            executeStep(2);
+                        }
+                    },onFail: function(context,data){
+                        executeStep(2);
+                    }
+                });
+            }
+        });
+    };
+   ```
+
+    ![Alt_text](images/screen-shot-4.png?raw=true)
+    ![Alt_text](images/screen-shot-6.png?raw=true)
+    ![Alt_text](images/screen-shot-7.png?raw=true)
 
-![Alt_text](images/screen-shot-4.png?raw=true)
+    Learn more about [TypingDNA adaptive functions](files/adaptive-script-description.md).
diff --git a/docs/files/adaptive-script-description.md b/docs/files/adaptive-script-description.md
@@ -13,30 +13,25 @@ following parameters with data.
 | 4 | `data.comparedPatterns` | A number, between 1-20 indicates how many previously enrolled patterns were used to verify current typing pattern | `1` - minimum patterns<br>20 - Maximum patterns |
 | 5 | `data.isTypingPatternReceived` | A boolean, indicates whether the typing pattern was received from the user. Typing patterns may not be received from users if the admin didn’t deploy the extensions in the login page or if the end users are using the autofill option in the browser | `True` - Typing patterns has been received<br>False - Typing patterns hasn’t been received. |
 
-Parameters 2, 3, 4 are only available for the [paid typingdna subscriptions](https://www.typingdna.com/pricing.html). 
-Otherwise those values will be null.
+`data.score`, `data.confidence`, `data.comparedPatterns` are only available for the [paid typingdna subscriptions](https://www.typingdna.com/pricing.html).
+Otherwise, those values will be null.
 
 
 ### Using the parameters inside the script to verify the user
 
-In the script template provided data.result has been used to verify the user and prompt the second step. 
-Instead of that, admin can use other parameters in following ways to verify the user. Please note that below things can 
-be configured if you have [paid typingdna subscriptions](https://www.typingdna.com/pricing.html). Otherwise you can use
-the template without changing it.  
+In the provided sample script, `data.result` has been used to verify the user and prompt the second step. 
+Instead of that, you can use other parameters in the following ways to verify the user. Please note that the below 
+parameters can be configured if you have [paid typingdna subscriptions](https://www.typingdna.com/pricing.html). Otherwise, you can use
+the basic parameter used in the sample script.
 
- ![Alt text](../images/screen-shot-5.png?raw=true)
-
-1. `data.score`  
-If the score is less than a threshold, the user can be prompted to the second step.  
-   Eg :- ```var userVerified = data.score > 60;```
+1. `data.score`: If the score is less than a threshold, the user can be prompted to the second step.  
+   ```var userVerified = data.score > 60;```
 
-2. `data.confidence`  
-If the score is less than a threshold, the user can be prompted to the second step.  
-   Eg :- ```var userVerified = data.confidence > 50;```
-
-3. `data.comparedPatterns`    
-Compared patterns can be used with other other parameters to increase the security.  
-   Eg 1 :-  ```var userVerified = data.score > 60 && data.comparedPatterns > 4;```  
-   Eg 2 :-  ```var userVerified = data.result && data.comparedPatterns > 5;```
+2. `data.confidence`: If the confidence is less than a threshold, the user can be prompted to the second step.  
+   ```var userVerified = data.confidence > 50;```
+
+3. `data.comparedPatterns`: Compared patterns can be used with other parameters to increase the security.  
+   ```var userVerified = data.score > 60 && data.comparedPatterns > 4;```  
+   ```var userVerified = data.result && data.comparedPatterns > 5;```
 
 
diff --git a/docs/images/screen-shot-3.png b/docs/images/screen-shot-3.png
diff --git a/docs/images/screen-shot-4.png b/docs/images/screen-shot-4.png
diff --git a/docs/images/screen-shot-6.png b/docs/images/screen-shot-6.png
diff --git a/docs/images/screen-shot-7.png b/docs/images/screen-shot-7.png