Revise docs (#176)

* anubis logo * Update RELEASE_NOTES.md * lint md * use orion ld (still with ngsi v2 calls) * update diagramms * clean docs * Update mkdocs.yml * update indentation to 4 for listing * fix identation * finalise api documentation * lint * Update open api specs * docs updates * revert logo position * autopep8 action fixes (#179) Co-authored-by: chicco785 <[email protected]> * remove TODO * Update open api specs * update test to new policy path * update middleware api spec docs * remove term of service lines * fix index name * prepare 0.6 release * use new demo set-up including tenant creation in keycloak Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
orchestracities · Oct 31, 2022 · 80685c1 · 80685c1
1 parent d7a7e7f
commit 80685c1
Show file tree

Hide file tree

Showing 23 changed files with 865 additions and 10,676 deletions.
diff --git a/.env b/.env
@@ -5,7 +5,7 @@ VALID_AUDIENCE=ngsi
 REACT_APP_URI=http://localhost:3000/
 REACT_APP_ANUBIS_API_URL=http://localhost:8085/
 REACT_APP_CONFIGURATION_API_URL=http://localhost:4000/configuration
-REACT_APP_OIDC_ISSUER=http://localhost:8080/realms/default
+REACT_APP_OIDC_ISSUER=http://keycloak:8080/realms/default
 REACT_APP_OIDC_CLIENT=configure
 REACT_APP_OIDC_SCOPE="openid profile email"
 MONGO_DB=mongodb://mongo:27017/graphql

diff --git a/.github/lint/config.json b/.github/lint/config.json
@@ -1,5 +1,6 @@
 {
   "default": true,
+  "MD007": { "indent": 4 },
   "MD024": {
     "siblings_only": true
   },

diff --git a/.github/workflows/openapi-spec.yml b/.github/workflows/openapi-spec.yml
@@ -30,13 +30,15 @@ jobs:
           openapi-markdown -i open-api-spec/api-manager/openapi.json -o docs/user/walkthrough.md
           sed -i '1 i\
           <!-- markdownlint-disable -->' docs/user/walkthrough.md
-      - name: Generate walktrhough
+      - name: Generate walktrhough middleware
         working-directory: .
         run: |
           npm install -g openapi-markdown
           openapi-markdown -i open-api-spec/middleware/openapi.json -o docs/user/walkthrough-middleware.md
           sed -i '1 i\
           <!-- markdownlint-disable -->' docs/user/walkthrough-middleware.md
+          sed -i '/null/d' docs/user/walkthrough-middleware.md
+          sed -i '/### Terms of service/d' docs/user/walkthrough-middleware.md 
       - name: Commit changes
         uses: stefanzweifel/git-auto-commit-action@v4
         with:

diff --git a/README.md b/README.md
@@ -13,7 +13,8 @@ Welcome to Anubis!
 
 ## What is the project about?
 
-Anubis is a flexible Policy Enforcement solution
+<img src="docs/logo.jpg" alt="Anubis" style="float: left; margin-right: 10px;"
+width="200"/> Anubis is a flexible Policy Enforcement solution
 that makes easier to reuse security policies across different services,
 assuming the policies entail the same resource.
 In short we are dealing with policy portability :)  What do you mean by that?
@@ -157,20 +158,20 @@ There are two distribution modalities:
 - *public*, i.e. when the different middleware belong to different
   organisations in the public internet. In this case:
 
-  - resources are considered to be univocally identifiable (if they have
+    - resources are considered to be univocally identifiable (if they have
     the same id they are the same resource);
 
-  - only user specific policies are distributed;
+    - only user specific policies are distributed;
 
-  - only resource specific policies are distributed.
+    - only resource specific policies are distributed.
 
 - *private*, i.e. when the different middleware belong to the same
   organisation. In this case:
 
-  - resources are considered to be univocally identifiable only within the same
+    - resources are considered to be univocally identifiable only within the same
     service and service path;
 
-  - all policies are distributed (including the ones for roles and groups and
+    - all policies are distributed (including the ones for roles and groups and
     `*` and `default` resource policies).
 
 ## Policies
@@ -238,6 +239,19 @@ To run this demo you'll need to have the following installed:
 
 ### Deployment
 
+To be able to create tenants, the hostname of the token issuer (Keycloak) in
+docker and in your local system, needs to be the same, to ensure that,
+add the following entry in your `/etc/hosts`:
+
+```console
+127.0.0.1       keycloak
+```
+
+> **NOTE**: If you don't want to edit your `/etc/hosts` and you are not
+interested in testing tenant creation and deletion, in the `.env` file replace
+`REACT_APP_OIDC_ISSUER=http://keycloak:8080/realms/default` with
+`REACT_APP_OIDC_ISSUER=http://localhost:8080/realms/default`.
+
 To deploy the demo that includes the Auth API, OPA, Keycloak, and a Context
 Broker, run the following script:
 
@@ -247,6 +261,8 @@ $ cd scripts
 $ ./run_demo.sh
 ```
 
+You can now login with username `[email protected]` and password `admin`.
+
 You can run a script to make a few test API calls. You can run the test
 script with:
 
@@ -404,7 +420,8 @@ Error Set:
 
 As of today, Anubis introduces an average overhead of 69msec,
 while this is not a bad number, it's not impressive. Still
-there is a very good news, we know how to improve :) See #14.
+there is a very good news, we know how to improve :) See
+[#14](https://github.com/orchestracities/anubis/issues/14).
 
 ## Test rego
 

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,6 +1,6 @@
 # Anubis Release Notes
 
-## 0.6-dev
+## 0.6
 
 ### New features
 
@@ -12,6 +12,8 @@
 
 ### Documentation
 
+- Revise docs (including logo)
+
 ### Continuous Integration
 
 ### Technical debt

diff --git a/anubis-management-api/README.md b/anubis-management-api/README.md
@@ -47,9 +47,9 @@ The API is composed by three main paths:
     and service paths). Under the hood, this path also creates and stores
     information linked to policies:
 
-  * Agents (i.e. user or user groups definitions);
+    * Agents (i.e. user or user groups definitions);
 
-  * Modes (i.e. type of action requested on the resource);
+    * Modes (i.e. type of action requested on the resource);
 
 * `/v1/audits` providing audit logs, i.e. reports of policies' evaluations.
 

diff --git a/anubis-management-api/anubis/policies/routers.py b/anubis-management-api/anubis/policies/routers.py
@@ -214,6 +214,8 @@ def read_modes(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)):
     },
 }
 
+# TODO if no token, we should return policies for foaf:Agent!
+
 
 @router.get("/me",
             response_model=List[schemas.Policy],
@@ -242,9 +244,8 @@ def my_policies(
       - Agent Type
       - Resource
       - Resource Type
-    In case an JWT token is passed over, user id, roles and groups are used to
-    filter policies that are only valid for him.
-    # TODO if no token, we should return policies for foaf:Agent!
+    Requires a JWT token: contained user id, roles and groups are used to
+    filter policies that are only valid for the user.
     To return policies from a service path tree, you can used the wildchar "#".
     For example, using `/Path1/#` you will obtain policies for all subpaths,
     such as: `/Path1/SubPath1` or `/Path1/SubPath1/SubSubPath1`.
@@ -325,8 +326,8 @@ def read_policies(
       - Agent Type
       - Resource
       - Resource Type
-    In case an JWT token is passed over, user id, roles and groups are used to
-    filter policies that are only valid for him. Unless the user is super admin or tenant admin.
+    In case an JWT token is passed over, user id is used to filter policies
+    where the owner is user id. Unless the user is super admin or tenant admin.
     To return policies from a service path tree, you can used the wildchar "#".
     For example, using `/Path1/#` you will obtain policies for all subpaths,
     such as: `/Path1/SubPath1` or `/Path1/SubPath1/SubSubPath1`.
@@ -340,7 +341,6 @@ def read_policies(
     elif user_info and user_info['email']:
         owner = user_info['email']
     # we don't filter policies in case super admin or tenant admin
-    # TODO CHANGE LOGIC IT SHOULD LIST POLICIES I CONTROL
     if agent_type and agent_type not in default.DEFAULT_AGENTS and agent_type not in default.DEFAULT_AGENT_TYPES:
         raise HTTPException(
             status_code=422,

diff --git a/anubis-management-api/anubis/version.py b/anubis-management-api/anubis/version.py
@@ -1 +1 @@
-ANUBIS_VERSION = '0.6.0-dev'
+ANUBIS_VERSION = '0.6.0'
diff --git a/docker-compose-middleware.yaml b/docker-compose-middleware.yaml
@@ -210,7 +210,7 @@ services:
       - envoymesh
 
   upstream-service:
-    image: fiware/orion:${ORION_VERSION:-3.3.1}
+    image: fiware/orion-ld:${ORION_VERSION:-1.1.1}
     ports:
       - "1026:1026"
     command: -logLevel DEBUG -noCache -dbhost mongo

diff --git a/docker-compose.yaml b/docker-compose.yaml
@@ -106,10 +106,10 @@ services:
       - envoymesh
 
   upstream-service:
-    image: fiware/orion:${ORION_VERSION:-3.3.1}
+    image: fiware/orion-ld:${ORION_VERSION:-1.1.1}
     ports:
       - "1026:1026"
-    command: -logLevel error -noCache -dbhost mongo
+    command: -logLevel error -dbhost mongo
     depends_on:
       - mongo
     healthcheck:

diff --git a/docs/createpolicy.png b/docs/createpolicy.png
diff --git a/docs/createresource.png b/docs/createresource.png
diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,7 @@
 # Welcome to Anubis
 
-Anubis is a flexible Policy Enforcement solution
+<img src="logo.jpg" alt="Anubis" style="float: left; margin-right: 10px;"
+width="200"/> Anubis is a flexible Policy Enforcement solution
 that makes easier to reuse security policies across different services,
 assuming the policies entail the same resource.
 In short we are dealing with policy portability :) What do you mean by that?
@@ -66,13 +67,13 @@ system for souls :)
 In the design and development of Anubis we tried to leverage different
 state-of-the-art solutions and standards:
 
-- [[W3C WAC](https://solid.github.io/web-access-control-spec/), one of the
+- [W3C WAC](https://solid.github.io/web-access-control-spec/), one of the
   reference vocabularies for expressing access control policies over web
   resources.
 - [W3C ODRL](https://www.w3.org/TR/odrl-model/), a policy expression language
   that allows representing statements about the usage of
   content and services.
-- [OAUTH2](https://oauth.net/2/)) and [OIDC](https://openid.net/connect/)
+- [OAUTH2](https://oauth.net/2/) and [OIDC](https://openid.net/connect/)
   the today reference protocols for authentication.
 - [OPA](https://www.openpolicyagent.org/) the state of the art solution
   for cloud native policy evaluation (not necessarily applied to access
@@ -208,21 +209,21 @@ There are two distribution modalities:
 - *public*, i.e. when the different middleware belong to different
   organisations in the public internet. In this case:
 
-  - resources are considered to be univocally identifiable (if they have
-    the same id they are the same resource);
+    - resources are considered to be univocally identifiable (if they have
+      the same id they are the same resource);
 
-  - only user specific policies are distributed;
+    - only user specific policies are distributed;
 
-  - only resource specific policies are distributed.
+    - only resource specific policies are distributed.
 
 - *private*, i.e. when the different middleware belong to the same
   organisation. In this case:
 
-  - resources are considered to be univocally identifiable only within the same
-    service and service path;
+    - resources are considered to be univocally identifiable only within the same
+      service and service path;
 
-  - all policies are distributed (including the ones for roles and groups and
-    `*` and `default` resource policies).
+    - all policies are distributed (including the ones for roles and groups and
+      `*` and `default` resource policies).
 
 In the public modality, subscribers are required to define the service for
 which they subscribe on a certain resource. This guarantees that policies

diff --git a/docs/logo.jpg b/docs/logo.jpg
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		ANUBIS_VERSION = '0.6.0-dev'
		ANUBIS_VERSION = '0.6.0'