Merge pull request #184 from geopython/security-admin-api

add sections on security and admin

Author: doublebyte1

workshop/content/docs/advanced/administration.md

@@ -0,0 +1,29 @@
+---
+title: Administration
+---
+
+# Administration
+
+## Overview
+
+pygeoapi provides an administration API (see the pygeoapi [documentation](https://docs.pygeoapi.io/en/latest/admin-api.html) for more information on how to enable, configure and use) in support of managing its configuration.  The API (not an OGC API) is implementated as a RESTful service to help create, update, replace or delete various elements of pygeoapi configuration.  A simple read-only UI is implemented as part of the admin API.
+
+## User interface
+
+By design, pygeoapi does not provide a true user interface to administer the configuration.  Given that the admin API exists, a few options can be considered for developing an admin UI:
+
+- standalone
+    - simple application with no connectivity to the pygeoapi admin API
+    - built off the pygeoapi configuration [schema](https://github.com/geopython/pygeoapi/blob/master/pygeoapi/schemas/config/pygeoapi-config-0.x.yml)
+    - allows for paste of existing pygeoapi configuration
+    - allows for generating pygeoapi configuration for copy/paste into a pygeoapi deployment
+    - can be deployed anywhere (for example, GitHub Pages)
+- integrated
+    - connected application to a pygeoapi deployment
+    - built off the pygeoapi configuration [schema](https://github.com/geopython/pygeoapi/blob/master/pygeoapi/schemas/config/pygeoapi-config-0.x.yml)
+    - reads/writes a live pygeoapi configuration via the pygeoapi admin API (access controlled)
+    - deployed as part of a Docker Compose application
+
+!!! note
+
+    Have your own idea for a pygeoapi admin UI?  Connect with the [pygeoapi community](https://pygeoapi.io/community) to discuss your idea!

workshop/content/docs/advanced/inspire.md

@@ -35,8 +35,8 @@ recommendation and the relevant Good Practices.
 | Discovery service                | CSW    | OGC API - Records                   | [In preparation](https://github.com/INSPIRE-MIF/gp-ogc-api-records) |
 | View service                     | WM(T)S | OGC API - Maps / OGC API - Tiles     | Not scheduled<br> [In preparation](https://wikis.ec.europa.eu/display/InspireMIG/69th+MIG-T+meeting+2022-04-01) |
 | Download service - Vector        | WFS    | OGC API - Features                  | [Adopted](https://github.com/INSPIRE-MIF/gp-ogc-api-features) |
-| Download service - Coverage      | WCS    | OGC API - Coverages / STAC        | Not scheduled<br> [In preparation](https://github.com/INSPIRE-MIF/gp-stac) | 
-| Download service - Sensor        | SOS    | OGC API - EDR / Sensorthings API [^1]  | Not scheduled<br> [Adopted](https://github.com/INSPIRE-MIF/gp-ogc-sensorthings-api) |
+| Download service - Coverage      | WCS    | OGC API - Coverages / STAC [^1]       | Not scheduled<br> [In preparation](https://github.com/INSPIRE-MIF/gp-stac) | 
+| Download service - Sensor        | SOS    | OGC API - EDR / Sensorthings API [^2]  | Not scheduled<br> [Adopted](https://github.com/INSPIRE-MIF/gp-ogc-sensorthings-api) |
 
 [^1]: Sensorthings API and is not an OGC API standards and is currently not supported by pygeoapi. It is listed here for completeness
 [^2]: STAC is not OGC API standard but is supported by pygeoapi

workshop/content/docs/advanced/security-access-control.md

@@ -4,15 +4,21 @@ title: Security and access control
 
 # Security and access control
 
+## Overview
+
 Security in general is a broad and complex topic, affecting the entire development lifecycle.
 It is recommended to follow security best practices during all development phases like design, coding and deployment.
 In this workshop we will focus only on API security and access control, rather than the full range of application security topics.
 
+## API security
+
+API security is the whole process to protect APIs from attacks. It is part of the more general security guidelines that are being treated in the OWASP Top Ten document. So those recommendations still apply.
+
 !!! Note "Application Security"
 
     The Open Web Application Security Project (OWASP) [Top Ten document](https://owasp.org/www-project-top-ten/) is a very good tool to ensure the bare minimum against the security risks and manage critical treats that are most likely affecting your code.
 
-API Security is the whole process to protect APIs from attacks. It is part of the more general security guidelines that are being treated in the OWASP Top Ten document. So those recommendations still apply.
+## Access control
 
 Access control is another fundamental part of the Open Web Application Security Project and addresses the Identity and Access Management (IAM) of an API.
 IAM consists of two different parts of a security flow:
@@ -25,5 +31,17 @@ These parts are usually managed by dedicated infrastructures and solutions which
 !!! Note "OpenAPI Security Specification"
 
     The OpenAPI specification has very well-defined elements for developers and adopters. The most relevant are:
-        - [Security Scheme Object](https://swagger.io/specification/#security-scheme-object) defines the security schemes that can be used by the operations. Supported schemes are *HTTP Authentication*, an *API Key*, *OAuth2*'s flows and *OpenID Connect*.
-        - [Security Requirement Object](https://swagger.io/specification/#security-requirement-object) defines the list of required security schemes to execute an operation.
+
+    - [Security Scheme Object](https://swagger.io/specification/#security-scheme-object) defines the security schemes that can be used by the operations. Supported schemes are *HTTP Authentication*, an *API Key*, *OAuth2*'s flows and *OpenID Connect*.
+    - [Security Requirement Object](https://swagger.io/specification/#security-requirement-object) defines the list of required security schemes to execute an operation.
+
+## pygeoapi considerations
+
+pygeoapi does not yet support OpenAPI security elements.  Future implementation could include generation of pygeoapi's OpenAPI document with a security configuration, or to generate from a known access control solution/application (such as [fastgeoapi](https://github.com/geobeyond/fastgeoapi) or [pygeoapi-auth](https://github.com/cartologic/pygeoapi-auth)).
+
+Direct access control implementation is not in scope for pygeoapi.  The desired approach here would be to leverage an existing solution and define/integrate the secured endpoints accordingly.  For example, fastgeoapi or pygeoapi-auth could be deployed downstream of pygeoapi, and govern access to specific endpoints (collections, items, etc.).
+
+
+!!! Note
+
+    The [pygeoapi official documentation](https://docs.pygeoapi.io/en/latest/security.html) provides the project's official status on security implementation updates, and should be visited to keep up to date with the latest status on security implementation in the project.

workshop/content/docs/advanced/semantic-web-linked-data.md

@@ -8,7 +8,7 @@ This section touches on 3 aspects of the Semantic Web:
 
 - [Search engines](#search-engines)
 - [Publish spatial data in the semantic web](#publish-spatial-data-in-the-semantic-web)
-- [Proxy to semantic web](#proxy-to-semantic-web)
+- [Proxy to semantic web](#proxy-to-the-semantic-web)
 
 ## Search engines
 

workshop/content/mkdocs.yml

@@ -30,6 +30,7 @@ nav:
         - Semantic Web and Linked Data: advanced/semantic-web-linked-data.md
         - Cloud deployment: advanced/cloud.md
         - INSPIRE support: advanced/inspire.md
+        - Administration: advanced/administration.md
         - Exercise 9 - pygeoapi as a bridge to other services: advanced/bridges.md
     - Conclusion: conclusion.md