From eb995e94935b9921fd519ebcc5f55b06f77869d0 Mon Sep 17 00:00:00 2001
From: Knut Ahlers <knut@ahlers.me>
Date: Sun, 28 Jan 2018 20:29:57 +0100
Subject: [PATCH] Add usage docs

Signed-off-by: Knut Ahlers <knut@ahlers.me>
---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/README.md b/README.md
index 8647592..189c9cf 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,64 @@
 
 This program is intended to be used within the [`ngx_http_auth_request_module`](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html) of nginx to provide a single-sign-on for a domain using one central authentication directory.
 
+## Usage
+
+You can use the `luzifer/nginx-sso` docker image to start your SSO service. On first start an example configuration will be generated and after you've changed that configuration you can start the container:
+
+```
+# docker run -d -p 127.0.0.1:8082:8082 -v /data/sso-config:/data luzifer/nginx-sso
+```
+
+After you did this you need to configure your nginx to use the SSO service:
+
+```nginx
+server {
+  listen        443 ssl;
+  server_name   kibana.hub.luzifer.io;
+
+  ssl_certificate     /data/ssl/certs/luzifer.io.pem;
+  ssl_certificate_key /data/ssl/certs/luzifer.io.key;
+
+  # Redirect the user to the login page when they are not logged in
+  error_page 401 = @error401;
+
+  location / {
+    # Protect this location using the auth_request
+    auth_request /sso-auth;
+
+    ## Optionally set a header to pass through the username
+    #auth_request_set $username $upstream_http_x_username;
+    #proxy_set_header X-User $username;
+
+    proxy_pass http://127.0.0.1:1720/;
+  }
+
+  location /sso-auth {
+    # Do not allow requests from outside
+    internal;
+    # Access /auth endpoint to query login state
+    proxy_pass http://127.0.0.1:8082/auth;
+    # Do not forward the request body (nginx-sso does not care about it)
+    proxy_pass_request_body off;
+    proxy_set_header Content-Length "";
+    # Set custom information for ACL matching: Each one is available as
+    # a field for matching: X-Host = x-host, ...
+    proxy_set_header X-Original-URI $request_uri;
+    proxy_set_header X-Host $http_host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Application "kibana";
+  }
+
+  # Define where to send the user to login and specify how to get back
+  location @error401 {
+    # Another server{} directive also proxying to http://127.0.0.1:8082
+    return 302 https://login.luzifer.io/login?go=$scheme://$http_host$request_uri;
+  }
+}
+```
+
 ## Configuration
 
 The configuration is mainly done using a YAML configuration file. Some options are configurable through command line flags and can be looked up using `--help` flag.
@@ -55,6 +113,8 @@ listen:
   port: 8082
 ```
 
+Pay attention if you are running the docker container you need to change the IP to `0.0.0.0` to expose the port in the container. If you miss this the service will not be available.
+
 ### Main configuration: ACL
 
 The rules of the ACL are the most complex part of the configuration and you should take your time to make this bullet-proof. If you mess up you're probably are getting complaints from your users because the default policy applied is to `deny` all access. So in the end you are configuring a white-list here.