ldap-rest 0.26.0 → 1.0.1

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

@@ -61,12 +61,20 @@ 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
+the hooks they register: 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 authorization plugins' request hooks (`ldapsearchrequest`,
+`ldapaddrequest`, `ldapmodifyrequest`, `ldapdeleterequest`,
+`ldaprenamerequest`) run before any other plugin's, whatever order the
+plugins loaded in: a caller who may not make an operation gets the 403, not
+another plugin's 409, and the operation is not replaced (by
+`core/ldap/trash`, for instance) before it is judged. `ldapsearchfilter`
+keeps the load order.
+
 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
@@ -108,6 +116,16 @@ aside — `authzDynamic` letting a request through on
 
 ### What is refused at startup
 
+- An authorization plugin with no authentication plugin is refused: no
+  request carries an identity, so every authorization plugin would step
+  aside and everything would pass while authorization looks on.
+  `authzDynamic`, which authenticates the requests it judges, needs nothing
+  else. With neither kind of plugin, the server serves every request with
+  every right, on purpose (local development, a trusted network); with
+  authentication alone, every authenticated caller has every right (a
+  single administration token, say). The log says which, once. This is
+  checked over the plugins the configuration loads (`--plugin`); a host
+  registering plugins itself answers for what they enforce.
 - 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
@@ -124,7 +142,8 @@ aside — `authzDynamic` letting a request through on
   already.
 
 A host that assembles the server itself — `registerPlugin` after `ready`,
-rather than `--plugin` — gets the same checks, as each plugin arrives: the
+rather than `--plugin` — gets the same checks of the composition, as each
+plugin arrives (not the one asking for an authentication plugin, above): 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

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

@@ -78,17 +78,26 @@ organization through which entries change hands.
 ```
 
 An entry is **in transit** when it is attached to that organization, or to
-none (with or without the option).
+none (with or without the option). An entry carrying no link is in transit
+on purpose: it is how the entries other tools insert without one are
+caught. Nothing ties such an entry to an organization: any administrator
+may claim it into one they manage, and the first to claim it takes it.
 
-- Every administrator sees the entries in transit.
+- Every administrator sees the entries in transit, but in a global branch
+  (`--authz-global-branch`), which only its holders read.
 - **Claiming** one (`POST /api/v1/ldap/users/:id/move` towards an
-  organization) asks for write on that organization only.
+  organization) asks for write on that organization only. The write
+  claiming it may carry other changes to the entry — its password, say —
+  judged with it: the entry lands in the organization that write is
+  allowed in.
 - **Putting** one in transit asks for write on the organization it leaves,
   and nothing on the transit branch: an administrator only lets go of what
   they manage. Handing an account over to an organization one does not manage
   is two steps: put it in transit, then its new administrator claims it.
-- Any other change to an entry in transit (attributes, password, status,
-  deletion) is judged as before, so the entry is claimed first.
+- Any other change to an entry in transit, not claiming it (attributes,
+  password, status, deletion), is judged as before: on the transit branch
+  for an entry attached to it, on its parent branch for one attached to
+  nothing.
 
 `GET /api/v1/authz/scope` returns the transit branch as `transit` (`null`
 when there is none), so that a client can offer these moves. A group attached

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

@@ -106,13 +106,44 @@ Permissions applied to all group members:
 
 ## Permission Resolution
 
-Permissions are resolved in this order:
-
-1. **User-specific permissions** - If user has direct branch permissions, use them
-2. **Group permissions** - Check all groups user belongs to
-3. **Default permissions** - Fall back to defaults if no specific rules match
-
-For each permission type (read/write/delete), the **most permissive** rule wins.
+The rules holding the target, the user's own and those of every group they
+belong to, are combined:
+
+1. **Within one source** (the user's own rules, or one group's), the rule of
+   the **most specific** branch holding the target applies, whatever order
+   the rules are written in, broader rules of that source aside. Branches
+   are compared as DNs, whatever their case and spacing.
+2. **Between sources**, for each permission type (read/write/delete), the
+   **most permissive** wins.
+3. **Default permissions** apply to a permission none of these rules sets. They are a fallback, not a floor: `"default": {"read": true}` does
+   not undo a rule refusing read.
+
+Creating or writing an entry a rule names also asks for that rule's
+permission, and
+moving or deleting one holding such an entry asks for read and write, or
+delete, at every rule below it: a caller granted `ou=organization` cannot
+rename `ou=payroll` from under the rule refusing it, nor change or delete
+the `ou=payroll` entry itself. This holds under
+`--authz-filter-attached-entries` too, where `departmentSync` would relink
+the accounts attached there. A write setting the organization link
+(`--ldap-organization-link-attribute`) is judged on the organizations it
+leaves and joins; anything else it carries still needs write where the
+entry stands: its branch, or, judged by attachment, the organization it
+leaves.
+
+A rule's branch matches a DN however it is spelled, as OpenLDAP reads it:
+case, spaces, escapes (`\2C` and `\,`, `\20` and a space, `\C3\A9` and
+`é`), an attribute type by any of its names or its OID
+(`organizationalUnitName=` and `2.5.4.11=` are `ou=`, learned from the
+directory schema at startup), the spaces its matching rules ignore, and
+the LDAPv2 forms (`;` between RDNs, a value in double quotes). A write is
+judged on the entry as the directory names it, read as the server before
+the write. A caller cannot step around a rule by spelling its branch
+another way.
+
+A move is judged on the mover's own rules. The rules of other users and
+groups name the branch by its DN: once a caller allowed to move it has done
+so, they no longer apply to it, and need rewriting for the new DN.
 
 ## How It Works
 
@@ -212,6 +243,25 @@ With this config, user `manager` can read:
 - `ou=team1,ou=dept1,ou=organization,dc=example,dc=com`
 - ... all descendants
 
+A rule on a sub-branch takes over below it. To keep `manager` out of one
+department:
+
+```json
+{
+  "users": {
+    "manager": {
+      "ou=organization,dc=example,dc=com": { "read": true },
+      "ou=payroll,ou=organization,dc=example,dc=com": { "read": false }
+    }
+  }
+}
+```
+
+A search granted on `ou=organization` then returns nothing from
+`ou=payroll`: each entry it finds is kept only where the caller may read it.
+A group the user belongs to may still grant the department, as the most
+permissive source wins.
+
 ## Examples
 
 ### Example 1: Department-Based Access
@@ -412,8 +462,9 @@ Cache hit/miss logging:
 
 ### Permission Inheritance
 
-- Sub-branch permissions inherit from parent branches
-- Cannot grant more restrictive permissions on sub-branches
+- Sub-branch rules take over from parent branch rules, for what they set
+- A rule may restrict a sub-branch as well as widen it, but another source
+  (a group) granting more still wins
 - Plan branch structure carefully
 
 ### Default Permissions

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

@@ -18,6 +18,29 @@ 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.
 
+## The Server's Own `/logout`
+
+A provider sends logout tokens to the other applications, not to the one
+that asked it to log out. So `core/auth/openidconnect` records the session
+its own `/logout` ends, as a logout token naming it would: by the id it gave
+that session at login, kept in the cookie, which ends that one session and
+leaves the person's others alone. The same person logging in again over a
+live session keeps its id, so a copy taken before is ended with it.
+
+A session from before that id existed is named by the provider's `sid`, when
+it sent one. A provider that sends none (Dex) leaves such a session
+unnamed: its copies keep working until its tokens expire, and the first
+`/logout` of one logs a warning. That lasts until those sessions have
+expired, a week at most.
+
+Without `core/bcl`, `/logout` drops the browser's cookie and nothing else,
+and a copy of it keeps working until its tokens expire.
+
+A plugin subscribing to `oidclogouttoken` receives `{ iss, session }` from
+`/logout`, with neither `sid` nor `sub`: `session` names one session of this
+server, and is matched against the `session` that `oidcsessionvalid`
+carries.
+
 ## Configuration
 
 ```bash
@@ -45,6 +68,11 @@ 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.
 
+A copy of a session `/logout` ended is refused, so no longer renewed: it
+dies a day after its last use at the latest, the cookie's rolling lifetime.
+While the store cannot answer, though, a copy is still renewed, up to the
+week; keep the retention at 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.
 

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

@@ -121,6 +121,14 @@ A provider whose discovery document names no `end_session_endpoint` gets a
 local logout — the cookie is dropped, the browser goes to `--base-url` — and
 a warning saying the provider may log the caller back in.
 
+The session itself ends here only with [`core/bcl`](back-channel-logout.md)
+loaded. The cookie holds the whole session, so dropping it ends the
+browser's copy: a copy kept elsewhere — a shared computer, a backup of the
+browser profile, a stolen cookie — keeps working until its tokens expire.
+With `core/bcl`, `/logout` records the session it ends, named by an id given
+at login, and that copy is refused. Without it, the first `/logout` logs a
+warning saying so.
+
 `GET /v1/config` (with `core/configApi`) publishes the route, so a front-end
 knows it can offer a sign-out control. The key is `openidconnect` whatever
 the instance is named:

package/docs/usage/plugins/integrations/app-accounts.md

@@ -100,6 +100,11 @@ DM_MAIL_ATTRIBUTE="mail"
 
 - `--applicative-account-base`: LDAP base DN for applicative accounts (required)
 - `--max-app-accounts`: Maximum number of app accounts per user (default: 5)
+- `--app-accounts-user-attribute`: attribute the `:user` of the routes is
+  matched against (default: the mail attribute, unique directory-wide).
+  `uid` is safe only where a uid is unique across the whole directory: a
+  uid shared by users the caller can read is answered `409`, and one
+  shared with a user it cannot read resolves to the one it can
 - `--mail-attribute`: LDAP attribute for email (default: `mail`)
 - `--api-prefix`: API endpoint prefix (default: `/api`)
 

package/docs/usage/plugins/integrations/groups.md

@@ -38,9 +38,42 @@ branch per organization. It serves the groups of an organization under
 ## Routes
 
 Every route answers 404 `ORGANIZATION_NOT_FOUND` when the organization entry
-is missing, and 410 `ORGANIZATION_DELETED` when it is deleted. Errors are
-`{ "error": "...", "code": "..." }`. A request an authorization plugin refuses
-answers 403 `REFUSED`.
+is missing or the caller cannot read it, and 410 `ORGANIZATION_DELETED` when
+it is deleted. Errors are `{ "error": "...", "code": "..." }`. A request an
+authorization plugin refuses answers 403 `REFUSED`.
+
+The routes read as the caller: the authorization plugins decide which groups
+and members it gets. A group it cannot read answers 404, a user it cannot
+read is not found (404 `USER_NOT_FOUND` when adding it), and a member it
+cannot read lists as `{ "uid": "..." }`. A write is judged before anything
+is looked for, so a caller who may not make it gets 403 whether the name is
+taken, the users exist or they are already members.
+
+What the caller may read is the authorization model's to say:
+
+- A model judging by branch (`core/auth/authzPerBranch`) gives an
+  organization's groups and users to the callers granted its branch.
+- A model judging entries by their organization link (`core/auth/authzLinid1`,
+  or `--authz-filter-attached-entries`) gives an entry carrying no link to
+  every administrator. Under such a model only, every group written in an
+  organization's branch — through these routes, SCIM or another plugin — is
+  given the organization link (`--ldap-organization-link-attribute`, with the
+  auxiliary class `twakeGroup` when it holds neither it nor
+  `twakeStaticGroup`), and follows it when moved to another organization; a
+  link naming another organization is refused (400). A group is then judged
+  on its organization: creating or changing one needs write on the
+  organization, not on its group branch only. What stays every
+  administrator's: whether an organization exists or is deleted, its spaces,
+  and users carrying no link, whose link is the provisioning tool's to set.
+  Such users are in transit: any administrator may claim them into an
+  organization they manage, the first to do so taking them — see
+  [transit](../auth/authz-linid1.md#transit-handing-an-entry-over).
+  With `core/ldap/organizations` loaded too, the organizations must lie under
+  `--ldap-top-organization`, where it accepts a link.
+- A plugin judging every read made for the request, as
+  `core/auth/authzDynamic` does, judges the organization check too: an
+  organization its token does not reach answers 404, as one that is not
+  there.
 
 A group reads:
 

package/docs/usage/plugins/integrations/scim.md

@@ -320,6 +320,13 @@ the caller sent, and so does a group `PUT` for its members, hidden ones
 included. A group left with no member the caller saw gets the
 `--group-dummy-user` placeholder.
 
+A member is resolved as the caller sees the directory, whether it is given
+by id or by DN: an account the caller cannot read is left out of the group,
+as one that does not exist is. Under an authorization model judging by
+branch, a member in a branch the caller may not read refuses the whole write
+instead, whether the account exists or not. A DN outside the user base is
+left out.
+
 ### Schema advertisement
 
 Schemas listed under `GET /scim/v2/Schemas` are read from

package/docs/usage/plugins/integrations/spaces.md

@@ -179,7 +179,9 @@ Member events compare each moved user's roles before and after a change:
 ## Routes
 
 Every route answers 404 `ORGANIZATION_NOT_FOUND` when the organization entry
-is missing, and 410 `ORGANIZATION_DELETED` when it is deleted. Errors are
+is missing or the caller cannot read it, and 410 `ORGANIZATION_DELETED` when
+it is deleted. A user the caller cannot read is not found
+(`USER_NOT_FOUND`). Errors are
 `{ "error": "...", "code": "..." }`. A request an authorization plugin refuses
 answers 403 `REFUSED`. A write answers `{ "success": true }` unless stated
 otherwise.

package/docs/usage/plugins/ldap/bulk-import.md

@@ -318,6 +318,26 @@ curl -X POST "http://localhost:8081/api/v1/ldap/bulk-import/users" \
 - Check organization DNs exist
 - Estimate import duration
 
+A dry run is judged as the import is: a row the caller may not write fails,
+and a row updating an existing entry counts as `updated`.
+
+### Authorization
+
+Each row's write is judged by the authorization plugins before anything is
+looked for in the directory: the entry, its organization, whether it exists.
+A row is let through when the caller may create its entry, or change the
+entry it names (an administrator updating the accounts of their organization
+from a file naming none). Otherwise it fails with
+`Token does not have permission on this branch` (`code: forbidden`), whether
+its entry and its organization are there or not.
+
+A row the caller may write tells, as a single creation does, whether its
+identifier is taken: it is then skipped, or updated with `updateExisting`.
+
+The organization link of a row names one organization: a row naming several,
+or holding an empty value (`;` in a cell), fails as invalid, reported in
+`errors` (a 400 answer with `continueOnError=false`).
+
 ### Update Existing Mode
 
 Update entries that already exist:

package/docs/usage/plugins/ldap/enterprise-rules.md

@@ -63,8 +63,18 @@ check that justified it.
   non-individual entries.
 - `filter` narrows the search, e.g. `(objectClass=twakeAccount)`.
 
-On an update the entry being modified is excluded from the search, so
-re-sending an unchanged value never conflicts with itself.
+On an update, a value the entry already holds, as stored and spelled the
+same, is not looked for again; only the values it does not hold yet are.
+Re-sending an unchanged value conflicts neither with the entry itself nor
+with the copies other plugins keep of it — the applicative accounts of
+`appAccountsConsistency` carry the account's mail. A value held under
+another attribute the constraint spans, an alias becoming the mail, is
+skipped only when that attribute's own constraint looks for it everywhere
+this one does; otherwise it is checked. A duplicate the directory already
+holds, from before the rule or another tool, is therefore not reported on a
+re-save. A value spelled differently is a new one, and looked for: changing
+only the case of an account's mail is refused while an applicative copy
+holds the old spelling, which the directory takes for the same address.
 
 ### Mail domains
 

package/docs/usage/plugins/ldap/external-users.md

@@ -37,7 +37,7 @@ This plugin intercepts group member validation and automatically creates missing
   the address escaped as any DN value (RFC 4514): `mail=a\+b@partner.com,…`
   creates an entry whose `mail` is `a+b@partner.com`. Only the direct children of the
   branch are external members.
-- **Domain Protection**: External users cannot be created if their mail are in managed domains (configured via `--mail-domain`, compared case-insensitively)
+- **Domain Protection**: External users cannot be created if their mail is in a managed domain, compared case-insensitively. The managed domains are those of `--mail-domain` and those the directory declares in its domain branches: the entries of a flat schema declaring the `domainName` role, or else `ou=domains,ou=nomenclature,<base>` with `--enterprise-domain-name-attribute` (`associatedDomain`). A subdomain of a managed domain is not managed: `user@sub.example.com` is external unless `sub.example.com` is declared itself
 - **Automatic Creation**: Users are created automatically when added to a group if they don't exist
 
 ### Config API
@@ -56,7 +56,8 @@ where to send them:
 
 A client turns an address into a member with
 `rdnAttribute=<escaped address>,<branch>`, and can refuse a `managedDomains`
-address before sending it.
+address before sending it. The list holds the domains declared in the
+directory as well as those of `--mail-domain`.
 
 ## How It Works
 
@@ -225,6 +226,9 @@ Protect multiple domains from external user creation:
 --mail-domain example.com,company.org,subsidiary.net
 ```
 
+The domains declared in the directory are protected without being listed
+here.
+
 ### Custom Attributes via Hooks
 
 Add organization-specific attributes to external users:
@@ -261,7 +265,8 @@ hooks: {
 **Solutions:**
 
 1. Use the correct branch for internal users: `ou=users,dc=example,dc=com`
-2. Remove domain from `--mail-domain` if it should allow external users
+2. Remove the domain from `--mail-domain`, or from the directory's domain
+   branches, if it should allow external users
 3. This is expected behavior for internal domains - create user in users branch instead
 
 ### Malformed Member DN

package/docs/usage/plugins/ldap/flat-generic.md

@@ -120,6 +120,9 @@ Each schema file must include an `entity` metadata section and attribute definit
 ```
 
 Pointer validation ensures the DN exists and is within allowed branches.
+The DN is looked for as the server, whoever writes: a caller may point at
+an entry it cannot read, and learns from the answer whether one is there,
+never what it holds.
 
 #### Fixed Attributes
 

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

@@ -410,6 +410,12 @@ The plugin supports JSON schema validation for group attributes. Example schema:
 }
 ```
 
+A `pointer` attribute is checked as in
+[flat schemas](flat-generic.md#pointer-dn-reference): the DN must name an
+entry in the allowed branches, looked for as the server, whoever writes.
+A caller may point at an entry it cannot read, and learns from the answer
+whether one is there, never what it holds.
+
 ## Hooks
 
 The plugin emits and listens to lifecycle hooks:

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

@@ -174,6 +174,14 @@ curl "http://localhost:8081/api/v1/ldap/organizations/ou%3DIT%2Co%3Dgov%2Cc%3Dmu
 ]
 ```
 
+**Where the attached entries are looked for**
+
+Below the parent of `--ldap-top-organization`, as the caller. A caller an
+authorization plugin does not let search there — `authzPerBranch` judging
+by DN, a token of `authzDynamic` — gets the entries attached within the
+organization's own branch; those attached from elsewhere are not listed.
+`/subnodes/search` looks the same way.
+
 **When the answer is partial**
 
 Two things bound what comes back, and both are announced in the list rather
@@ -715,6 +723,15 @@ The plugin validates organizations against configured object classes. Example sc
 }
 ```
 
+A `pointer` attribute is checked as in
+[flat schemas](flat-generic.md#pointer-dn-reference): the DN must name an
+entry in the allowed branches, looked for as the server, whoever writes.
+A caller may point at an entry it cannot read, and learns from the answer
+whether one is there, never what it holds. A pointer that grants rights
+follows the same rule: an organization administrator may name, in
+`twakeLocalAdminLink`, an account they cannot read, and so hand the
+administration of their organization to it.
+
 ## See Also
 
 - [LDAP Flat Plugin](./ldapFlat.md) - For managing flat LDAP entities (users, positions, nomenclature) through schema-driven approach

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

@@ -199,7 +199,7 @@ Combine with an authentication plugin ([token](../auth/token.md), [oidc](../auth
 
 - **Schema fetch**: the root DSE is read for `subschemaSubentry` (falling back to `cn=Subschema`), then the subschema entry is fetched and parsed once per `--ldap-raw-schema-cache-ttl`. Concurrent callers share a single fetch, and so does the [object class repair](flat-generic.md#entries-created-by-other-tools), which loads it even without this plugin.
 - **Operational attributes**: entries are read with `*` and `+`. When the server rejects `+`, the read is retried with `*` alone.
-- **Missing entries**: the LDAP "no such object" result (code 32) is mapped to a 404.
+- **Missing entries**: the LDAP "no such object" result (code 32) is mapped to a 404. A search whose base the caller cannot read answers the same 404 as one whose base does not exist.
 
 ## Limitations