From 653b1ecb8d1b2ba78e8c006c6cebd6f0f4954100 Mon Sep 17 00:00:00 2001
From: Dhawal Gawande <dhawal.gawande@factset.com>
Date: Thu, 25 Aug 2022 11:24:54 +0100
Subject: [PATCH] docs: add note for reuse of ConfidentialClient

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/README.md b/README.md
index 82ffb54..f930aa0 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,7 @@ import { ConfidentialClient } from '@factset/sdk-utils';
 import axios from 'axios';
 
 async function exampleRequest() {
+  // The ConfidentialClient instance should be reused in production environments.
   const confidentialClient = new ConfidentialClient('/path/to/config.json');
   const accessToken = await confidentialClient.getAccessToken();
 
@@ -52,6 +53,77 @@ async function exampleRequest() {
 exampleRequest();
 ```
 
+## Modules
+
+Information about the various utility modules contained in this library can be found below.
+
+### Authentication
+
+The [authentication module](src) provides helper classes that facilitate [OAuth 2.0](https://developer.factset.com/learn/authentication-oauth2) authentication and authorization with FactSet's APIs. Currently the module has support for the [client credentials flow](/~https://github.com/factset/oauth2-guidelines#client-credentials-flow-1).
+
+Each helper class in the module has the following features:
+
+* Accepts a `Configuration` instance that contains information about the OAuth 2.0 client, including the client ID and private key.
+* Performs authentication with FactSet's OAuth 2.0 authorization server and retrieves an access token.
+* Caches the access token for reuse and requests a new access token as needed when one expires.
+    * In order for this to work correctly, the helper class instance should be reused in production environments.
+
+#### Configuration
+
+Classes in the authentication module require OAuth 2.0 client configuration information to be passed to the constructor in the `ConfidentialClient` through a JSON-formatted file or a `ConfidentialClientConfiguration` object. Below is an example of a JSON-formatted file:
+
+```json
+{
+    "name": "Application name registered with FactSet's Developer Portal",
+    "clientId": "OAuth 2.0 Client ID registered with FactSet's Developer Portal",
+    "clientAuthType": "Confidential",
+    "owners": ["USERNAME-SERIAL"],
+    "jwk": {
+        "kty": "RSA",
+        "use": "sig",
+        "alg": "RS256",
+        "kid": "Key ID",
+        "d": "ECC Private Key",
+        "n": "Modulus",
+        "e": "Exponent",
+        "p": "First Prime Factor",
+        "q": "Second Prime Factor",
+        "dp": "First Factor CRT Exponent",
+        "dq": "Second Factor CRT Exponent",
+        "qi": "First CRT Coefficient"
+    }
+}
+```
+
+The other option is to pass in the `ConfidentialClientConfiguration` instance which is initialised as shown below:
+
+```ts
+const confidentialClientConfiguration = {
+    name: "Application name registered with FactSet's Developer Portal",
+    clientId: "OAuth 2.0 Client ID registered with FactSet's Developer Portal",
+    clientAuthType: "Confidential",
+    owners: ["USERNAME-SERIAL"],
+    jwk: {
+        kty: "RSA",
+        use: "sig",
+        alg: "RS256",
+        kid: "Key ID",
+        d: "ECC Private Key",
+        n: "Modulus",
+        e: "Exponent",
+        p: "First Prime Factor",
+        q: "Second Prime Factor",
+        dp: "First Factor CRT Exponent",
+        dq: "Second Factor CRT Exponent",
+        qi: "First CRT Coefficient"
+    }
+};
+```  
+
+If you're just starting out, you can visit FactSet's Developer Portal to [create a new application](https://developer.factset.com/applications) and download a configuration file in this format.
+
+If you're creating and managing your signing key pair yourself, see the required [JWK parameters](/~https://github.com/factset/oauth2-guidelines#jwk-parameters) for public-private key pairs.
+
 ## Contributing
 
 Please refer to the [contributing guide](CONTRIBUTING.md).