Add authentication docs

Describes functions and the gateway including how to configure
the built-in gateway basic authentication.

Signed-off-by: Alex Ellis (VMware) <[email protected]>

Author: alexellis

README.md

@@ -20,4 +20,4 @@ All commits into master (or merged PRs) will appear on the front-page after bein
 
 ## mkdocs-material markdown extensions
 
-There are several markdown extensions that can be used to create special formatting. Look at the docs [here](https://squidfunk.github.io/mkdocs-material/extensions/admonition/) for all available extensions. 
+There are several markdown extensions that can be used to create special formatting. Look at the docs [here](https://squidfunk.github.io/mkdocs-material/extensions/admonition/) for all available extensions. 

docs/index.md

@@ -74,6 +74,8 @@ OpenFaaS is written in Golang and is MIT licensed - contributions are welcomed w
 
 * View the [contributing page](/community/#contribute)
 
+If you would like to contribute to the documentation site or find out more check out the [docs repo](https://github.com/openfaas/docs).
+
 ### Grafana dashboards
 
 Example of a Grafana dashboards linked to OpenFaaS showing auto-scaling live in action: [here](https://grafana.com/dashboards/3526)

docs/reference/authentication.md

@@ -0,0 +1,29 @@
+# Authentication for functions
+
+There are two main concerns for authentication for OpenFaaS: the administrative API Gateway API and the individual functions.
+
+## For the API Gateway
+
+When exposing OpenFaaS on the public internet it is important to protect the administrative API endpoints of the API Gateway.
+
+These APIs exist at:
+
+* `/system/`
+
+We recommend using basic authentication and a strong password to protect the `/system/` route, but it is not the only option. If you prefer you can use a reverse proxy project such as [Kong](https://getkong.org/docs/) to enable OAuth or a similar strategy.
+
+The API Gateway as of version 0.8.2 provides built-in basic authentication. To use it set the environmental variable `basic_auth` to true. Then create two secrets named `basic-auth-user` and `basiic-auth-password`.
+
+Once basic authentication is enabled you will need to use `faas-cli login` before using the CLI.
+
+## For functions
+
+Functions are exposed at:
+
+* `/function/`
+* `/async-function/`
+
+Functions exposed on OpenFaaS often do not need to have authentication enabled, this is because they may be responding to webhooks from an external system such as GitHub or Patreon. Neither GitHub, nor Patreon will support authenticating with OAuth or basic authentication strategies, but rely on HMAC.
+
+HMAC involves a shared symmetric secret - both parties store the key securely. The sender computes a hash of the body of the request with their symmetric key and sends this data to the receiver along with the has value in the HTTP header. The receiver then computes a hash of the body with their copy of the key and checks that this matches what the sender supplied in the HTTP header.
+

mkdocs.yml

@@ -121,10 +121,10 @@ pages:
     - Featured: ./tutorials/featured.md
   - Reference:
     - Secrets: ./reference/secrets.md
+    - Auth: ./reference/authentication.md
   - Design & Architecture:
     - Gateway: ./architecture/gateway.md
     - Watchdog: ./architecture/watchdog.md
     - Autoscaling: ./architecture/autoscaling.md
   - Contributing:
     - Get Started: ./contributing/get-started.md
-