Add sso-proxy documentation to the README

README.md

@@ -102,6 +102,57 @@ associated key will be cleared either on logout, or when the login
 session expires.
 
 
+# SSO Proxy
+
+The *sso-proxy* server adds SSO authentication and access controls to
+unauthenticated backends (legacy applications, or apps that do not
+support authentication altogether).
+
+It is a straightforward reverse proxy that handles the SSO-related
+methods directly and forwards everything else unchanged to the
+backend. While it is possible to specify multiple backends for each
+endpoint, the load balancing algorithm is extremely unsophisticated:
+the proxy will simply pick a random backend on every request, without
+any tracking of whether backends are up or not (this is obviously
+improvable). Also note that the authenticated identity is **not**
+passed along to the backend: since the backends are unauthenticated,
+it wouldn't be safe for them to trust this information anyway, unless
+they have a way to ensure it comes only from the trusted sso-proxy
+(perhaps using TLS or other forms of transport verification). Finally,
+*sso-proxy* only handles incoming requests based on their Host
+attribute, not the request path.
+
+The proxy server has its own configuration file, */etc/sso/proxy.yml*
+by default, which has the following attributes:
+
+* `session_auth_key` and `session_enc_key` are secrets to be used for
+  HTTP-based sessions. For details on their syntax see the description
+  for `session_secrets` above.
+* `sso_server_url` is the URL for the login server
+* `sso_public_key_file` should point at a file containing the SSO
+  public key
+* `sso_domain` is the SSO domain
+* `backends` is the list of configured endpoints and associated
+  backends, each entry has the following attributes:
+  * `host` the HTTP host to serve
+  * `upstream` is a list of *host:port* addresses for the upstream
+    backends
+  * `tls_server_name` allows you to explicitly set the value of the
+    ServerName TLS extension on the outbound request. This is done do
+    de-couple the transport layer between proxy and backend from the
+    details of the actual HTTP request.
+  * `client_tls` specifies the client TLS configuration. If set, the
+    upstream request will use HTTPS, otherwise plain HTTP. Known
+    attributes:
+    * `cert`: path to the client certificate
+    * `key`: path to the private key
+    * `ca`: path to the CA used to validate the server
+
+Given its characteristics, the proxy is currently best suited for
+relatively low-volume, administrative applications, rather than for
+user-visible services.
+
+
 # API
 
 The *sso-server* binary serves different types of HTTP traffic: