From c23ecb250fb437dff1f0404fdc34ff06b8c12c5b Mon Sep 17 00:00:00 2001
From: Conrad <conrad.leonard@hotmail.com>
Date: Fri, 11 Nov 2016 07:36:11 +1000
Subject: [PATCH] Doc section on "security by sysadmin" (#1653)

* * section on "security by sysadmin"

* * changes as discussed in
* https://github.com/broadinstitute/cromwell/pull/1653

* * Move security section to separate SecurityRecommendations.md doc

* * fix TOC
---
 README.md                  | 10 +++++++++
 SecurityRecommendations.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 SecurityRecommendations.md

diff --git a/README.md b/README.md
index 9d2b37e6d..e1a82db33 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,7 @@ A [Workflow Management System](https://en.wikipedia.org/wiki/Workflow_management
   * [Workflow Submission](#workflow-submission)
   * [Database](#database)
   * [SIGINT abort handler](#sigint-abort-handler)
+* [Security](#security)
 * [Backends](#backends)
   * [Backend Filesystems](#backend-filesystems)
     * [Shared Local Filesystem](#shared-local-filesystem)
@@ -64,6 +65,9 @@ A [Workflow Management System](https://en.wikipedia.org/wiki/Workflow_management
 * [Logging](#logging)
 * [Workflow Options](#workflow-options)
 * [Call Caching](#call-caching)
+  * [Configuring Call Caching](#configuring-call-caching)
+  * [Call Caching Workflow Options](#call-caching-workflow-options)
+  * [Local Filesystem Options](#local-filesystem-options)
 * [REST API](#rest-api)
   * [REST API Versions](#rest-api-versions)
   * [POST /api/workflows/:version](#post-apiworkflowsversion)
@@ -324,6 +328,12 @@ system {
 
 Or, via `-Dsystem.abort-jobs-on-terminate=true` command line option.
 
+# Security
+
+ - Cromwell is NOT on its own a security appliance!
+ - Only YOU are responsible for your own security! 
+ - Some recommendations and suggestions on security can be found in the [SecurityRecommendations.md](SecurityRecommendations.md) document
+
 # Backends
 
 A backend represents a way to run the user's command specified in the `task` section.  Cromwell allows for backends conforming to
diff --git a/SecurityRecommendations.md b/SecurityRecommendations.md
new file mode 100644
index 000000000..3d980e582
--- /dev/null
+++ b/SecurityRecommendations.md
@@ -0,0 +1,51 @@
+Security
+========
+
+<!---toc start-->
+* [Firecloud](#firecloud)
+* [Security by sysadmin](#security)
+   * [Multi-tenant](#multi-tenant)
+<!---toc end-->
+
+# Firecloud
+
+TODO
+
+# Security by sysadmin
+__Warning!__
+
+__This section is community-contributed. It is intended as helpful guidance only, and is not endorsed by the Broad Institute.__
+
+Cromwell running in server mode accepts all connections on the configured webservice port. The simplest way to restrict access is by putting an authenticating proxy server in between users and the cromwell server:
+ 1. Configure a firewall rule on the cromwell server host to deny access to the webservice port (e.g. 8000) from all addresses except a secure proxy host.
+ 1. Configure `<YourFavoriteWebProxy>` on the proxy host with `<YourFavoriteAuthMechanism>`, to proxy authenticated traffic from the world to the cromwell server. Using Apache `httpd` web server for example with basic htpassword file-based authentication, the configuration might look something like:
+
+ ```Apache
+<Location /cromwell>
+    Order deny,allow
+    Allow from all
+    AuthType Basic
+    AuthName "Password Required"
+    AuthUserFile /path/to/my/htpasswdfile
+    Require user someone someoneelse
+    ProxyPass http://101.101.234.567:8000     # address of cromwell server web service
+</Location>
+```
+
+ 1. That's it. Users now hit `http://my.proxy.org/cromwell` with authenticated requests, and they're forwarded to port 8000 on the cromwell server host.
+
+## Multi-tenant
+The above scheme extends easily to multiple cromwell instances, for use by different groups within an organization for example. If the instances are running on the same host then each instance should be run as its own dedicated service account user, e.g. `cromwell1`, `cromwell2` etc. so that processes running under one cromwell instance cannot access the files of another; different webservice ports must also be configured. If persistent database storage is being used then each instance should be configured with its own database and database user. The proxy configuration above is extended simply by adding another `Location`:
+
+```Apache
+<Location /cromwell1>
+    Order deny,allow
+    Allow from all
+    AuthType Basic
+    AuthName "Password Required"
+    AuthUserFile /path/to/my/htpasswdfile1
+    Require user stillanotherperson andanother
+    ProxyPass http://101.101.234.567:8001
+</Location>
+```
+