Updated the documentation (#34)

* Fix typo

* Fix Wave 1 participants

* Update Auth details in the documentation

* Fix CR comments

docs/4-ocen_components.md

@@ -6,16 +6,16 @@ sidebar_position: 4
 
 The components of OCEN 4.0 are captured below. These include:
 
-1. **Registries:** 
-    * **Participant Registry:** Manages all participants in the platform 
-    * **Product Registry:** Manages all products in the platform
+1. **OCEN Registry:** OCEN Registry helps manage
+    * **Participant Registry:** Manages all participants on OCEN
+    * **Product Registry:** Manages all products on OCEN
     * **Product Network & Network Policies:** Manages the serving of the product via a network of participants via defined network policies
+    * **Authentication:** Enables security on the platform by providing client credentials
 
-2. **Services**
-    * **Auth service:** Enables security on the platform
-    * **Heartbeat and Analytics service:** Enables intrumentation across the loan journey and the requests for performance monitoring on the network and to drive business analytics
-    * **Credit Gurantees service:** Verifies eligibility of a borrower for a credit gurantee
+2. **Heartbeat and Analytics service** This service enables intrumentation across the loan journey and the requests for performance monitoring on the network and to drive business analytics.
 
-3. **OCEN 4.0 APIs**
+3. **Credit Gurantees service:** Verifies eligibility of a borrower for a credit gurantee with CGTMSE.
+
+4. **OCEN 4.0 APIs** API specification for the participants to communicate with each other and the OCEN components.
 
 ![OCEN Components](./_images/ocen_components.png "OCEN Components")

docs/5-ocen_registries.md

@@ -2,27 +2,27 @@
 sidebar_position: 5
 ---
 
-# Registries and Product Network
+# OCEN Registry and Product Network
 
-OCEN 4.0 introduces two separate registries - **Participant Registry** for Participants, and **Product Registry** for Products, that are maintained via SROs. All participants that serve a product do so as part of a **Product Network**.
+OCEN 4.0 introduces two separate registries - **Participant Registry** for Participants, and **Product Registry** for Products, that are maintained via SROs. These registries are accessed via a shared UI portal and are also referred together as the **OCEN Registry**. All participants that serve a product do so as part of a **Product Network**.
 
-These registries and the product network are part of the initial onboarding process onto OCEN 4.0.
+These registries and the product network are part of the initial onboarding process onto OCEN 4.0. 
 
 # Participant Onboarding
 
-All participants are onboarded to OCEN 4.0 via the participant registry. A standard onboarding process is followed for all participants, and their verification is guaranteed by SROs to ensure that new members receive an equivalent level of trust within the network.
+All participants are onboarded to OCEN 4.0 via the participant onboarding in the Participant Registry. A standard onboarding process is followed for all participants, and their verification is guaranteed by SROs to ensure that new members receive an equivalent level of trust within the network.
 
 ![Participant Registry](./_images/participant_registry.png "Participant Registry")
 
 # Product and Product Network onboarding
 
-Lender will create & manage the Product and the Loan Agent will create & manage the Product Network to serve that product. All participants in OCEN 4.0 can browse the Products and Product Networks on the Product Registry and subscribe to serve a Product via the Product Networks.
+Lender will create & manage the Product via the Product Registry and the Loan Agent will create & manage the Product Network to serve that product. All participants in OCEN 4.0 can browse the Products and Product Networks on the Product Registry and subscribe to serve a Product via the Product Networks.
 
 ![Product Registry](./_images/product_registry_and_network.png "Product Registry")
 
 # Registry access
 
-The OCEN registries will be accessed via a **UI portal**. The portal will enable registration, management and discoverability of products, participants and product networks.
+The OCEN registry will be accessed via a **UI portal**. The portal will enable registration, management and discoverability of products, participants and product networks.
 
 The OCEN 4.0 specification include APIs to programatically fetch the details of a product or a participant. These APIs can be used by the participants as part of the Loan Journey.
 

docs/7-auth_service/1-overview.md

@@ -4,42 +4,42 @@ sidebar_position: 1
 
 # Overview
 
-The Auth service performs two key elements of security on the platform:
+The OCEN 4.0 Auth APIs perform two key elements of security on the platform:
 
 1. **Identity Verification:** 
     * Ensure that all entities are properly identified. 
-    * Auth service uses OAuth 2.0 and OpenID Connect protocols for the same.
+    * Auth APIs uses OAuth 2.0 and OpenID Connect protocols for the same.
 
 2. **Integrity and Non-Repudiation:**
     * Ensure authenticity & completeness of data exchanged between entities
     * This is achieved through digital signatures
 
-All participants must register with Auth Service as client, as well as on Participant Registry with their API endpoints & public key. Each participant in the ecosystem may play the role of either being both or being one of an API provider and an API client to communicate with other modules. 
+All participants must register on the Participant Registry with their API endpoints & public key. Each participant in the ecosystem may play the role of either being both or being one of an API Provider and an API Client to communicate with other modules. 
 
 ## Sample flow
 
-Consider a sample API request in the platform from an API client to an API Provider.
+Consider a sample API request in the platform from a client participant (say Loan Agent) to a Provider participant (say Lender).
 
-1. API Clients need an [access token](./3-access_token.md) to present to the API providers, for them to authorize the calls.
-2. API providers need access to the public key of token issuing Auth Service, to validate the access token presented by an API client.
-3. API providers, upon identifying the API caller using the access token, further need access to the public key of the API caller available at the Participant Registry to verify the integrity of digitally signed request sent by API client.
-4. On similar lines to (3), API Clients, while receiving response to their requests, also need access to the API Provider’s public key to verify the digitally signed response from the API provider.
+**Client** needs to include an [access token](./3-access_token.md) in their call to present to the Provider so that Provider can authenticate and authorize the Client. Client can fetch its Auth Token from the OCEN Registry on the GenerateAccessToken API by passing in it's clientID and clientSecret.
+
+**Provider** needs access to the public key of the Client to validate the access token presented by an API client. The access token includes the participantID of the Client. If the Provider does not have the public key of the Client, the Provider can fetch the public key of the Client by calling the GetParticipantDetails API to verify the integrity of digitally signed request sent by Client.
+
+Both particpants switch roles when the Provider needs to send a response back to the Client. The details of the Secure Auth flow are described [here](./2-auth_flow.md).
 
 ![Auth API Flow](./_images/auth_api_flow.png "Auth API Flow")
 
-## Onboarding
+## Participant Onboarding
 
-1. Reach out to Participant Registry administrators using an established channel (email, slack etc.) to get on boarded onto the OCEN ecosystem with following required details:
+1. Reach out to OCEN Registry administrators using an established channel (see FAQs for details) to get on boarded onto the OCEN ecosystem with following required details:
    - Participant Type
-   - API Endpoint
+   - API Endpoint (base URL where other participants can call them)
    - Public Certificate Key
-2. **Client Id & Secret** are issued as final output of this process using the Authentication Service.
-3. Participant Registry is updated with participants details (API endpoint, Public key).
+2. **Client ID & Client Secret** are issued to the participant as final output of this process.
+3. OCEN Registry is updated with participants details (API endpoint, Public key).
 
-## Offboarding
+## Participant Offboarding
 
-1. Using an established channel (email, slack etc.) notify Participant Registry administrators to trigger the offboarding process.
-2. Client Id & Secret are deactivated and removed from the authentication service.
-3. Module API endpoint & public key entries are removed from Participant Registry.
-4. All resource mappings are removed.
+1. Using an established channel (email, slack etc.) notify OCEN Registry administrators to trigger the offboarding process.
+2. Client ID & Client Secret are deactivated and removed from the Auth component.
+3. All resource mappings are removed.
 

docs/7-auth_service/2-auth_flow.md

@@ -3,22 +3,20 @@ sidebar_position: 2
 ---
 # Secure API Calls Flow
 
-Every OCEN participant may be an API provider or an API client. In these roles:
-
-1. API Clients need an access token to present to the API providers to authorize the calls.
-2. API providers need access to the public key of token issuing OCEN Auth Service to validate the access token presented by an API client.
-3. Upon identifying the API caller using the access token, API providers need access to the public key of the API caller available at the Gateway to verify the integrity of the digitally signed request sent by the API client.
-4. Along similar lines to (3), API Clients, while receiving the response to their requests, also need access to the API Provider’s public key to verify the digitally signed response from the API provider.
+Every OCEN participant may be an API Provider or an API Client. In these roles:
+1. API Clients need an access token to present to the API Provider to authorize the calls.
+2. API Provider need access to the public key of token issuing OCEN Auth Component to validate the access token presented by an API client.
+3. Upon identifying the caller using the access token, API Provider need access to the public key of the API Client to verify the integrity of the digitally signed request sent by the API Client.
+4. Along similar lines to (3), API Client, while receiving the response to their requests, also need access to the API Provider’s public key to verify the digitally signed response from the API Provider.
 
 Following is a sample interaction between a Lender and a Loan Agent(LA), following the security guidelines mentioned here:
+1. LA obtains an access token from Auth Component by calling the GenerateAccessToken API
+2. LA fetches the endpoint location of the lender by caling the GetNetworkParticipantDetails API.
+3. LA calls the lender, attaches its access token to `Authorization` header & attaches body `Signature` header as well.
+4. Lender determines the ParticipantID of the LA from the access token
+5. Lender fetches the public key of the LA, by caling the GetNetworkParticipantDetails API
+6. Lender verifies the Signature header in the LA's request and proceeds to process the request
 
-![Secure interaction sample between Loan Agent(LA) & Lender](./_images/secure-interaction-flow.png "Secure Interaction Flow")
+When the Lender responds back to LA, its includes own access token and response body `Signature` header attached as done by LA in steps 1-3. Similarly upon receiving the same from the Lender, LA fetches the public key of the Lender, verifies if the request is valid as done by Lender in Steps 4-5.
 
-1. Loan Agent(LA) obtains an access token from Auth Service
-    1. Uses the access token to fetch endpoint location of the lender(s).
-2. Loan Agent(LA) call lender(s), attaches the access token to `Authorization` header & attaches body `Signature` header as well.
-3. Lender, fetches two keys, to validate incoming requests: 
-    1. Public key of the Auth service to verify the Authorization header
-    2. Public key of the Loan Agent(LA), registered on the Gateway, to verify the Signature header.
-4. Respond back to Loan Agent(LA), with response body `Signature` header attached.
-5. Loan Agent(LA), fetches public key of the lender from gateway & processes the request if valid.
+![Secure interaction sample between Loan Agent(LA) & Lender](./_images/secure-interaction-flow.png "Secure Interaction Flow")

docs/7-auth_service/3-access_token.md

@@ -3,7 +3,7 @@ sidebar_position: 3
 ---
 # Access Token
 
-The Auth Service provides the dynamic and short-lived access token to each API client in the ecosystem. These access tokens are formatted as [JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519) (JWT). Each JWT is digitally signed by the Auth Service, as the issuer of the token. The digitally-signed access token is inserted into API authorization headers by the API client, as its identity token, for every call made to any API provider in the ecosystem.
+The Auth Component provides dynamic and short-lived access token to each API Client in the ecosystem. These access tokens are formatted as [JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519) (JWT). Each JWT is digitally signed by the Auth Service, as the issuer of the token. The digitally-signed access token is inserted into API authorization headers by the API client, as its identity token, for every call made to any API provider in the ecosystem.
 
 JWTs are issued with a lifespan of 24 hours. So, all ecosystem API clients are expected to refresh their tokens every 24 hours.
 

docs/7-auth_service/4-message_signing.md

@@ -4,7 +4,7 @@ sidebar_position: 4
 # Message Signing
 
 While the authentication mechanism of associating an incoming request with a set of identifying credentials 
-is provided by the Auth Service. To provide the integrity and **non-repudiation**, whereby both parties (i.e., API Consumer & Provider) can assure themselves that the request and responses have originated by the private key holder and no message tampering has occurred somewhere in the connection, all requests must be digitally signed by the API consumer and all responses likewise must be signed by the API provider.
+is provided by the Auth Service. To provide the integrity and **non-repudiation**, whereby both parties (i.e., API Client & Provider) can assure themselves that the request and responses have originated by the private key holder and no message tampering has occurred somewhere in the connection, all requests must be digitally signed by the API consumer and all responses likewise must be signed by the API provider.
 
 > SSL/mTLS (mutual TLS) provides an additional layer of security for data in transit. Such layered security approach ensures that each defense component has a backup to counter any flaws or gaps in the security.