From f5ddd97e5468d0dab7fd11c464295cfbc2b86e38 Mon Sep 17 00:00:00 2001
From: Chris Wendt <chrismwendt@gmail.com>
Date: Sat, 9 Mar 2019 17:56:12 -0800
Subject: [PATCH] Add docs for HTTP basic auth

---
 README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 65 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 8765a37..73b2d55 100644
--- a/README.md
+++ b/README.md
@@ -19,14 +19,71 @@ Docker image `sourcegraph/lang-python` from Docker Hub.
 
 ### 🔐 Secure deployment 🔐
 
-We recommend deploying the language server behind an auth proxy or firewall and
-treating it like an authenticated user because anyone that connects to the
-language server can access resources such as private code that the language
-server has access to.
-
-Make sure you set `python.sourcegraphUrl` to the URL that the language
-server should use to reach Sourcegraph, which is likely different from the URL
-that end users use.
+If you have private code, we recommend deploying the language server behind an
+auth proxy (such as the example below using HTTP basic authentication in NGINX), a firewall, or a VPN.
+
+### HTTP basic authentication
+
+You can prevent unauthorized access to the language server by enforcing HTTP basic authentication in nginx, which comes with the sourcegraph/server image. At a high level, you'll create a secret then put it in both the nginx config and in your Sourcegraph global settings so that logged-in users are authenticated when their browser makes requests to the Python language server.
+
+Here's how to set it up:
+
+Create an `.htpasswd` file in the Sourcegraph config directory with one entry:
+
+```
+$ htpasswd -c ~/.sourcegraph/config/.htpasswd langserveruser
+New password:
+Re-type new password:
+Adding password for user langserveruser
+```
+
+Add a location directive the [nginx.conf](https://docs.sourcegraph.com/admin/nginx) that will route requests to the Python language server:
+
+```nginx
+...
+http {
+    ...
+    server {
+        ...
+        location / {
+            ...
+        }
+
+        location /python {
+            proxy_pass http://host.docker.internal:4288;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "Upgrade";
+
+            auth_basic "basic authentication is required to access the language server";
+            auth_basic_user_file /etc/sourcegraph/.htpasswd;
+        }
+    }
+}
+```
+
+- If you're running the quickstart on Linux, change `host.docker.internal` to the output of `ip addr show docker0 | grep -Po 'inet \K[\d.]+'`.
+- If you're using [Kubernetes](#using-kubernetes) (e.g. [deploy-sourcegraph](https://github.com/sourcegraph/deploy-sourcegraph)), change `host.docker.internal` to `lang-python`.
+
+Add these to your Sourcegraph global settings:
+
+```
+  "python.serverUrl": "ws://langserveruser:PASSWORD@host.docker.internal:7080/python",
+  "python.sourcegraphUrl": "http://host.docker.internal:7080",
+```
+
+Fill in the `PASSWORD` that you created above.
+
+- If you're running the quickstart on Linux, change `host.docker.internal` to the output of `ip addr show docker0 | grep -Po 'inet \K[\d.]+'`.
+- If you're using [Kubernetes](#using-kubernetes) (e.g. [deploy-sourcegraph](https://github.com/sourcegraph/deploy-sourcegraph)):
+  - `python.serverUrl` is the address of the Python language server from the perspective of a user's browser (e.g. https://sourcegraph.example.com/python)
+  - `python.sourcegraphUrl` is the address of the Sourcegraph instance from the perspective of the Python language server (e.g. http://sourcegraph-frontend:30080)
+
+Finally, restart the sourcegraph/server container (or nginx deployment if deployed to Kubernetes) to pick up the configuration change.
+
+After deploying the language server, unauthenticated access to `http://localhost:7080/python` (or https://sourcegraph.example.com/python) should be blocked, but code intelligence should work when you're logged in.
+
+You can always revoke the `PASSWORD` by deleting the `.htpasswd` file and restarting nginx.
 
 ### Using Docker