ldap-rest 0.8.2 → 0.10.0

package/docs/usage/configuration.md

@@ -25,8 +25,11 @@ All LDAP-Rest configuration options.
     - [core/auth/hmac](#coreauthhmac)
     - [core/auth/llng](#coreauthllng)
     - [core/auth/openidconnect](#coreauthopenidconnect)
+    - [core/bcl](#corebcl)
   - [Authorization Plugins](#authorization-plugins)
+    - [Common to every authorization plugin](#common-to-every-authorization-plugin)
     - [core/auth/authzPerBranch](#coreauthauthzperbranch)
+    - [core/auth/authzScope](#coreauthauthzscope)
     - [core/auth/authzPerRoute](#coreauthauthzperroute)
     - [core/auth/authzLinid1](#coreauthauthzlinid1)
   - [Security Plugins](#security-plugins)
@@ -41,6 +44,7 @@ All LDAP-Rest configuration options.
   - [Utility Plugins](#utility-plugins)
     - [core/static](#corestatic)
     - [core/weblogs](#coreweblogs)
+    - [core/storage](#corestorage)
     - [core/configApi](#coreconfigapi)
 - [Configuration File](#configuration-file)
 - [LDAP Failover](#ldap-failover)
@@ -97,7 +101,7 @@ export DM_PLUGINS="core/auth/token,core/ldap/flatGeneric,core/ldap/groups"
 | `--ldap-url`                 | `--ldap-urls`    | `DM_LDAP_URL`            | `ldap://localhost`                 | LDAP server URL(s)                          |
 | `--ldap-dn`                  |                  | `DM_LDAP_DN`             | `cn=admin,dc=example,dc=com`       | Bind DN                                     |
 | `--ldap-pwd`                 |                  | `DM_LDAP_PWD`            | `admin`                            | Password                                    |
-| `--ldap-base`                |                  | `DM_LDAP_BASE`           |                                    | Base DN for searches                        |
+| `--ldap-base`                |                  | `DM_LDAP_BASE`           |                                    | Base DN for searches (required)             |
 | `--ldap-user-main-attribute` |                  | `DM_LDAP_USER_ATTRIBUTE` | `uid`                              | User identifier attribute                   |
 | `--ldap-cache-max`           |                  | `DM_LDAP_CACHE_MAX`      | `1000`                             | Max cache entries                           |
 | `--ldap-cache-ttl`           |                  | `DM_LDAP_CACHE_TTL`      | `0`                                | Search cache TTL (seconds), `0` disables it |
@@ -251,27 +255,86 @@ Empty means the plugin guards every path. Scoping several instances to different
 
 #### `core/auth/llng`
 
-| CLI          | Env           | Default                              | Description               |
-| ------------ | ------------- | ------------------------------------ | ------------------------- |
-| `--llng-ini` | `DM_LLNG_INI` | `/etc/lemonldap-ng/lemonldap-ng.ini` | LemonLDAP::NG config path |
+| CLI                      | Env                       | Default                              | Description                                                                                        |
+| ------------------------ | ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `--llng-ini`             | `DM_LLNG_INI`             | `/etc/lemonldap-ng/lemonldap-ng.ini` | LemonLDAP::NG config path                                                                          |
+| `--llng-username-header` | `DM_LLNG_USERNAME_HEADER` |                                      | Header LLNG exports with the login, published as `req.userName` (see [llng](plugins/auth/llng.md)) |
 
 #### `core/auth/openidconnect`
 
-| CLI                    | Env                     | Default | Description              |
-| ---------------------- | ----------------------- | ------- | ------------------------ |
-| `--oidc-server`        | `DM_OIDC_SERVER`        |         | OIDC server URL          |
-| `--oidc-client-id`     | `DM_OIDC_CLIENT_ID`     |         | OIDC Client ID           |
-| `--oidc-client-secret` | `DM_OIDC_CLIENT_SECRET` |         | OIDC Client Secret       |
-| `--base-url`           | `DM_BASE_URL`           |         | Public URL for callbacks |
+| CLI                     | Env                      | Default | Description                                                                             |
+| ----------------------- | ------------------------ | ------- | --------------------------------------------------------------------------------------- |
+| `--oidc-server`         | `DM_OIDC_SERVER`         |         | OIDC server URL                                                                         |
+| `--oidc-client-id`      | `DM_OIDC_CLIENT_ID`      |         | OIDC Client ID                                                                          |
+| `--oidc-client-secret`  | `DM_OIDC_CLIENT_SECRET`  |         | OIDC Client Secret                                                                      |
+| `--oidc-username-claim` | `DM_OIDC_USERNAME_CLAIM` | `sub`   | Claim naming the caller, published as `req.userName` (see [OIDC](plugins/auth/oidc.md)) |
+| `--base-url`            | `DM_BASE_URL`            |         | Public URL for callbacks                                                                |
+
+#### `core/bcl`
+
+Back-Channel Logout: a logout performed at the provider ends the session here
+on the next request. Needs `core/storage`, and refuses to start without it —
+see [Back-Channel Logout](plugins/auth/back-channel-logout.md).
+
+| CLI               | Env                | Default  | Description                 |
+| ----------------- | ------------------ | -------- | --------------------------- |
+| `--bcl-retention` | `DM_BCL_RETENTION` | `604800` | Seconds a tombstone is kept |
 
 ### Authorization Plugins
 
+#### Common to every authorization plugin
+
+| CLI                       | Env                        | Default    | Description                                                                                                                                                                                                                       |
+| ------------------------- | -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--authz-unresolved-user` | `DM_AUTHZ_UNRESOLVED_USER` | `deny`     | What an authenticated identity the plugin cannot resolve means: `deny` refuses the operation, `allow` lets it through with a warning                                                                                              |
+| `--authz-identity`        | `DM_AUTHZ_IDENTITY`        | `req.user` | Which value rules are keyed on: `req.user`, this server's identifier for the caller, or `req.userName`, the caller under a name a person would use. See [what a rule is keyed on](plugins/auth/README.md#what-a-rule-is-keyed-on) |
+| `--authz-for`             | `DM_AUTHZ_FOR`             |            | The authentication plugins, by instance name, whose requests the plugin judges; unset, every authenticated request. Meant for a plugin's own overrides: `{"authz_for":["oidc"]}`                                                  |
+| `--authz-combine`         | `DM_AUTHZ_COMBINE`         | `false`    | Let two plugins judging the LDAP operations of the same requests start together, as an AND                                                                                                                                        |
+
+`--authz-unresolved-user` is read by the plugins that resolve an identity
+before judging it — `core/auth/authzPerBranch` and `core/auth/authzLinid1`.
+`core/auth/authzPerRoute` matches the identity as it stands and
+`core/auth/authzDynamic` judges a token, so neither resolves anything and
+neither reads it. A value other than `deny` or `allow` is refused at startup.
+
+An **anonymous** request is not this case: it carries no identity, and every
+authorization plugin skips it as before. This is about a caller the
+authenticator admitted whose identity the authorization model cannot place —
+`authzLinid1` looking up a `uid` that does not exist, typically because the
+authenticator publishes something else. `allow` is the behaviour every plugin
+had before 0.8.3, and it is an open door where `authzLinid1` is loaded: see
+[the note](upgrading.md#an-identity-that-does-not-resolve-is-refused).
+
+`--authz-for` and `--authz-combine` say how plugins loaded together compose:
+without them, two plugins judging the LDAP operations of the same requests
+are refused at startup — see [several authorization
+plugins](plugins/auth/README.md#several-authorization-plugins).
+
+`--authz-for` takes one name per occurrence: repeat it
+(`--authz-for oidc --authz-for authToken`), or give the environment variable
+a list (`DM_AUTHZ_FOR="oidc authToken"`). A second word after the value —
+`--authz-for oidc authToken` — is refused rather than dropped, as it is after
+every option taking a list.
+
+`--authz-identity` is a different question, and the paragraphs above are not
+about it: `core/auth/authzPerRoute` and the SCIM base map read it as well,
+since a route rule and the base a SCIM operation is served from are keyed on
+whichever of the two names it selects. A value other than `req.user` or
+`req.userName` is refused at startup.
+
 #### `core/auth/authzPerBranch`
 
-| CLI                            | Env                             | Default                                          | Description                 |
-| ------------------------------ | ------------------------------- | ------------------------------------------------ | --------------------------- |
-| `--authz-per-branch-config`    | `DM_AUTHZ_PER_BRANCH_CONFIG`    | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON) |
-| `--authz-per-branch-cache-ttl` | `DM_AUTHZ_PER_BRANCH_CACHE_TTL` | `60`                                             | Cache TTL (seconds)         |
+| CLI                               | Env                                | Default                                          | Description                                                                                                                                                                   |
+| --------------------------------- | ---------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--authz-per-branch-config`       | `DM_AUTHZ_PER_BRANCH_CONFIG`       | `{default:{read:true,write:false,delete:false}}` | Authorization config (JSON)                                                                                                                                                   |
+| `--authz-per-branch-cache-ttl`    | `DM_AUTHZ_PER_BRANCH_CACHE_TTL`    | `60`                                             | Cache TTL (seconds)                                                                                                                                                           |
+| `--authz-filter-attached-entries` | `DM_AUTHZ_FILTER_ATTACHED_ENTRIES` | `false`                                          | Judge an attached entry by the organization it hangs off, and filter listings accordingly. Honoured by `authzPerBranch` and `authzLinid1`; does nothing under `authzDynamic`. |
+
+#### `core/auth/authzScope`
+
+| CLI                    | Env                     | Default | Description                                                                                                                                                    |
+| ---------------------- | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--authz-scope-source` | `DM_AUTHZ_SCOPE_SOURCE` |         | The plugin, by instance name, that describes a caller's scope when several judge them; unset, the first loaded. See [authz-scope](plugins/auth/authz-scope.md) |
 
 #### `core/auth/authzPerRoute`
 
@@ -384,6 +447,19 @@ Automatically creates/updates/deletes applicative account entries when users are
 
 Web access logging plugin. No configuration options - just add the plugin to enable access logs.
 
+#### `core/storage`
+
+Keyed storage with a deadline, for the plugins that need to keep something —
+see [Storage](plugins/utilities/storage.md).
+
+| CLI                           | Env                            | Default              | Description                            |
+| ----------------------------- | ------------------------------ | -------------------- | -------------------------------------- |
+| `--storage-backend`           | `DM_STORAGE_BACKEND`           |                      | `ldap` or `file`; required             |
+| `--storage-sweep-interval`    | `DM_STORAGE_SWEEP_INTERVAL`    | `600`                | Seconds between two expiry passes      |
+| `--storage-ldap-base`         | `DM_STORAGE_LDAP_BASE`         |                      | Branch the `ldap` backend writes to    |
+| `--storage-ldap-object-class` | `DM_STORAGE_LDAP_OBJECT_CLASS` | `applicationProcess` | Object class of the entries it writes  |
+| `--storage-file-directory`    | `DM_STORAGE_FILE_DIRECTORY`    |                      | Directory the `file` backend writes to |
+
 #### `core/configApi`
 
 Exposes API configuration at `/api/v1/config` for client applications. Returns available features, schemas, and endpoints. No configuration options.

package/docs/usage/plugins/README.md

@@ -21,13 +21,14 @@ LDAP entity management:
 
 Secure API access:
 
-| Plugin                 | Description                              |
-| ---------------------- | ---------------------------------------- |
-| [token](auth/token.md) | Bearer token authentication              |
-| [totp](auth/totp.md)   | TOTP authentication (time-based codes)   |
-| [hmac](auth/hmac.md)   | HMAC-SHA256 signing for backend services |
-| [llng](auth/llng.md)   | LemonLDAP::NG SSO integration            |
-| [oidc](auth/oidc.md)   | OpenID Connect / OAuth 2.0               |
+| Plugin                                             | Description                                    |
+| -------------------------------------------------- | ---------------------------------------------- |
+| [token](auth/token.md)                             | Bearer token authentication                    |
+| [totp](auth/totp.md)                               | TOTP authentication (time-based codes)         |
+| [hmac](auth/hmac.md)                               | HMAC-SHA256 signing for backend services       |
+| [llng](auth/llng.md)                               | LemonLDAP::NG SSO integration                  |
+| [oidc](auth/oidc.md)                               | OpenID Connect / OAuth 2.0                     |
+| [back-channel-logout](auth/back-channel-logout.md) | Honour a logout performed at the OIDC provider |
 
 ## Authorization Plugins
 
@@ -61,10 +62,11 @@ Connect to external systems:
 
 ## Utility Plugins
 
-| Plugin                          | Description        |
-| ------------------------------- | ------------------ |
-| [static](utilities/static.md)   | Static file server |
-| [weblogs](utilities/weblogs.md) | HTTP logging       |
+| Plugin                          | Description                   |
+| ------------------------------- | ----------------------------- |
+| [static](utilities/static.md)   | Static file server            |
+| [weblogs](utilities/weblogs.md) | HTTP logging                  |
+| [storage](utilities/storage.md) | Keyed storage with a deadline |
 
 ## Plugin Dependencies
 
@@ -79,10 +81,13 @@ core/ldap/externalUsersInGroups
 
 core/auth/authzPerBranch
   └─ requires: An authentication plugin
+
+core/bcl
+  └─ requires: core/storage (refuses to start without it)
 ```
 
 See [the complete dependencies matrix](../../plugin-development/dependencies.md).
 
 ## Load Order
 
-Authentication plugins are loaded first to secure API endpoints. The order is defined in `src/plugins/priority.json`.
+Authentication plugins are loaded first, so their middleware sits ahead of the routes it guards. The list also carries the plugins other plugins depend on, which have to be registered before the batch their consumers land in — `core/storage` is one. The order is defined in `src/plugins/priority.json`.

package/docs/usage/plugins/auth/README.md

@@ -12,6 +12,135 @@ LDAP-Rest provides multiple authentication plugins to secure API access. These p
 | [LemonLDAP::NG](llng.md)  | `core/auth/llng`          | Integration with LemonLDAP::NG SSO               |
 | [OpenID Connect](oidc.md) | `core/auth/openidconnect` | OAuth 2.0 / OpenID Connect authentication        |
 
+## What a rule is keyed on
+
+Authorization rules name a caller, and each authenticator has its own idea
+of what a caller is called. Every one of them publishes the caller twice:
+
+| Authenticator             | `req.user`                          | `req.userName`                           |
+| ------------------------- | ----------------------------------- | ---------------------------------------- |
+| `core/auth/token`         | the name given in `--auth-token`    | the same                                 |
+| `core/auth/totp`          | the name given in `--auth-totp`     | the same                                 |
+| `core/auth/hmac`          | the service name from `--auth-hmac` | the same                                 |
+| `core/auth/llng`          | LLNG's `whatToTrace`                | `--llng-username-header`, or the same    |
+| `core/auth/openidconnect` | the OIDC `sub`                      | `--oidc-username-claim` (default: `sub`) |
+| `core/auth/authzDynamic`  | the token's tenant                  | the same                                 |
+
+`req.user` is this server's identifier for the caller; `req.userName` is the
+caller under a name a person would use. `--authz-identity` says which one is
+keyed on by `core/auth/authzPerBranch`, `core/auth/authzLinid1`,
+`core/auth/authzPerRoute` and the SCIM base map — every plugin that names a
+caller in its configuration:
+
+```bash
+--authz-identity req.user        # the default: every existing rule is unchanged
+--authz-identity req.userName    # rules written on logins
+```
+
+The second is what makes a rule portable. Under OpenID Connect the `sub` is
+opaque — `auth0|…`, a UUID — so rules keyed on it have to be looked up per
+administrator and rewritten when the provider changes; keyed on
+`preferred_username` they read as the logins they are.
+
+A value other than these two is refused at startup. When the option asks for
+`req.userName` and the authenticator published none, permissions are read for
+`req.user` and a warning says so once — a rule that silently stops matching
+is worse than one that refuses.
+
+At startup each authenticator logs what it will publish, and each
+authorization plugin whose configured identities none of them can produce
+says so: token, TOTP and HMAC names are in the configuration, and an
+identity provider's claims are not, in which case the line says it cannot be
+checked before a login rather than staying silent.
+
+## Several authorization plugins
+
+Every plugin that judges LDAP operations — `core/auth/authzPerBranch`,
+`core/auth/authzLinid1`, `core/auth/authzDynamic` — registers the same hooks,
+and all of them run: loaded together, they compose as an **AND**, and the
+first refusal wins. The per-caller read filter (`ldapsearchfilter`) is one of
+those hooks: two plugins there compose as an intersection, which is the same
+AND. That is sound when it is meant. When it is not, it is a
+refusal nobody can explain: `authzPerBranch` beside `authzDynamic` judges a
+machine token by a branch configuration written for administrators, finds
+no entry for the tenant, and refuses a write the token's own ACLs grant.
+
+The AND needs no second plugin to bite. `--authz-per-branch-config` has a
+default — read everywhere, write nowhere — so a lone `authzPerBranch` judges
+**every** authenticated identity, whatever authenticated it: a token that no
+rule names reads, and every write it attempts is refused.
+
+### Whose requests a plugin judges
+
+The dispatcher records which authentication plugins vouched for a request,
+by instance name, in `req.authenticators`. An authorization plugin given
+`authz_for` judges the requests of those plugins and skips the others:
+
+```bash
+--plugin core/auth/authzDynamic
+--plugin 'core/auth/openidconnect:oidc:{"auth_path_prefix":"/api/admin"}'
+--plugin 'core/auth/authzPerBranch:authzPerBranch:{"authz_for":["oidc"]}'
+```
+
+Here the tokens are held to their own ACLs, and the administrators signed in
+through OpenID Connect to the branch configuration: no request is judged by
+both. Unset, `authz_for` means every authenticated request — what every
+plugin did before the option existed. It is read by `authzPerBranch`,
+`authzLinid1` and `authzPerRoute`; `authzDynamic` judges the requests
+carrying its own tokens, and no others, whatever the option says — an
+`authz_for` of its own there is said at startup rather than ignored in
+silence.
+
+Two cases stay apart:
+
+- a request **another** population's authenticator vouched for is skipped —
+  it is not this model's business;
+- a request of **this** population whose identity does not resolve is
+  refused — a configuration error, not an absence of one
+  (`--authz-unresolved-user`).
+
+A request carrying an identity that no authenticator vouched for is judged:
+"not mine" is never inferred from an absence. A plugin that only stepped
+aside — `authzDynamic` letting a request through on
+`--authz-dynamic-bypass` — did not vouch for it and is not recorded.
+
+### What is refused at startup
+
+- Two plugins judging LDAP operations for the same authenticator's requests
+  — two branch-level plugins with no `authz_for`, or a branch-level plugin
+  judging `authzDynamic`'s tokens — are refused, with both names, unless
+  `--authz-combine` says the AND is meant. `authzPerRoute` registers no LDAP
+  hook and is never part of it: route plus branch, and route plus token, are
+  deliberate ANDs on identities each side can name.
+- An `authz_for` naming no loaded authentication plugin is refused: the
+  plugin would judge nobody, which reads as a working configuration. A
+  server-wide `--authz-for` that no loaded plugin reads — only
+  `authzDynamic` there — is said: it scopes nothing.
+- Two plugins whose populations only meet through two authenticators on the
+  same path prefix — a request presenting both credentials is judged by
+  both — are said, not refused: asking for two credentials is a decision
+  already.
+
+A host that assembles the server itself — `registerPlugin` after `ready`,
+rather than `--plugin` — gets the same checks, as each plugin arrives: the
+refusal comes out of `registerPlugin`, before any of the plugin's routes or
+hooks exist. An arriving plugin is judged against what is already there, so
+the authentication plugins an `authz_for` or `--authz-scope-source` names
+are registered before the plugin naming them.
+
+### What the log says
+
+At startup, one line per plugin names the hooks it takes part in and whose
+requests it judges — `every authenticated request (authToken, oidc)` when
+`authz_for` is unset, so a model judging an authenticator nobody wrote it
+for is visible before a request arrives. When a hook refuses, the log line
+names the plugin that refused; the 403 body does not, as it never discloses
+the model.
+
+With two plugins combined on purpose, `--authz-filter-attached-entries` only
+broadens a listing while both honour it — both do, being built on the same
+base class, but nothing obliges a third implementation to.
+
 ## Authorization Plugins
 
 | Method                                          | Plugin                     | Description                  |

package/docs/usage/plugins/auth/authz-dynamic.md

@@ -44,6 +44,44 @@ node lib/bin/index.js \
 | `--authz-dynamic-config-attribute` | `DM_AUTHZ_DYNAMIC_CONFIG_ATTRIBUTE` | `description`  | Attribute holding the JSON ACL document                               |
 | `--authz-dynamic-tenant-attribute` | `DM_AUTHZ_DYNAMIC_TENANT_ATTRIBUTE` | `cn`           | Attribute from which `req.user` is read                               |
 | `--authz-dynamic-reload-endpoint`  | `DM_AUTHZ_DYNAMIC_RELOAD_ENDPOINT`  | `false`        | Register `POST /api/v1/authz-dynamic/reload` for manual cache refresh |
+| `--authz-dynamic-bypass`           | `DM_AUTHZ_DYNAMIC_BYPASS`           | _(empty)_      | Who may reach the directory without one of these tokens (see below)   |
+
+### Loading this plugin beside another authenticator
+
+The dispatcher runs every authentication plugin claiming a request's path,
+so a request can arrive here already identified by another one. Until 0.9.0
+this plugin stepped aside whenever that happened, and the token ACLs were
+then applied to nothing: with `core/auth/token` loaded beside it, a static
+token reached the whole directory as an unscoped administrator — or was
+refused for lacking a dynamic token, depending on which plugin had been
+registered first.
+
+The ACLs now apply to whatever token the request carries, whoever else
+identified it, and anything allowed past them without a token is named:
+
+| `--authz-dynamic-bypass` | Effect                                                                                              |
+| ------------------------ | --------------------------------------------------------------------------------------------------- |
+| _(empty, the default)_   | Nobody. A request must carry one of these tokens                                                    |
+| `any-authenticated`      | Anything another plugin authenticated — the behaviour before 0.9.0                                  |
+| `trusted-proxy`          | A request from a trusted proxy **that named a caller** (`req.trustedProxy` and `req.proxyAuthUser`) |
+| any other value          | The identity another authenticator publishes in `req.user`, e.g. a name from `--auth-token`         |
+
+Values combine: `--authz-dynamic-bypass trusted-proxy --authz-dynamic-bypass ops-admin`.
+
+`trusted-proxy` requires the proxy to have named someone. `trustedProxy`
+marks the _address_ it trusts and fills `proxyAuthUser` only when the
+request carried the authentication header it expects, so accepting the mark
+alone would hand the whole directory to every host of the `--trusted-proxy`
+range — `10.0.0.0/8` being all of it.
+
+A bypassed request carries **no** token, so no ACL is enforced on it — that
+is what a bypass is. Each one is logged at `info` with the reason that let it
+through, and a configuration loading this plugin beside another
+authenticator says so once at startup.
+
+The answer no longer depends on registration order: when the bypass names an
+identity another plugin has not published yet, the verdict waits until every
+authenticator has run.
 
 ## Token entry shape
 
@@ -148,6 +186,10 @@ ACL, the client is cryptographically constrained to its own SCIM subtree.
   deploy cleartext secrets in production.
 - **Timing**: comparisons run through `crypto.timingSafeEqual` or a buffer
   wrapper, preventing timing oracles on the secret.
+- **Composition**: loading another authenticator on the same paths means a
+  request can arrive already identified. It is still checked against the
+  token it carries; what may pass without one is `--authz-dynamic-bypass`,
+  and nothing else.
 - **Scope escape**: the authz hooks check every LDAP operation's DN against
   the token's ACL. The active token is carried via `AsyncLocalStorage`, so it
   applies even to plugins that do not thread `req` down to `ldapActions`.

package/docs/usage/plugins/auth/authz-linid1.md

@@ -60,6 +60,39 @@ No configuration file needed - permissions are read from LDAP. Simply load the p
 
 The plugin caches permissions for 5 minutes by default. This is hardcoded but can be modified in the source if needed.
 
+### The identity has to be a `uid`
+
+The plugin resolves `req.user` by searching
+`(<ldap_user_main_attribute>=<identity>)` under `--ldap-base`, so it only
+works behind an authenticator that publishes what the directory calls a user:
+
+| Authenticator             | `req.user`                       | Resolves here                          |
+| ------------------------- | -------------------------------- | -------------------------------------- |
+| `core/auth/token`         | the name given in `--auth-token` | only if that name is a `uid`           |
+| `core/auth/totp`          | the name given in `--auth-totp`  | only if that name is a `uid`           |
+| `core/auth/hmac`          | the service name                 | usually not                            |
+| `core/auth/llng`          | LLNG's `whatToTrace`             | when it traces the `uid`               |
+| `core/auth/openidconnect` | the OIDC `sub`                   | **no** — an opaque provider identifier |
+
+An identity that does not resolve is **refused** (403), and the refusal is
+logged with the plugin's name; `--authz-unresolved-user` sets it otherwise
+([notes](../../upgrading.md#an-identity-that-does-not-resolve-is-refused)).
+An identity naming **several** entries is refused (403) whatever that
+option says, and a warning gives the number of entries. A lookup the
+directory fails fails the request and is not cached.
+
+Both answers are cached for the plugin's TTL (5 minutes), negatives
+included, so a mismatch does not turn every request into a directory search.
+The TTL cuts both ways: an identity added to the directory after being
+refused waits it out, and an administrator whose **own entry is renamed or
+moved** keeps resolving to the former DN — where no organization names them,
+so their own operations are refused. A rename, a move to the trash or a
+delete performed through this server drops what was resolved; a change made
+directly in the directory waits out the TTL.
+
+`GET /api/v1/authz/scope` resolves the identity outside that cache, so
+during such a window it can describe a scope the hooks no longer grant.
+
 ## Permission Resolution
 
 For each LDAP operation, the plugin:

package/docs/usage/plugins/auth/authz-per-branch.md

@@ -174,10 +174,20 @@ Modifies the organization tree API:
 
 Groups are resolved dynamically:
 
-1. Searches for all groups where user is a member
-2. Uses wildcard DN pattern: `(member=uid={user},*)`
-3. Caches results for configured TTL (default: 60 seconds)
-4. Cache prevents repeated LDAP queries for same user
+1. Resolves the caller to its DN, searching
+   `(<ldap_user_main_attribute>=<uid>)` under the LDAP base (`--ldap-base`)
+2. Searches for all groups where that DN is a member
+3. Matches each group found against the `groups` keys **as DNs**: case and
+   the spaces around `,` and `=` do not matter, so
+   `CN=Editors, OU=Groups,dc=example,dc=com` names the same group as
+   `cn=editors,ou=groups,dc=example,dc=com`
+4. Caches results (see [Group Caching](#group-caching)); concurrent
+   requests for the same user share one lookup
+
+A uid that names **more than one** entry gets **no group rule**, since its
+groups cannot be told apart from its homonym's; a warning is logged, and the
+uid's own `users` rule still applies. A lookup that fails answers `500` and
+is not cached.
 
 ## Sub-branch Inheritance
 
@@ -379,6 +389,10 @@ Group memberships are cached to reduce LDAP queries:
 - **Configurable**: `--authz-per-branch-cache-ttl`
 - **Per-user cache**: Each user's groups cached separately
 - **Automatic expiry**: Cache entries expire after TTL
+- **Dropped on writes**: any add, delete, rename or move made through
+  ldap-rest empties the cache, and so does a modify touching the group member
+  attribute or `--ldap-user-main-attribute`. A change made directly in the
+  directory waits for the TTL
 
 Cache hit/miss logging:
 
@@ -408,11 +422,18 @@ Cache hit/miss logging:
 - **Open by default**: Set `read: true` for general access
 - Choose based on your security posture
 
+`--authz-per-branch-config` is never empty: unset, it is
+`{"default":{"read":true,"write":false,"delete":false}}`, and it applies to
+**every** authenticated identity, whatever authenticated it. Loaded beside a
+token plugin, `authzDynamic` or an identity provider whose callers no rule
+names, this plugin lets them read and refuses every write. Give it an
+`authz_for` naming the authentication plugins it was written for — see
+[several authorization plugins](README.md#several-authorization-plugins).
+
 ### Group-Based Security
 
 - Group DNs must be fully qualified
 - Group resolution uses LDAP search - ensure proper indexing
-- Cache can delay permission revocation (up to TTL duration)
 
 ### Authentication Required
 
@@ -523,7 +544,8 @@ Changed permissions don't take effect immediately.
 
 **Solutions:**
 
-1. Wait for group cache TTL to expire
+1. A membership changed directly in the directory waits for the
+   [group cache](#group-caching) TTL
 2. Restart server to clear all caches
 3. Reduce `--authz-per-branch-cache-ttl` for testing
 
@@ -534,17 +556,25 @@ User should inherit group permissions but doesn't.
 
 **Solutions:**
 
-1. Verify user is member of group:
+1. Verify the user's DN is a member of the group:
 
    ```bash
-   ldapsearch -x -b "ou=groups,dc=example,dc=com" "(member=uid=jdoe,*)"
+   ldapsearch -x -b "dc=example,dc=com" \
+     "(member=uid=jdoe,ou=users,dc=example,dc=com)"
    ```
 
-2. Check group DN in config matches LDAP exactly
+2. Check the group DN in config names the group: it is compared as a DN
+   (case and spaces are ignored), but every RDN must be there
+
+3. Check the uid names a single entry:
+
+   ```bash
+   ldapsearch -x -b "dc=example,dc=com" "(uid=jdoe)" dn
+   ```
 
-3. Ensure group membership uses correct attribute (default: `member`)
+4. Ensure group membership uses correct attribute (default: `member`)
 
-4. Configure custom member attribute if needed:
+5. Configure custom member attribute if needed:
    ```bash
    --ldap-group-member-attribute uniqueMember
    ```

package/docs/usage/plugins/auth/authz-per-route.md

@@ -107,6 +107,12 @@ one-level:GET:/api/v1/ldap/users/*
 | User authenticated but has no rules configured        | 403 Forbidden                                          |
 | User has at least one matching rule                   | 200 / pass through                                     |
 | User has rules but none match the current method+path | 403 Forbidden                                          |
+| Authenticated by a plugin outside `authz_for`         | Pass through — another population, judged elsewhere    |
+
+`authz_for` lists the authentication plugins, by instance name, whose
+requests the rules are for; unset, they apply to every authenticated
+request. See [several authorization
+plugins](README.md#several-authorization-plugins).
 
 ## Full Example