From 1fa47d7a932d75fc871a6216c8371770cf92c80c Mon Sep 17 00:00:00 2001
From: Francesco Bartoli <xbartolone@gmail.com>
Date: Sun, 25 Feb 2024 19:07:58 +0000
Subject: [PATCH] Add content to tutorials

---
 docs/getting-started.md |  1 +
 docs/tutorials.md       | 35 ++++++++++++++++++++++++++++++++---
 mkdocs.yml              | 28 ++++++++++++++--------------
 3 files changed, 47 insertions(+), 17 deletions(-)
 create mode 100644 docs/getting-started.md

diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..69a5d54
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1 @@
+# Getting started
diff --git a/docs/tutorials.md b/docs/tutorials.md
index 2608b1c..bcbbbbe 100644
--- a/docs/tutorials.md
+++ b/docs/tutorials.md
@@ -1,14 +1,43 @@
 # Tutorials
 
-## Configure Authentication
+## Authentication and Authorization
+
+!!! tip "Familiarize with the topic"
+    If you don't have prior experience with the topic, we recommend reading [Authentication and Authorization in Applications](https://www.permit.io/blog/authentication-vs-authorization), which is a really good introduction on the difference between Authentication and Authorization that helps you understand how they focus on two different purposes.
+
+This tutorial aims to guide the user to configure **fastgeoapi** with a mechanism that fits with your security requirements.
+The tool supports different security schemes for [OGC APIs](https://ogcapi.ogc.org/) served by [pygeoapi](https://pygeoapi.io) and allows optionally to enable a coarse or fine-grade authorization for a *collection* and the endpoints based on user needs and use cases.
+
+Supported security schemes are:
+
+- **API KEY**: mostly used for machine to machine communication where a static shared secret can be kept secured or for internal interactions among microservices;
+- **OAuth2**: commonly used for authorization to accessing resources between two systems and also for stronger machine to machine communication with external parties when a secret needs to be rotated;
+- **OpenID Connect**: It looks like very similar to OAuth2 and in fact it is built on top of that. It allows to identify and authenticate a user in mobile and Single-Page Application (SPA).
+
+!!! note "OAuth2 vs OpenID Connect"
+    It is beneficial to clarify that they serve two different purposes. [OAuth2](https://en.wikipedia.org/wiki/OAuth) is a framework for *Authorization* while [OpenID Connect](https://openid.net/developers/how-connect-works/) is a protocol for *Authentication*. If you would like to develop further the concepts then [this]() is an appropriate read.
+
+## Configure and protect pygeoapi
+
+The protection mechanisms introduced above are mutually exclusive and they apply to the whole `pygeoapi` application that is wrapped by *fastgeoapi*.
+The configuration happens in the `.env` file where the environment variables for development and production are defined. As explained in the [getting-started](getting-started.md) section their prefix identifies the target environment (i.e. `DEV_` vs `PROD_`). Let's go through the different mechanisms.
+
+Please make sure to have cloned the [repo](https://github.com/geobeyond/fastgeoapi) before starting the following section.
 
 ### API KEY
+
 TBD
 
 ### OAuth2
-TBD
 
-## Configure Authorisation
+TBD
 
 ### OpenID Connect
+
+TBD
+
+## Configure a coarse or fine-grained authorization
+
+### Policies as code
+
 TBD
diff --git a/mkdocs.yml b/mkdocs.yml
index 422f145..7f5b894 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -54,20 +54,20 @@ extra:
     - icon: fontawesome/brands/linkedin
       link: https://www.linkedin.com/company/geobeyond
 
-      markdown_extensions:
-        - pymdownx.highlight:
-            anchor_linenums: true
-        - pymdownx.inlinehilite
-        - pymdownx.snippets
-        - admonition
-        - pymdownx.arithmatex:
-            generic: true
-        - footnotes
-        - pymdownx.details
-        - pymdownx.superfences
-        - pymdownx.mark
-        - attr_list
-        - pymdownx.emoji
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - admonition
+  - pymdownx.arithmatex:
+      generic: true
+  - footnotes
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.mark
+  - attr_list
+  - pymdownx.emoji
 
 copyright: |
   &copy; Copyright 2024 <a href="https://github.com/geobeyond">Geobeyond team</a>.