Document optional fine-grained permissions in market (#682)

* Creating permissions docs

* adding permissions to tutorial list

* Writting introduction

* Adding descriptions of RBAC roles

* Adding images

* RBAC instructions for the market

* Adding content for allow/deny lists

* adding allow deny list images

* Adding steps for submitting allow/ deny list changes

* Fixing spelling mistakes

* formatting h3 titles

* Fixing markdown violation issue

* Adding section - mapping roles to addresses

* Updating tutorials overview

* Minor edits

Co-authored-by: Matthias Kretschmann <m@kretschmann.io>

content/tutorials/allow-deny-lists.md

@@ -0,0 +1,41 @@
+---
+title: Allow and Deny Lists
+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). 
+
+## Setup
+
+All and deny lists are not enabled by default in Ocean Market. You need to edit the environmental variables to enable this feature in your fork of Ocean Market:
+
+- To enable allow and deny lists you need to add the following environmental variable to your .env file in your fork of Ocean Market: `GATSBY_ALLOW_ADVANCED_SETTINGS="true"`
+- Publishers in your market will now have the ability to restrict who can consume their datasets.
+
+## Usage 
+
+To use allow or deny lists you need to navigate to your data asset and click on "Advance Settings".
+
+![Advanced Settings](images/allow-deny-lists/advanced-settings.png)
+
+In order to add a user to a allow or deny list, you need to first know their ethereum address. You can then enter the address of the user into the input section and click the "ADD" button. 
+
+![Add address to allow list](images/allow-deny-lists/add-allow-list.png)
+
+To remove a user from an all or deny list you can click the cross next to their ethereum address. 
+
+![Removing a user from allow or deny list](images/allow-deny-lists/removing-allow-deny.png)
+
+Any changes you make on the advanced settings page need to be submitted and signed in a transaction. To do this, first click the "SUBMIT" button.
+
+![Submit changes to allow or deny lists](images/allow-deny-lists/submit.png)
+
+Next you will need to sign the transaction in Metamask, or the wallet of your choice. 
+
+![Sign Metamask transaction](images/allow-deny-lists/metamask-transaction.png)
+
+When the process of updating the allow or deny lists is complete you will a success message. 
+
+![Update allow or deny list success](images/allow-deny-lists/update-success.png)
+
+

content/tutorials/introduction.md

@@ -9,5 +9,6 @@ These tutorials cover:
 - Set up a marketplace
 - Run a compute-to-data environment
 - Storage setup - Azure, AWS or local
+- Fine-grained permissions
 
 

content/tutorials/permissions.md

@@ -0,0 +1,15 @@
+---
+title: Fine-Grained Permissions 
+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: 
+
+- [Role based access control server.](./rbac)
+
+- [Allow & deny lists.](./allow-deny-lists) 
+
+Neither are enabled in [Ocean Market](market.oceanprotocol.com/) but you can enable them in your own market by following the guides above. 
+
+

content/tutorials/rbac.md

@@ -0,0 +1,122 @@
+---
+title: Role-Based Access Control Server
+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. 
+
+## Roles
+
+The RBAC server defines four different roles: 
+
+- Admin
+- Publisher
+- Consumer
+- User
+
+### Admin/ Publisher
+
+Currently users with either the admin or publisher roles will be able to use the Market without any restrictions. They can publish, consume and browse datasets. 
+
+### Consumer
+
+A user with the consumer is able to browse datasets, purchase them, trade datatokens and also contribute to datapools. However, they are not able to publish datasets. 
+
+![Viewing the market without publish permission](images/rbac/without-publish-permission.png)
+
+### Users
+
+Users are able to browse and search datasets but they are not able to purchase datasets, trade datatokens, or contribute to data pools. They are also not able to publish datasets. 
+
+![Viewing the market without consume permission](images/rbac/without-consume-permission.png)
+
+### Address without a role
+
+If a user attempts to view the data market without a role, or without a wallet connected, they will not be able to view or search any of the datasets. 
+
+![Viewing the market without browse permission](images/rbac/without-browse-permission.png)
+
+### No wallet connected
+
+When the RBAC server is enabled on the market, users are required to have a wallet connected to browse the datasets.
+
+![Connect a wallet](images/rbac/connect-wallet.png)
+
+## Mapping roles to addresses 
+
+Currently the are two ways that the RBAC server can be configured to map user roles to Ethereum addresses. The RBAC server is also built in such a way that it is easy for you to add your own authorization service. They two existing methods are: 
+
+1. Keycloak
+
+If you already have a [Keycloak](https://www.keycloak.org/) identity and access management server running you can configure the RBAC server to use it by adding the URL of your Keycloak server to the `KEYCLOAK_URL` environmental variable in the RBAC `.enb` file. 
+
+2. JSON
+
+Alternatively, if you are not already using Keycloak, the easiest way to map user roles to ethereum addresses is in a JSON object that is saved as the `JSON_DATA` environmental variable in the RBAC `.env` file. There is an example of the format required for this JSON object in `.example.env`
+
+It is possible that you can configure both of these methods of mapping user roles to Ethereum Addresses. In this case the requests to your RBAC server should specify which auth service they are using e.g. `"authService": "json"` or `"authService": "keycloak"`
+
+### Default Auth service
+
+Additionally, you can also set an environmental variable within the RBAC server that specifies the default authorization method that will be used e.g. `DEFAULT_AUTH_SERVICE = "json"`. When this variable is specified, requests sent to your RBAC server don't need to include an `authService` and they will automatically use the default authorization method. 
+
+## Running the RBAC server locally
+
+You can start running the RBAC server by following these steps:
+
+1. Clone this repository:
+
+```Bash
+git clone https://github.com/oceanprotocol/RBAC-Server.git
+cd RBAC-Server
+```
+
+2. Install the dependencies:
+
+```Bash
+npm install
+```
+
+3. Build the service
+
+```Bash
+npm run build
+```
+
+4. Start the server
+
+```Bash
+npm run start
+```
+
+## Running in Docker
+
+When you are ready to deploy the RBAC server to 
+
+1. Replace the KEYCLOAK_URL in the Dockerfile with the correct URL for your hosting of [Keycloak](https://www.keycloak.org/).
+2. Run the following command to build the RBAC service in a Docker container:
+
+```Bash
+npm run build:docker
+```
+
+3. Next, run the following command to start running the RBAC service in the Docker container:
+
+```Bash
+npm run start:docker
+```
+
+4. Now you are ready to send requests to the RBAC server via postman. Make sure to replace the URL to `http://localhost:49160` in your requests.
+
+## Setting up the RBAC in the Market
+
+To use the RBAC server with the market you need to save your the URL of your RBAC server as an env within the market. 
+
+- First setup and host the Ocean role based access control (RBAC) server. Follow the instructions in the [RBAC repository](https://github.com/oceanprotocol/RBAC-Server)
+- In your .env file in your fork of Ocean Market, set the value of the `GATSBY_RBAC_URL` environmental variable to the URL of the Ocean RBAC server that you have hosted, e.g. `GATSBY_RBAC_URL= "http://localhost:3000"`
+- Users of your marketplace will now require the correct role ("user", "consumer", "publisher") to access features in your marketplace. The market will check the role that has been allocated to the user based on the address that they have connected to the market with.
+- The following features have been wrapped in the `Permission` component and will be restricted once the `GATSBY_RBAC_URL` has been defined:
+  - Viewing or searching datasets requires the user to have permission to `browse`
+  - Purchasing or trading a datatoken, or adding liquidity to a pool require the user to have permission to `consume`
+  - Publishing a dataset requires the user to have permission to `publish`
+- You can change the permission restrictions by either removing the `Permission` component or passing in a different eventType prop e.g. `<Permission eventType="browse">`.
+

data/sidebars/tutorials.yml

@@ -50,3 +50,12 @@
       link: /tutorials/amazon-s3-for-brizo/
     - title: Set Up On-Premise Storage
       link: /tutorials/on-premise-for-brizo/
+
+- group: Fine-Grained Permissions
+  items:
+    - title: Overview
+      link: /tutorials/permissions
+    - title: Role-Based Access Control
+      link: /tutorials/rbac
+    - title: Allow & Deny Lists
+      link: /tutorials/allow-deny-lists