Docs

README.md

@@ -5,7 +5,24 @@
 [![Tests](https://github.com/codemicro/datasette-auth-headers/actions/workflows/test.yml/badge.svg)](https://github.com/codemicro/datasette-auth-headers/actions/workflows/test.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/codemicro/datasette-auth-headers/blob/main/LICENSE)
 
-Authenticate a Datasette instance using headers set by an upstream proxy
+*Authenticate a Datasette instance using headers set by an upstream proxy*
+
+---
+
+This plugin is designed to work when Datasette is being run behind a reverse proxy, such as [Caddy](https://caddyserver.com), that is performing authentication on behalf of the app and setting headers in the upstream request. 
+
+For example, when Caddy and [Authentik's proxy provider](https://docs.goauthentik.io/docs/add-secure-apps/providers/proxy/) are used together with a configuration like so:
+
+```
+example.com {
+  forward_auth * authentik {
+    // ...
+  }
+  reverse_proxy datasette
+}
+```
+
+Authentik will set [a number of headers](https://docs.goauthentik.io/docs/add-secure-apps/providers/proxy/#headers) in the upstream request, such as `X-Authentik-User`, to inform us who is authenticated. This plugin uses those headers to create a Datasette actor.
 
 ## Installation
 
@@ -15,7 +32,19 @@ datasette install datasette-auth-headers
 ```
 ## Usage
 
-Usage instructions go here.
+You must configure this plugin on the global level within Datasette. An example configuration that reads the `X-Authentik-User` header and uses it as the actor ID is:
+
+```json
+{
+  "plugins": {
+    "datasette-auth-headers": {
+      "id-header-name": "X-Authentik-User"
+    }
+  }
+}
+```
+
+`id-header-name` is case-insensitive and is the only configuration option at this time.
 
 ## Development