Issue 749 permissions update (#750)

* Adding introduction to permissions

* Adding addition information in intro

* Adding introducrion to RBAC server

* adding introduction to allow/ deny lists

* Adding sub titles for intro & changing titles

* Updating page titles in sidebar

* Updating page names

content/tutorials/asset-level-permissions.md

@@ -1,9 +1,16 @@
 ---
-title: Allow and Deny Lists
+title: Asset-Level Restrictions
 description: Restrict access to individual assets
 ---
 
-Allow and deny lists are advanced features that allow publishers to control access to individual data assets. Publishers can restrict assets so that they can only be accessed by approved users (allow lists) or they can restrict assets so that they can be accessed by anyone except certain users (deny lists). 
+## Introduction
+
+For asset-level restrictions Ocean supports allow and deny lists. Allow and deny lists are advanced features that allow publishers to control access to individual data assets. Publishers can restrict assets so that they can only be accessed by approved users (allow lists) or they can restrict assets so that they can be accessed by anyone except certain users (deny lists). 
+
+When an allow-list is in place, a consumer can only access the resource if they have a datatoken and one of the credentials in the "allow" list of the DDO. Ocean also has complementary deny functionality: if a consumer is on the "deny" list, they will not be allowed to access the resource. 
+
+Initially, the only credential supported is Ethereum public addresses. To be fair, it’s more a pointer to an individual not a credential; but it has a low-complexity implementation so makes a good starting point. For extensibility, the Ocean metadata schema enables specification of  other types of credentials like W3C Verifiable Credentials and more. When this gets implemented, asset-level permissions will be properly RBAC too:) 
+Since asset-level permissions are in the DDO, and the DDO is controlled by the publisher, asset-level restrictions are controlled by the publisher.
 
 ## Setup
 

content/tutorials/market-level-permissions.md

@@ -1,8 +1,13 @@
 ---
-title: Role-Based Access Control Server
+title: Market-Level Permissions
 description: Control who can publish, consume or browse data
 ---
-The primary mechanism for restricting your users ability to publish, consume, or browse is the role-based access (RBAC) control server. 
+
+## Introduction
+
+For market-level permissions, Ocean implements a role-based access control server (RBAC server). It implements restrictions at the user level, based on the user’s role (credentials). The RBAC server is run & controlled by the marketplace owner. Therefore permissions at this level are at the discretion of the marketplace owner. 
+
+The RBAC server is the primary mechanism for restricting your users ability to publish, consume, or browse assets in the market.  
 
 ## Roles
 

content/tutorials/permissions.md

@@ -4,12 +4,28 @@ description: Control who can publish, consume or browse data
 ---
 
 
-Ocean Protocol supports fine-grained permissions across our technology stack which can be particularly useful for enterprise use-cases. There are two ways in which permissions are implemented: 
+A large part of Ocean is about access control, which is primarily handled by datatokens. Users can access a resource (e.g. a file) by redeeming datatokens for that resource. We recognize that enterprises and other users often need more precise ways to specify and manage access, and we have introduced fine-grained permissions for these use cases. 
+Fine-grained permissions mean that access can be controlled precisely at two levels:
 
-- [Role based access control server.](./rbac)
+- [Marketplace-level permissions](./market-level-permissions) for browsing, consuming or publishing within a marketplace frontend.
 
-- [Allow & deny lists.](./allow-deny-lists) 
+- [Asset-level permissions](./asset-level-permissions) on consuming a specific asset.
 
-Neither are enabled in [Ocean Market](market.oceanprotocol.com/) but you can enable them in your own market by following the guides above. 
+The fine-grained permissions features are designed to work in forks of Ocean Market. We have not enabled them in Ocean Market itself, to keep Ocean Market open for everyone to use. On the front end, the permissions features are easily enabled by setting environment variables.
+
+### Introduction
+
+Some datasets need to be restricted to appropriately credentialed users. In this situation there is tension:
+
+1. Datatokens on their own aren’t enough - the datatokens can be exchanged without any restrictions, which means anyone can acquire them and access the data. 
+2. We want to retain datatokens approach, since they enable Ocean users to leverage existing crypto infrastructure e.g. wallets, exchange etc.
+
+We can resolve this tension by drawing on the following analogy:
+
+> Imagine going to an age 18+ rock concert. You can only get in if you show both (a) your concert ticket and (b) an id showing that you’re old enough. 
+
+We can port this model into Ocean, where (a) is a datatoken, and (b) is a credential. The datatoken is the baseline access control. It’s fungible, and something that you’ve paid for or had shared to you. It’s independent of your identity. The credential is something that’s a function of your identity. 
+
+The credential based restrictions are implemented in two ways, at the market level and at the asset level. Access to the market is restricted on a role basis, the user's identity is attached to a role via the role based access control (RBAC) server. Access to individual assets is restricted via allow and deny lists which list the ethereum addresses of the users who can and cannot access the asset within the DDO.
 
 

data/sidebars/tutorials.yml

@@ -57,7 +57,7 @@
   items:
     - title: Overview
       link: /tutorials/permissions
-    - title: Role-Based Access Control
+    - title: Market-Level Permissions
-      link: /tutorials/rbac
+      link: /tutorials/market-level-permissions
-    - title: Allow & Deny Lists
+    - title: Asset-Level Permissions
-      link: /tutorials/allow-deny-lists
+      link: /tutorials/asset-level-permissions