Commit fe763606 authored by ale's avatar ale

Add sso-proxy documentation to the README

parent 347348a9
Pipeline #2734 passed with stages
in 4 minutes and 24 seconds
......@@ -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:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment