ldap-rest 0.8.2 → 0.9.0

package/docs/usage/upgrading.md

@@ -4,6 +4,295 @@ What to check before deploying, newest first. Only releases that need a
 decision or a configuration change appear here; see the
 [CHANGELOG](../../CHANGELOG.md) for everything else.
 
+## To 0.9.0
+
+### Two authorization plugins judging the same requests no longer start
+
+**Who is affected:** anyone loading two of `core/auth/authzPerBranch`,
+`core/auth/authzLinid1` and `core/auth/authzDynamic` together — including
+`authzPerBranch` beside `authzDynamic`, where the branch plugin judged the
+tokens too.
+
+Every plugin judging LDAP operations registers the same hooks, and all of
+them run: the first refusal wins. Loaded together, they composed as an AND
+nobody had decided, and the 403 did not say whose refusal it was. The server
+now refuses to start, naming both plugins. Two ways out:
+
+- **Scope each plugin to its own callers** with `authz_for`, the instance
+  names of the authentication plugins whose requests it judges — so that no
+  request is judged by both:
+
+  ```bash
+  --plugin core/auth/authzDynamic
+  --plugin 'core/auth/openidconnect:oidc:{"auth_path_prefix":"/api/admin"}'
+  --plugin 'core/auth/authzPerBranch:authzPerBranch:{"authz_for":["oidc"]}'
+  ```
+
+- **Keep the AND**, if it was meant, with `--authz-combine`. Behaviour is
+  then what it was, and the startup log says the two compose.
+
+`authzPerRoute` is not concerned: it registers no LDAP hook, and route plus
+branch stays a combination that starts as before.
+
+**Hosts assembling the server themselves** — `registerPlugin` after `ready`
+rather than `--plugin` — get the same refusal, out of the `registerPlugin`
+call that brings the second plugin. A plugin arriving is judged against what
+is already there: register the authentication plugins an `authz_for` names,
+and the plugins `--authz-scope-source` names, before the plugin naming them.
+
+A lone `authzPerBranch` is not refused, but mind its default: unset,
+`--authz-per-branch-config` grants read everywhere and write nowhere to
+**every** authenticated identity, whatever authenticated it. The startup
+line `authzPerBranch judges … for every authenticated request (…)` names the
+authenticators it judges; one it was not written for needs an `authz_for`.
+
+`GET /v1/authz/scope` changes in two ways. It answers with a plugin that
+judges the caller, lists every plugin judging them under `sources`, and says
+which one answered under `source` — `--authz-scope-source` chooses when
+several can. And when the only plugins judging the caller cannot describe a
+scope — `authzPerRoute`, `authzDynamic` — it answers `described: false` with
+no entity instead of `unrestricted: true` with `create: true` everywhere. A
+client that enumerates the entities it may create offers nothing there
+rather than everything. An anonymous caller is answered `401` as soon as any
+authorization plugin is loaded, where it used to be told `unrestricted`.
+
+### A second word after an option taking a list is refused
+
+**Who is affected:** anyone whose command line puts two values after one
+`--plugin`, `--authz-for`, `--mail-domain` or other list option.
+
+`--authz-for oidc authToken` read as `["oidc"]`: the second word was dropped
+in silence, and for `authz_for` that is a population smaller than the
+command line says — requests of `authToken` that nothing judges. The server
+now refuses to start on it, naming the option. Repeat the option for each
+value (`--authz-for oidc --authz-for authToken`), or use the plural form
+where there is one (`--plugins "a b"`), or the environment variable, which
+splits on spaces and commas.
+
+### `getLogger()` may return `undefined`, and its type says so
+
+**Who is affected:** anyone building a plugin or a host in TypeScript
+against the package's `expressformatedresponses` export and calling
+`getLogger()`.
+
+The logger is installed by the `DM` constructor, and before that there is
+none. The type used to say `winston.Logger`, so a reader without a guard
+compiled and threw `Cannot read properties of undefined` at runtime — from
+inside an error path, which is how #182 and #199 happened. It now says
+`winston.Logger | undefined`, and such a reader stops compiling:
+
+```ts
+getLogger().info('…'); // no longer compiles
+getLogger()?.info('…'); // logs when there is a logger
+```
+
+A plugin holds `this.logger`, which is always set; `getLogger()` is for a
+helper with no server in hand. `setLogger` accepts `undefined` as well, so a
+test restoring the state it found no longer needs a cast.
+
+### OpenID Connect honours `auth_path_prefix`
+
+**Who is affected:** anyone running `core/auth/openidconnect`, and in
+particular anyone who gave it an `auth_path_prefix`.
+
+The plugin did not go through the authentication dispatcher: it mounted its
+own middleware in `api()`, which kept its registration order, and it never
+read `auth_path_prefix`. Three consequences, all of them now gone:
+
+- **Scoping did nothing.** An instance scoped to `/api/admin` guarded the
+  whole server. It now guards `/api/admin` — and **the paths it used to
+  guard by accident are no longer guarded by it**. Check that another
+  authentication plugin covers them, or drop the prefix to keep guarding
+  everything. The startup line naming unguarded routes works again and is
+  the fastest way to tell.
+- **Authorization could run before the identity.** With
+  `core/auth/authzPerRoute` loaded, a named OIDC instance landed in the
+  parallel batch and mounted after it, so every rule was judged with no
+  `req.user` — and an unidentified request is passed, not refused. Rules
+  that read as enforced were inert.
+- **Two authentications composed as an AND.** A valid `Authorization:
+Bearer` answered by a catch-all token plugin was then redirected to the
+  provider anyway. Only the plugin whose claim is most specific runs now.
+
+`/login`, `/logout`, `/callback` and `/backchannel-logout` are claimed by
+the plugin whatever its scope, so a catch-all authentication no longer
+answers the provider's redirect with a 401.
+
+Unauthenticated requests are unchanged: a browser is redirected, an API
+client receives 401.
+
+### `core/auth/llng` refuses a request the handler named nobody for
+
+**Who is affected:** anyone whose LemonLDAP::NG configuration has a `skip`
+rule on a path this plugin guards.
+
+`skip` makes the handler return immediately — no session read, no
+`Lm-Remote-User` header — and the plugin published `req.user = undefined`.
+Every authorization plugin skips its check when a request carries no
+identity, so the rule meant "authenticated, and scoped by nobody" rather
+than "no authentication on this path". Such a request now answers 401.
+
+Serve those paths from a virtual host this plugin does not guard, or scope
+the plugin with `auth_path_prefix` so they fall outside it.
+
+### `authzDynamic` no longer steps aside for another authenticator
+
+**Who is affected:** anyone loading `core/auth/authzDynamic` beside another
+authentication plugin on the same paths — `core/auth/token`,
+`core/auth/openidconnect`, `core/auth/llng`.
+
+The plugin returned early as soon as a request already carried a `req.user`,
+so the token ACLs were applied to nothing. With `core/auth/token` registered
+first, its static tokens reached the whole directory as unscoped
+administrators; registered the other way round, the same configuration
+demanded both credentials. Which one a deployment got was plugin import
+order.
+
+The ACLs now apply to the token a request carries, whoever else identified
+it, and a request carrying none is refused. **A deployment relying on the
+old behaviour will start answering 401** — its callers authenticate with the
+other plugin and have no dynamic token.
+
+`--authz-dynamic-bypass` names what may pass without a token:
+
+```
+--authz-dynamic-bypass any-authenticated   # what the plugin did before 0.9.0
+--authz-dynamic-bypass ops-admin           # one identity, as another plugin publishes it
+--authz-dynamic-bypass trusted-proxy       # what core/auth/trustedProxy vouched for
+```
+
+`any-authenticated` restores the previous behaviour in one line. The
+difference is that it is now written down, logged per request with the
+reason, and announced at startup when this plugin shares its paths with
+another authenticator.
+
+`trusted-proxy` is the composition the old code's comment described and
+never performed: `core/auth/trustedProxy` sets `req.trustedProxy` and
+`req.proxyAuthUser`, never `req.user`, so that pair never took the early
+return — while every authenticator that does set it, did.
+
+### An identity that does not resolve is refused
+
+**Who is affected:** anyone running an authorization plugin that resolves
+identities against the directory — `core/auth/authzLinid1` — behind an
+authenticator that publishes something other than the directory's
+`ldap_user_main_attribute`.
+
+Every authorization hook skipped its check when `resolveUser` answered
+null: a `warn`, then the read, the write or the delete went ahead. With
+`authzLinid1`, whose `resolveUser` searches
+`(<ldap_user_main_attribute>=<identity>)`, an authenticator publishing
+anything else resolved to nothing on every request — `core/auth/openidconnect`
+publishes the OIDC `sub`, `core/auth/llng` whatever `whatToTrace` traces — so
+anyone the identity provider admitted read, wrote and deleted across the
+whole tree, behind a line a `notice` production log does not show.
+
+An authenticated identity that does not resolve is now refused, with the same
+403 as any other refusal. **Check your logs before upgrading**: a deployment
+in this state looks healthy, and the requests that were passing will start
+answering 403.
+
+```
+grep 'could not be resolved' <your log>
+```
+
+If that matches, the caller's identity and the plugin's model disagree, and
+the upgrade turns an open door into a refusal — which may be a service
+outage where the door was being used. `--authz-unresolved-user allow`
+restores the old behaviour while you fix the pairing; it keeps the warning,
+and it keeps the door open.
+
+An **anonymous** request is unchanged: no identity at all is still skipped,
+and the route's own authentication is what answers it.
+
+Both answers are cached now, negatives included, for the plugin's own cache
+TTL. An identity added to the directory after being refused waits out that
+TTL.
+
+### `/subnodes/search` caps what it returns
+
+**Who is affected:** a client reading the whole answer of
+`/api/v1/ldap/organizations/<dn>/subnodes/search` and expecting every match.
+
+It returned every attached entry it found, which is the one shape a directory
+with a size limit cannot answer: past that limit the server refuses the
+search rather than shortening it. It now caps them at
+`--ldap-organization-max-subnodes` (default 50) and ends the list with the
+`moreIndicator` row `/subnodes` already used, so the two endpoints answer the
+same shape.
+
+A client that treats every row as an entry will show that row as one. Drop
+whatever carries `_isMoreIndicator` — see
+[the endpoint's notes](plugins/ldap/organizations.md#get-organization-subnodes).
+
+The same row can now also appear among the **child organizations**, which
+were never capped and still are not: it says the directory refused to list
+them all, and it carries no `_totalCount`, nothing having counted them.
+
+### `/subnodes/search` is authorized, and lists the children by page
+
+**Who is affected:** anyone whose callers reach that route with a token that
+does not hold the whole directory, and anyone running against Active
+Directory.
+
+Neither of its searches carried the request, and an authorization plugin
+skips its check when there is none — the same gap the flat routes had until
+0.8.2. A caller now sees what its branch grants it, where it used to see
+everything the directory held; a caller outside its branch is refused. This
+is a fix, but it changes what an existing client receives.
+
+The child organizations of both routes are also searched by page now. On
+OpenLDAP that changes nothing — the server's size limit bounds a paged
+search as it does an unpaged one. On **Active Directory** it does: an
+unpaged search answered at most `MaxPageSize` entries (1000 by default) and
+said nothing about the rest, so a node with more children than that now
+returns all of them, and a client holding the answer in memory receives a
+larger one than before.
+
+### Back-Channel Logout keeps its marks in `core/storage`
+
+`core/bcl/ldap` and `core/bcl/file` are gone, and with them
+`--bcl-ldap-base`, `--bcl-ldap-object-class`, `--bcl-file-directory` and
+`--bcl-sweep-interval`. One plugin, `core/bcl`, keeps what a logout killed in
+`core/storage`, so a deployment chooses where records live once and every
+consumer of that store follows. Sweeping is now `--storage-sweep-interval`;
+`--bcl-retention` stays, because how long a mark is kept is Back-Channel
+Logout's policy rather than the store's. See
+[Storage](plugins/utilities/storage.md) and
+[Back-Channel Logout](plugins/auth/back-channel-logout.md).
+
+**Marks written before this are not read.** The key is namespaced now, and
+the LDAP branch is the store's rather than the plugin's. Back-Channel Logout
+shipped in no release — 0.8.2 predates it — so this can only affect an
+instance running a build from `master`. If yours is one, everything logged out
+within the retention window stops counting once you upgrade, and the old
+`ou=BclTombstones` branch, or the old `--bcl-file-directory`, is left behind
+for you to remove.
+
+### Judging an account by what it is attached to
+
+`--authz-filter-attached-entries` changes what a branch grant means, so it is
+off by default and nothing moves until you set it.
+
+Every account of a directory lives in the same `ou=users`, so a branch check
+on its parent says the same thing about all of them: either every
+administrator reaches every account, or none does. With the option on, an
+account is judged by the organization its `twakeDepartmentLink` names —
+listings drop the accounts attached elsewhere, and a write is refused on an
+account outside the branch you hold. Entries attached to nothing, which is
+what an organization or a nomenclature value is, stay readable by every
+administrator.
+
+**Turn it on only where a branch is a department.** Where a branch is a
+tenant, the option also stops refusing a read on the branch it targets — the
+organization tree and the reference data become readable across branches, and
+what keeps one customer out of another's data is then the per-entry filter
+alone.
+
+It is honoured by `core/auth/authzPerBranch` and `core/auth/authzLinid1`.
+`core/auth/authzDynamic` registers its own hooks and never sees the filter:
+setting the option there does nothing at all.
+
 ## To 0.8.0
 
 ### Node 20 is the floor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -92,6 +92,10 @@
       "types": "./dist/src/plugins/auth/trustedProxy.d.ts",
       "import": "./dist/plugins/auth/trustedProxy.js"
     },
+    "./plugin-bcl": {
+      "types": "./dist/src/plugins/bcl.d.ts",
+      "import": "./dist/plugins/bcl.js"
+    },
     "./plugin-configapi": {
       "types": "./dist/src/plugins/configApi.d.ts",
       "import": "./dist/plugins/configApi.js"
@@ -212,6 +216,18 @@
       "types": "./dist/src/plugins/static.d.ts",
       "import": "./dist/plugins/static.js"
     },
+    "./plugin-storage": {
+      "types": "./dist/src/plugins/storage.d.ts",
+      "import": "./dist/plugins/storage.js"
+    },
+    "./plugin-storage-file": {
+      "types": "./dist/src/plugins/storage/file.d.ts",
+      "import": "./dist/plugins/storage/file.js"
+    },
+    "./plugin-storage-ldap": {
+      "types": "./dist/src/plugins/storage/ldap.d.ts",
+      "import": "./dist/plugins/storage/ldap.js"
+    },
     "./plugin-twake-appaccountsapi": {
       "types": "./dist/src/plugins/twake/appAccountsApi.d.ts",
       "import": "./dist/plugins/twake/appAccountsApi.js"