Merge pull request #65 from opengeospatial/issue-43

add section on security (#43)

workshop/content/docs/index.md

@@ -19,12 +19,10 @@ These Standards are being constructed as "building blocks" that can be used to a
     <tr>
         <td><a href="https://noc.social/@doublebyte"><img width="150" src="assets/images/joana-profile.jpeg"/></a></td>
         <td><a href="https://twitter.com/tomkralidis"><img width="150" src="https://avatars.githubusercontent.com/u/910430?v=4"/></a></td>
-        <td><a href="https://twitter.com/krishnaglodha"><img width="150" src="https://avatars.githubusercontent.com/u/47075664?v=4"/></a></td>
     </tr>
     <tr>
         <td><a href="https://github.com/doublebyte1">Joana Simoes (OGC)</a></td>
         <td><a href="https://github.com/tomkralidis">Tom Kralidis (OSGeo)</a></td>
-        <td><a href="https://github.com/krishnaglodha">Krishna Lodha (Rotten Grapes)</a></td>
     </tr>
 </table>
 

workshop/content/docs/security.md

@@ -0,0 +1,80 @@
+---
+title: Security and OGC APIs
+---
+
+# Security and OGC APIs
+
+OGC APIs are designed using modern technologies in order to lower the barrier to geospatial data, services, and processes.
+
+## SSL/TLS
+
+OGC APIs can be deployed using HTTP or HTTPS.  It is strongly recommended to deploy any services using HTTPS so that clients
+can validate and verify authenticity of your services accordingly.  Depending on how your system is architected, this may mean
+applying Secure Sockets Layer/Transport Layer Security (SSL/TLS) on your service host, or if you have a multi-layered deployment
+architecture, applying as part of your front-end services, at which point internal/inner communication may or may not be implemented
+using HTTP.
+
+## Access control
+
+Open Standards and APIs are not only for Open Data.  Implementing access control (authentication, authorization) is a critical component
+of many infrastructures and systems in order to maintain data integrity, authority and trust.  Examples of requiring access control in
+OGC APIs includes (but is not limited to):
+
+- securing all endpoints
+- securing only specific endpoints
+- allowing insert/update/delete capabilities on items in a collection
+- allowing insert/update/delete capabilities on collections
+
+Given that access control concerns, implementations and architectures exist for many domains, it is best to leverage industry standards
+for implementation.  Given OGC API standards leverage the OpenAPI specification for service descriptions, one can use the OpenAPI
+[Security Scheme Object](https://spec.openapis.org/oas/v3.0.3#security-scheme-object) to describe (not implement!) the access control mechanism(s) for the
+entire API as well as for a specific path/operation of the API.
+
+Supported OpenAPI security schemes include:
+
+- API key (`apiKey`)
+- HTTP authentication (`http`)
+- OAuth2 common flows (`oauth2`)
+- OpenID Connect Discovery (`openIdConnect`)
+
+
+Access control using HTTP Basic authentication:
+```json
+"security": {
+  "default": {
+    "type": "http",
+    "scheme": "basic",
+    "description": "Please contact us for access information"
+  }
+}
+```
+
+Access control using an API key:
+```json
+"security": {
+  "default": {
+    "type": "apiKey",
+    "name": "api-key",
+    "in": "query",
+    "description": "Please see https://example.org/contact-us for more information"
+  }
+}
+```
+
+Access control using OAuth2:
+```json
+"security": {
+  "default": {
+    "type": "oauth2",
+    "authorizationUrl": "https://example.org/oauth/authorize",
+    "flow": "implicit",
+    "description": "Please see https://example.org/contact-us for more information"
+    "scopes": {
+        "read:roads": "read roads collection",
+        "write:roads": "modify roads in the roads collection"
+  }
+}
+```
+
+!!! note
+    Implementing the above assumes that the required access control mechanisms are in place.

workshop/content/mkdocs.yml

@@ -22,6 +22,7 @@ nav:
         - OGC API - Environmental Data Retrieval: api-deep-dive/environmental-data-retrieval.md
         - OGC SensorThings API: api-deep-dive/sensorthings.md
     - OGC API roadmap: roadmap.md
+    - Security: security.md
     - Transition and migration: transition-and-migration.md
     - Getting involved: getting-involved.md
     - Conclusion: conclusion.md