ldap-rest 0.8.2 → 0.9.0

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

@@ -408,6 +408,14 @@ 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

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
 

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

@@ -15,20 +15,60 @@ whichever authorization plugin is in force.
 --plugin core/auth/authzScope
 ```
 
-It has no options. It answers through whichever loaded plugin carries the
-`authz` role _and_ can say who may do what where — one implementing
-`resolveUser`, `getAuthorizedBranches` and `getUserPermissions`. Both
+It answers through a loaded plugin that carries the `authz` role _and_ can
+say who may do what where — one implementing `resolveUser`,
+`getAuthorizedBranches` and `getUserPermissions`. Both
 [authz-linid1](authz-linid1.md) and [authz-per-branch](authz-per-branch.md)
 do, and this endpoint works with either without knowing which.
 
-The role alone is not enough. [authz-per-route](authz-per-route.md) gates URLs
-and [authz-dynamic](authz-dynamic.md) reads a token: both carry the `authz`
-role and implement none of those three methods, so this endpoint passes them
-over — loading one beside a branch-level plugin changes the answer not at all.
-A server whose only authorization plugin is one of those has nothing to
-describe a scope with, and the answer is the unrestricted one shown below: a
-client built on it shows every button, and a refusal, when it comes, comes from
-the route or the token rather than from the scope.
+| CLI                    | Env                     | Default | Description                                                   |
+| ---------------------- | ----------------------- | ------- | ------------------------------------------------------------- |
+| `--authz-scope-source` | `DM_AUTHZ_SCOPE_SOURCE` |         | The plugin, by instance name, that describes a caller's scope |
+
+### Which plugin answers
+
+The caller is resolved under the name the hooks key on — `req.user`, or
+`req.userName` with `--authz-identity req.userName` — so the scope described
+is the one enforced.
+
+Only a plugin that judges the caller answers for them: one scoped with
+`authz_for` to other authentication plugins is not this caller's model, and
+is passed over (see [several authorization
+plugins](README.md#several-authorization-plugins)).
+
+When more than one judges the caller — two branch-level plugins combined with
+`--authz-combine` — the hooks apply both and this endpoint can describe only
+one. `--authz-scope-source` names it. Without it, the first loaded answers,
+and for plugins outside the priority list that is import order, which nobody
+chose: the server says so at startup, and the answer lists every plugin
+judging the caller under `sources`, the one it comes from under `source`. A
+name that is not a loaded plugin able to describe a scope is refused at
+startup.
+
+### When nothing can describe the scope
+
+[authz-per-route](authz-per-route.md) gates URLs and
+[authz-dynamic](authz-dynamic.md) reads a token: both carry the `authz` role,
+neither resolves a user or a branch. When they judge the caller and no
+branch-level plugin does, no model can say what the caller may do, and the
+answer says that rather than guessing:
+
+```json
+{
+  "user": "alice",
+  "unrestricted": false,
+  "described": false,
+  "source": null,
+  "sources": ["authzPerRoute"],
+  "branches": [],
+  "entities": []
+}
+```
+
+This endpoint used to answer `unrestricted: true` with `create: true` on
+every entity there — an authorization judgement handed to a client that acts
+on it, while the route or the token refused. A client that reads an entity
+missing from `entities` as not creatable offers nothing.
 
 ## Endpoint
 
@@ -40,6 +80,9 @@ GET /api/v1/authz/scope
 {
   "user": "uid=alice,ou=users,dc=example,dc=com",
   "unrestricted": false,
+  "described": true,
+  "source": "authzLinid1",
+  "sources": ["authzLinid1"],
   "branches": [
     {
       "dn": "ou=Sales,ou=organization,dc=example,dc=com",
@@ -77,13 +120,16 @@ is where a new organization goes when the client names no parent. A local admini
 `create: false` for organizations, and creates sub-organizations under their own
 node by naming it as `parentDn`.
 
-With no authorization plugin loaded the server grants everything, and the
-answer says so:
+With no authorization plugin judging the caller the server grants
+everything, and the answer says so:
 
 ```json
 {
   "user": "alice",
   "unrestricted": true,
+  "described": true,
+  "source": null,
+  "sources": [],
   "branches": [],
   "entities": [
     { "name": "users", "base": "ou=users,dc=example,dc=com", "create": true }
@@ -93,9 +139,16 @@ answer says so:
 
 ## Errors
 
-| Status | When                                                          |
-| ------ | ------------------------------------------------------------- |
-| `401`  | No authenticated user, or a user the directory cannot resolve |
+| Status | When                                                                                        |
+| ------ | ------------------------------------------------------------------------------------------- |
+| `401`  | No authenticated user while any authorization plugin is loaded, or a user it cannot resolve |
+
+An anonymous caller is refused as soon as anything authorizes: every
+authorization plugin skips a request without an identity, so nothing would
+judge them and the answer would be `unrestricted: true` — more than an
+identified caller of the same server is told. A server loading no
+authorization plugin at all answers `unrestricted` to anyone, anonymous
+included, which is what it does.
 
 ## See also
 

package/docs/usage/plugins/auth/back-channel-logout.md

@@ -0,0 +1,86 @@
+# Back-Channel Logout
+
+Honouring a logout the provider performed elsewhere.
+
+## Overview
+
+When someone logs out at the OpenID Provider — or an administrator ends their
+sessions — the provider sends a **logout token** to every application that
+asked for one. Without it, an application keeps honouring its own cookie: the
+session stays alive until it expires on its own, which is exactly what a
+logout is supposed to prevent.
+
+`core/bcl` records what such a token killed, and `core/auth/openidconnect`
+asks, on every request, whether the session it holds is still alive.
+
+**Nothing here stores a session.** A logout token only leaves a _tombstone_
+saying that one `sid`, or every session of one `sub`, is dead. Sessions stay
+in their cookie, and the storage holds only what died — which is what keeps
+it small.
+
+## Configuration
+
+```bash
+--plugin core/auth/openidconnect \
+--plugin core/storage --storage-backend file --storage-file-directory /var/lib/ldap-rest/storage \
+--plugin core/bcl --bcl-retention 604800
+```
+
+| Option            | Environment        | Default  | Description                 |
+| ----------------- | ------------------ | -------- | --------------------------- |
+| `--bcl-retention` | `DM_BCL_RETENTION` | `604800` | Seconds a tombstone is kept |
+
+Where the marks live, and how often expired ones are reclaimed, belongs to
+[`core/storage`](../utilities/storage.md) — `core/bcl` keeps only the policy.
+
+At the provider, register the back-channel logout URI:
+
+```
+https://ldap-rest.example.com/backchannel-logout
+```
+
+## Retention
+
+A tombstone has to outlive the session it kills, or a cookie older than the
+mark would be honoured again. The default matches `express-openid-connect`'s
+own seven-day session; shorten it only alongside the session lifetime.
+
+Expiry is enforced when the mark is read, not only when the sweeper passes,
+so a late sweeper never keeps out someone who has since logged in again.
+
+## `core/bcl` Refuses to Start Without Storage
+
+`core/storage` must be loaded and `--storage-backend` set, or the plugin
+throws at startup.
+
+That is deliberate. A logout check that quietly does nothing would leave
+every session outliving the logout that closed it, and nothing would say so.
+For a feature that can be skipped, a warning is the right answer; for this
+one, a refusal to start is the honest failure.
+
+The refusal answers for the configuration, not for the order it is written
+in. `core/bcl` declares `core/storage` as a dependency, so a configuration
+naming only `core/bcl` loads the store anyway; and `core/storage` is in the
+priority list, so one that names both gets a single instance whichever comes
+first.
+
+## What a Login Forgets
+
+A mark on the `sub` kills every session of that person. Left in place it
+would also kill the sessions created _after_ it, for the whole retention —
+so a successful login clears the marks matching its own claims.
+
+This has a consequence worth knowing, which the SDK's own default shares: a
+login also revives sessions that a "log out everywhere" token killed without
+naming a `sid`.
+
+## Failures Are Not Swallowed
+
+If the store cannot record a tombstone, the provider is answered `400` rather
+than `204`. A provider retries a `400`; a `204` tells it a logout was honoured
+that nothing kept.
+
+## See Also
+
+- [Storage](../utilities/storage.md) — where the marks live
+- [OpenID Connect](oidc.md)

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

@@ -15,6 +15,35 @@ Integration with [LemonLDAP::NG](https://lemonldap-ng.org/) (LLNG) Web SSO solut
 DM_LLNG_INI="/etc/lemonldap-ng/lemonldap-ng.ini"
 ```
 
+## Rules that name nobody
+
+The plugin serves a request only when the handler named a user. A LemonLDAP::NG
+location rule set to `skip` makes the handler return at once — no session
+read, no `Lm-Remote-User` written — and such a request is refused with 401
+rather than served with no identity: every authorization plugin skips its
+check when a request carries no identity, so "no authentication on this path"
+would have become "authenticated, and scoped by nobody".
+
+Serve such a path from a virtual host this plugin does not guard, or scope
+the plugin with `auth_path_prefix` so the path falls outside it.
+
+The identity header is read whatever case the handler wrote it in, and
+whatever the client sent under that name is dropped before the handler runs:
+only the handler may name the caller.
+
+`req.user` is what `whatToTrace` traces, which is often a mail or a display
+name. `--llng-username-header` names a second header LemonLDAP::NG exports
+carrying the login, published as `req.userName`; with
+`--authz-identity req.userName`, rules are then written on logins. Export it
+from the LLNG configuration as you would any other header.
+
+Whatever the request carried under that name is dropped before the handler
+runs, exactly as the identity header is: a rule can be keyed on
+`req.userName`, so a client supplying it would otherwise take over the
+identity that rule names. The consequence is that the value must come from
+the handler — a header set by an upstream proxy does not survive, and would
+only have been trustworthy if that proxy stripped the client's copy itself.
+
 ## Prerequisites
 
 1. **LemonLDAP::NG Handler**: The `lemonldap-ng-handler` npm package (optional dependency)

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

@@ -35,6 +35,56 @@ Install the optional dependency:
 npm install express-openid-connect
 ```
 
+## Scope
+
+Like every other authentication plugin, this one registers with the server's
+authentication dispatcher, so `auth_path_prefix` says which paths it guards:
+
+```bash
+--plugin 'core/auth/openidconnect:oidc:{"auth_path_prefix":"/api/admin"}'
+```
+
+Until 0.9.0 the option was accepted and ignored — the plugin mounted its own
+middleware and guarded the whole server — and the layers it mounted kept
+their registration order, so a route plugin loading before it was served
+without a session and an authorization plugin loading after it judged rules
+before `req.user` existed. See
+[the note](../../upgrading.md#openid-connect-honours-auth_path_prefix).
+
+Its own routes come with it: `/login`, `/logout`, `/callback` and
+`/backchannel-logout` are claimed whatever the scope, so the provider can
+always reach the callback and post a logout token, and a catch-all
+authentication never answers them with a 401.
+
+Two instances are supported — `auth()` builds a fresh router per instance —
+but `--base-url` and the callback path are global, so both share one
+redirect URI. Scope by prefix, not by provider, unless you also front them
+with different base URLs.
+
+## The identity it publishes
+
+`req.user` is the OIDC `sub` — an opaque provider identifier, `auth0|…` or a
+UUID — which is what authorization rules are keyed on by default, and what
+nobody can write a rule for without looking it up per administrator.
+
+`--oidc-username-claim` names the claim published as `req.userName`:
+
+```bash
+--oidc-username-claim preferred_username
+```
+
+Ask the provider for the scope that carries it (`profile`, or `email` for
+`email`), then key the authorization plugins on it with
+`--authz-identity req.userName`. A session missing the configured claim falls
+back to the `sub`, with a warning naming the claim.
+
+## What an unauthenticated request receives
+
+The library's own answer: a browser is redirected to the provider, an API
+client (`Accept: application/json`) receives 401. Every other authentication
+plugin in this repository answers JSON 401 throughout — the difference is
+kept because it is what makes a login work at all.
+
 ## How It Works
 
 1. Uses `express-openid-connect` for OAuth2/OIDC flow
@@ -163,5 +213,7 @@ npm install express-openid-connect
 
 ## See Also
 
+- [Back-Channel Logout](back-channel-logout.md) — honouring a logout the
+  provider performed elsewhere
 - [OpenID Connect Specification](https://openid.net/connect/)
 - [express-openid-connect](https://github.com/auth0/express-openid-connect)

package/docs/usage/plugins/ldap/organizations.md

@@ -174,6 +174,43 @@ curl "http://localhost:8081/api/v1/ldap/organizations/ou%3DIT%2Co%3Dgov%2Cc%3Dmu
 ]
 ```
 
+**When the answer is partial**
+
+Two things bound what comes back, and both are announced in the list rather
+than left for the client to guess:
+
+- The attached entries are capped at `--ldap-organization-max-subnodes`
+  (default 50). Child organizations are not capped.
+- The directory has a size limit of its own, and a branch holding more
+  entries than it will list in one answer makes it refuse rather than
+  truncate. The endpoint then asks again for a bounded number and returns
+  what it gets, writing a `warn` line naming the node.
+
+Either way the list ends with a row that is not an entry:
+
+```json
+{
+  "dn": "more-ou=IT,dc=example,dc=com",
+  "cn": ["... 412 more elements"],
+  "objectClass": ["moreIndicator"],
+  "_isMoreIndicator": "true",
+  "_totalCount": "462",
+  "_displayedCount": "50"
+}
+```
+
+Its DN answers nothing — `more-<the organization's DN>` for the attached
+entries, `more-organizations-<the organization's DN>` for the child
+organizations — and a client should drop any row carrying
+`_isMoreIndicator` before treating the rest as entries. `_totalCount` is
+present only when the directory listed everything and the cap did the
+trimming; when the directory itself refused, nothing knows the total.
+
+A refusal is not emptiness: a node whose children cannot be listed answers
+its first fifty and says there are more, and any other directory failure is
+raised rather than returned as `[]`. Raise the size limit for the account
+ldap-rest binds as (`olcLimits`, or `olcSizeLimit`) to see a whole branch.
+
 ### Create Organization
 
 ```http

package/docs/usage/plugins/utilities/storage.md

@@ -0,0 +1,94 @@
+# Storage Plugin
+
+Keyed storage for whoever needs to keep something with a deadline.
+
+## Overview
+
+`core/storage` gives other plugins a key, a value and an instant past which
+the value stops being returned. It knows nothing about why a record exists:
+Back-Channel Logout tombstones were the first use, a refresh-token lock and a
+shared counter are the ones in sight.
+
+One plugin, one backend, named by `--storage-backend`. Consumers ask this one
+for its store and work through a single interface; where the records actually
+live is a deployment decision, not theirs.
+
+Having exactly one is the point. The alternative — each consumer loading the
+backend it likes — puts the same record in two places, and makes whichever
+plugin was registered first decide what happens when one of them is unwell.
+Loading a second instance is refused rather than left to registration order,
+which is invisible in a configuration.
+
+## Configuration
+
+```bash
+--plugin core/storage --storage-backend ldap \
+  --storage-ldap-base ou=Records,dc=example,dc=com
+```
+
+| Option                        | Environment                    | Default              | Description                                               |
+| ----------------------------- | ------------------------------ | -------------------- | --------------------------------------------------------- |
+| `--storage-backend`           | `DM_STORAGE_BACKEND`           | _(none)_             | `ldap` or `file`. Empty means the plugin refuses to start |
+| `--storage-sweep-interval`    | `DM_STORAGE_SWEEP_INTERVAL`    | `600`                | Seconds between two passes dropping expired records       |
+| `--storage-ldap-base`         | `DM_STORAGE_LDAP_BASE`         | _(none)_             | 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`    | _(none)_             | Directory the `file` backend writes to                    |
+
+`core/storage` is in the priority list, so it is registered before the
+plugins that consume it whatever order they are written in. A consumer that
+declares it as a dependency — `core/bcl` does — also loads it on its own when
+the configuration does not name it.
+
+## Backends
+
+### `ldap`
+
+One entry per record under `--storage-ldap-base`. The branch holds records
+and nothing else, so it belongs outside the branches the directory serves —
+the plugin does not create it, and will not write into a branch that is not
+there.
+
+Suited to a deployment that already replicates its directory and wants the
+records to follow, and to one where no other store is available.
+
+### `file`
+
+One file per record under `--storage-file-directory`. A write goes to a
+temporary file and is renamed into place, so a reader never sees half a
+record; the directory and its files are created `0700` and `0600`.
+
+The directory is the plugin's own: nothing else should be writing there, and
+the sweeper removes what it finds expired. It is local to one process, so it
+suits a single instance, not a cluster sharing one verdict.
+
+## Expiry
+
+Two rules the backends do not get to reinterpret:
+
+- **Expiry is enforced on read.** A record past its deadline is answered as
+  absent whatever the sweeper has done, so a sweeper running late is a
+  storage cost, never a wrong answer.
+- **The deadline belongs to the consumer.** How long a record lives is the
+  policy of whoever wrote it. The store is told an instant and respects it.
+
+Keys are namespaced per consumer, so two of them cannot collide in one branch
+or one directory.
+
+## For Plugin Authors
+
+```ts
+const storage = this.requirePlugin<Storage>('storage');
+await storage.store.set('myplugin', key, value, Date.now() + 3600_000);
+const kept = await storage.store.get('myplugin', key); // null once expired
+await storage.store.delete('myplugin', key);
+```
+
+`requirePlugin` warns and answers `null` when storage is absent, which is
+right for a feature that can be skipped. A plugin making a **security**
+decision must not read "no storage" as "nothing to check": it refuses to load
+instead, as [Back-Channel Logout](../auth/back-channel-logout.md) does.
+
+## See Also
+
+- [Back-Channel Logout](../auth/back-channel-logout.md) — the first consumer
+- [OpenID Connect](../auth/oidc.md)