From 370145bebe2c2b376090ee110bae49f28ac92293 Mon Sep 17 00:00:00 2001
From: Jarno Elonen <elonen@iki.fi>
Date: Wed, 22 Feb 2023 01:45:15 +0200
Subject: [PATCH] Add config option details to README. Bump version to 0.3.0

---
 Cargo.lock       |   2 +-
 Cargo.toml       |   2 +-
 README.md        | 121 +++++++++++++++++++++++++++++++++++++++++++++++
 debian/changelog |  15 ++++++
 4 files changed, 138 insertions(+), 2 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 5eb58cc..04134f3 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -492,7 +492,7 @@ dependencies = [
 
 [[package]]
 name = "ldap_authz_proxy"
-version = "0.2.1"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "async-recursion",
diff --git a/Cargo.toml b/Cargo.toml
index 6db96eb..69639b2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "ldap_authz_proxy"
-version = "0.2.1"
+version = "0.3.0"
 edition = "2021"
 
 description = "LDAP authorization proxy for authenticated HTTP users"
diff --git a/README.md b/README.md
index e37b228..3043465 100644
--- a/README.md
+++ b/README.md
@@ -281,6 +281,127 @@ The VM running Nginx (and ldap_authz_proxy) was joined to AD domain like this:
 Script(s) for building Nginx Kerberos (SPNEGO) module for Debian:
 https://github.com/elonen/debian-nginx-spnego
 
+## Config option details
+
+Configuration options (generated by `ldap_authz_proxy --help-config`):
+
+```
+  http_path  [default: '']
+
+    Regular expression to match the HTTP path against (e.g. '^/api/v1/.*').
+    Never matched if empty. If you need to match all paths, use '^'.
+    If multiple sections match, the first one is used.
+
+
+  username_http_header  [default: 'X-Ldap-Authz-Username']
+
+    HTTP header to use for the username
+
+
+  ldap_server_url  [REQUIRED]
+
+    URL of the LDAP server (e.g. 'ldaps://ldap.example.com:636')
+
+
+  ldap_conn_timeout  [default: '10.0']
+
+    LDAP connection timeout in seconds
+
+
+  ldap_bind_dn  [REQUIRED]
+
+    DN of the LDAP user to bind as (e.g. 'CN=proxyuser,OU=users,DC=example,DC=com')
+
+
+  ldap_bind_password  [REQUIRED]
+
+    Password of the LDAP user to bind as
+
+
+  ldap_search_base  [REQUIRED]
+
+    LDAP base DN to search in (e.g. 'OU=users,DC=example,DC=com')
+
+
+  ldap_scope  [default: 'subtree']
+
+    LDAP search scope. Must be 'subtree', 'onelevel' or 'base')
+
+
+  ldap_query  [REQUIRED]
+
+    LDAP query to use. May contain '%USERNAME%', which will be quoted and replaced.
+    Example: '(&(objectClass=person)(sAMAccountName=%USERNAME%))
+
+
+  ldap_attribs  [default: 'CN']
+
+    LDAP attributes to return (e.g. 'displayName, givenName, sn, mail'). Must not be empty.
+
+
+  query_vars  [default: '']
+
+    Extra variables to use in the query, in addition to %USERNAME%.
+    You can use these to avoid repeating long query strings in different sections.
+
+    Example: 'MY_GROUP_NAME=group1, MY_USER_ATTRIB=sAMAccountName'
+    ...would turn '(&(objectClass=person)(%MY_USER_ATTRIB%=%USERNAME%)(memberOf=%MY_GROUP_NAME%))'
+    into '(&(objectClass=person)(sAMAccountName=%USERNAME%)(memberOf=group1))'
+
+
+  cache_size  [default: '512']
+
+    Maximum number of entries to cache (per section)
+
+
+  cache_time  [default: '30.0']
+
+    Maximum age of entries in the cache (in seconds)
+
+
+  attrib_delimiter  [default: ';']
+
+    Delimiter to use when concatenating multiple values of an attribute
+
+
+  deduplicate_attribs  [default: 'true']
+
+    Whether to deduplicate attribute values.
+    Example: 'someAttr=foo,bar,foo,foo' becomes 'someAttr=foo,bar')
+
+
+  set_attribs_on_success  [default: '']
+
+    Attributes to set manually if the main query succeeds.
+    If empty, only the attributes returned by LDAP queries are set.
+    Format: 'attribute=value1, attribute=value2, attribute2= ...'
+
+
+  sub_queries  [default: '']
+
+    Section names of optional sub-queries.'.
+
+    Sub-queries can check for additional conditions and/or set additional attributes.
+    See also 'sub_query_join for details.
+
+    Recursions and duplicates are removed.
+    Sub-queries are cached in the same way as the main query, and
+    caching is hierarchical: if main query is cached, sub-queries are not executed.
+
+    Format: 'extra_section_1, extra_section_2'
+
+
+  sub_query_join  [default: 'Main']
+
+    How sub-queries affect authorization.
+    Regardless of this, if any sub-query throws an LDAP error, the request is NOT authorized.
+
+    Possible values:
+     - 'Any': If main query or any sub-queries returns non-empty, request is authorized.
+     - 'All': All sub-queries must return non-empty, otherwise request is NOT authorized.
+     - 'Main': If main query authorizes, use sub-requests to add attributes.
+```
+
 ## Development
 
 Probably the easiest way to develop this is to:
diff --git a/debian/changelog b/debian/changelog
index 45e2b85..6b0dfd7 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,18 @@
+ldap_authz_proxy (0.3.0-1) unstable; urgency=low
+
+  * Rename some config options for clarity, add a few new ones
+  * Security: redact bind passwords from logs
+  * New features:
+    - Support for LDAP sub-queries
+    - Support for custom variables in LDAP queries (for shorter config)
+    - Support for adding static attributes per section
+    - Built-in help for config options
+    - Config file dump option for debugging
+    - Support quoting in config file
+    - Configurable attribute delimiter in response headers
+
+ -- Jarno Elonen <elonen@iki.fi>  Tue, 22 Feb 2023 23:14:00 +0000
+
 ldap_authz_proxy (0.2.1-1) unstable; urgency=low
 
   * Slightly optimize RAM use