ldap-rest 0.12.0 → 0.13.1

package/docs/usage/plugins/integrations/lifecycle-events.md

@@ -1,11 +1,12 @@
 # Lifecycle Events
 
-`core/twake/lifecycleEvents` publishes an account's lifecycle to RabbitMQ from
-the directory write itself. REST, SCIM and any other plugin writing through
+`core/twake/lifecycleEvents` publishes an account's or a group's lifecycle to
+RabbitMQ from the directory write itself. REST, SCIM and any other plugin writing through
 LDAP-Rest announce the same events, with the same payloads.
 
-Which entries are accounts, which attributes carry the role, the lock and the
-deletion, and where each event goes are configuration.
+Which entries are accounts or groups, which attributes carry the role, the
+lock, the deletion and the members, and where each event goes are
+configuration.
 
 ## Events
 
@@ -22,6 +23,14 @@ publishes nothing.
   role in a single-valued attribute.
 - `disabled`: the lock attribute takes the lock value.
 - `enabled`: the lock attribute no longer holds the lock value.
+- `updated`: a target whose payload has `$changed.` sources publishes when one
+  of them changed, with those that did not left out. A target without them
+  publishes on every change of the entry.
+- `memberAdded`, `memberRemoved`: the member attribute gains or loses values.
+  The old and new lists are compared as sets, so a whole list replaced
+  publishes only the members that came or went. The group placeholder
+  (`--group-dummy-user`) is never a member here. A group created with
+  members publishes `created` only, its members in `$members`.
 - `deleted`: the entry becomes a tombstone (the deleted attribute takes the
   deleted value), or an entry that is not a tombstone is removed.
 
@@ -102,6 +111,8 @@ operational one such as `pwdAccountLockedTime` is seen on both sides.
 - `--twake-lifecycle-deleted-at-attribute`,
   `--twake-lifecycle-deleted-at-format` (`iso8601`, the default, or
   `generalizedTime`): the deletion date. It is always published as ISO 8601.
+- `--twake-lifecycle-member-attribute` (default `member`): the attribute
+  `memberAdded`, `memberRemoved` and member lists read.
 - `--twake-lifecycle-rules`: a JSON file, or the JSON itself.
 
 Each option has a `DM_` environment variable, for example
@@ -177,12 +188,34 @@ Payload and `when` values are sources:
 - `$context.actor`, `$context.requestId`, `$context.source`: who made the
   write, the request it belongs to, and the API it came through (`rest`,
   `scim`); left out for a write no request made, such as a scheduled task
+- `$changed.attr`: the attribute after the write, only if the write changed
+  it; an attribute the write removed gives `""`
 - `$attr|domain`, `$previous.attr|domain`: what follows the `@`
 - `$now`: the current time, ISO 8601
 - anything else: the value itself
 
 `$attr` and `$previous.attr` carry the first value of a multi-valued
-attribute. A source with no value leaves its field out. Every message carries
+attribute. A source with no value leaves its field out.
+
+A payload field can also list members, as an object with one key:
+
+- `$members`: the members after the write
+- `$added`, `$removed`: the members `memberAdded` and `memberRemoved` are about
+
+```json
+"members": { "$added": { "username": "$uid", "email": "$mail" } }
+```
+
+Each member is read once, and shaped by the object it maps to, whose
+sources are its own attributes (`$attr`) or plain values; any other source is
+refused at startup. A tombstone is left
+out, and a target whose `$added` or `$removed` is left empty publishes
+nothing. A member no longer in the directory is known by its RDN alone:
+`uid=jdoe,…` gives `{ "username": "jdoe" }` above. A group of 1,000 members
+takes 1,000 reads, one after the other, off the path of the write's
+response. A member that cannot be read, for a reason other than being gone,
+drops that target, logged as an error: a member the service account may not
+read silences every target of the group that lists its members. Every message carries
 a random AMQP `messageId`.
 
 A source can read any attribute of the entry: `$userPassword` would put the

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

@@ -51,7 +51,7 @@ All SCIM endpoints sit behind the auth middleware registered before the plugin
 | `--scim-base-map`                    | `DM_SCIM_BASE_MAP`                    | —                                                  | Path to JSON file mapping authenticated user → `{userBase, groupBase}`                           |
 | `--scim-user-object-class`           | `DM_SCIM_USER_OBJECT_CLASSES`         | `top, inetOrgPerson, organizationalPerson, person` | Object classes for created Users                                                                 |
 | `--scim-user-rdn-attribute`          | `DM_SCIM_USER_RDN_ATTRIBUTE`          | `uid`                                              | RDN attribute for Users                                                                          |
-| `--scim-user-lock-attribute`         | `DM_SCIM_USER_LOCK_ATTRIBUTE`         | `pwdAccountLockedTime`                             | LDAP attribute whose presence marks a User as `active: false`                                    |
+| `--scim-user-lock-attribute`         | `DM_SCIM_USER_LOCK_ATTRIBUTE`         | `pwdAccountLockedTime`                             | LDAP attribute whose lock value marks a User as `active: false`                                  |
 | `--scim-user-lock-value`             | `DM_SCIM_USER_LOCK_VALUE`             | —                                                  | Value written to that attribute when deactivating (required unless the attribute is the default) |
 | `--scim-group-object-class`          | `DM_SCIM_GROUP_OBJECT_CLASSES`        | `top, groupOfNames`                                | Object classes for created Groups                                                                |
 | `--scim-group-rdn-attribute`         | `DM_SCIM_GROUP_RDN_ATTRIBUTE`         | `cn`                                               | RDN attribute for Groups                                                                         |
@@ -113,23 +113,23 @@ All responses have `Content-Type: application/scim+json`.
 
 ### Default mapping (LDAP ⇄ SCIM User)
 
-| SCIM                                 | LDAP                                        |
-| ------------------------------------ | ------------------------------------------- |
-| `id`                                 | `uid` (or `entryUUID`)                      |
-| `userName`                           | `uid`                                       |
-| `externalId`                         | `employeeNumber`                            |
-| `name.familyName`                    | `sn`                                        |
-| `name.givenName`                     | `givenName`                                 |
-| `name.formatted`                     | `cn`                                        |
-| `displayName`                        | `displayName`                               |
-| `title`                              | `title`                                     |
-| `preferredLanguage`                  | `preferredLanguage`                         |
-| `emails[primary=true].value`         | `mail`                                      |
-| `emails[primary=false].value`        | `mailAlternateAddress`                      |
-| `phoneNumbers[primary=true].value`   | `telephoneNumber`                           |
-| `phoneNumbers[primary=false].value`  | `mobile`                                    |
-| `active`                             | pseudo (false if the lock attribute is set) |
-| `meta.created` / `meta.lastModified` | `createTimestamp` / `modifyTimestamp`       |
+| SCIM                                 | LDAP                                                      |
+| ------------------------------------ | --------------------------------------------------------- |
+| `id`                                 | `uid` (or `entryUUID`)                                    |
+| `userName`                           | `uid`                                                     |
+| `externalId`                         | `employeeNumber`                                          |
+| `name.familyName`                    | `sn`                                                      |
+| `name.givenName`                     | `givenName`                                               |
+| `name.formatted`                     | `cn`                                                      |
+| `displayName`                        | `displayName`                                             |
+| `title`                              | `title`                                                   |
+| `preferredLanguage`                  | `preferredLanguage`                                       |
+| `emails[primary=true].value`         | `mail`                                                    |
+| `emails[primary=false].value`        | `mailAlternateAddress`                                    |
+| `phoneNumbers[primary=true].value`   | `telephoneNumber`                                         |
+| `phoneNumbers[primary=false].value`  | `mobile`                                                  |
+| `active`                             | pseudo (false if the lock attribute holds the lock value) |
+| `meta.created` / `meta.lastModified` | `createTimestamp` / `modifyTimestamp`                     |
 
 Override with `--scim-user-mapping /path/to/user-mapping.json` (same schema as
 `static/schemas/scim/default-mapping.json`).
@@ -140,14 +140,18 @@ SCIM models account status with the boolean `active` (RFC 7643 §4.1.1), and it
 is how Okta, Entra ID and JumpCloud disable a user — they PATCH `active` to
 `false` rather than DELETE the resource.
 
-LDAP has no single equivalent, so the plugin models it on the **presence of one
-attribute**: present means locked, absent means active.
+LDAP has no single equivalent, so the plugin models it on **one attribute
+holding one value**: `--scim-user-lock-value` in `--scim-user-lock-attribute`
+means locked, anything else means active. A ppolicy lockout after failed binds
+is a timestamp in `pwdAccountLockedTime`, so it reads as active, and
+`"active": true` leaves it in place. It lasts `pwdLockoutDuration`, or until
+an administrator clears it when that is 0.
 
 | SCIM              | LDAP                                            |
 | ----------------- | ----------------------------------------------- |
 | `"active": false` | write `--scim-user-lock-value` to the attribute |
-| `"active": true`  | remove the attribute                            |
-| attribute absent  | `"active": true`                                |
+| `"active": true`  | remove the attribute if it holds the lock value |
+| lock value absent | `"active": true`                                |
 
 The default targets the ppolicy overlay:
 
@@ -184,8 +188,8 @@ neither can be told apart from a deliberate local schema:
 
 **None of this can tell whether your directory honours the value you chose.**
 The checks are on the shape of the configuration. `active` is read back from
-the mere presence of the attribute, so a value the directory stores and
-ignores still reads as `false`. Verify once, by hand, that a deactivation
+the value this plugin wrote, so a value the directory stores and ignores still
+reads as `false`. Verify once, by hand, that a deactivation
 actually prevents a bind.
 
 `active` is not a mapping entry and must not be added to a mapping file: it is
@@ -347,16 +351,16 @@ group entries works; use a mapping override if you would rather name it there.
 SCIM filters are translated to LDAP filters (RFC 4515). Values are always escaped
 via `escapeLdapFilter()` — no LDAP injection is possible.
 
-| SCIM                             | LDAP                          |
-| -------------------------------- | ----------------------------- |
-| `userName eq "alice"`            | `(uid=alice)`                 |
-| `name.familyName sw "Du"`        | `(sn=Du*)`                    |
-| `emails.value co "@example.com"` | `(mail=*@example.com*)`       |
-| `displayName pr`                 | `(displayName=*)`             |
-| `active eq true`                 | `(!(pwdAccountLockedTime=*))` |
-| `active pr`                      | `(objectClass=*)`             |
-| `a eq "x" and b eq "y"`          | `(&(a=x)(b=y))`               |
-| `not (a eq "x")`                 | `(!(a=x))`                    |
+| SCIM                             | LDAP                                      |
+| -------------------------------- | ----------------------------------------- |
+| `userName eq "alice"`            | `(uid=alice)`                             |
+| `name.familyName sw "Du"`        | `(sn=Du*)`                                |
+| `emails.value co "@example.com"` | `(mail=*@example.com*)`                   |
+| `displayName pr`                 | `(displayName=*)`                         |
+| `active eq true`                 | `(!(pwdAccountLockedTime=000001010000Z))` |
+| `active pr`                      | `(objectClass=*)`                         |
+| `a eq "x" and b eq "y"`          | `(&(a=x)(b=y))`                           |
+| `not (a eq "x")`                 | `(!(a=x))`                                |
 
 Unknown SCIM attributes raise `400 invalidFilter`.
 
@@ -616,6 +620,12 @@ Other plugins can observe and transform SCIM operations via the dynamic hooks
 `scimuserdelete`, `scimuserdeletedone`, and their `scimgroup*` equivalents, plus
 `scimbulkdone` for Bulk.
 
+`scimgroupcreate` receives the group, the request and the group base. A
+group's RDN value is its `displayName`, unless the hook sets `id` on the group
+and the group mapping stores nothing in the RDN attribute: that `id` is then
+the RDN value. An `id` sent by the client is ignored. A hook returns all
+three, so that the hooks after it still get the base.
+
 ## Exposing the configuration to client apps (`configApi`)
 
 Load `core/configApi` alongside the SCIM plugin, and `GET /api/v1/config` will

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

@@ -38,16 +38,8 @@ a delete that an authorization plugin refuses writes nothing.
 
 `core/ldap/trash` moves a deleted entry before this plugin sees the delete,
 so no tombstone would be written in a branch it watches. The server refuses
-to start when `--trash-watched-bases` covers a `--twake-tombstone-dn`
-pattern, read the way the trash reads it today, and an empty list watches
-every branch.
-
-The trash splits `--trash-watched-bases` on every comma, a bug
-([#226](https://github.com/linagora/ldap-rest/issues/226)): a base such as
-`ou=users,dc=example,dc=com` becomes the suffixes `ou=users`, `dc=example`
-and `dc=com`, and `dc=com` watches every branch below it. The check follows
-the trash as it behaves, so such a value refuses to start next to any
-tombstone pattern under `dc=com`.
+to start when one of the `;`-separated `--trash-watched-bases` covers or sits under
+a `--twake-tombstone-dn` pattern, and an empty list watches every branch.
 
 ## Reason
 

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

@@ -318,13 +318,13 @@ For each schema, the plugin generates REST API endpoints:
 ### List Entries
 
 ```bash
-GET /api/v1/ldap/{pluralName}?match={filter}&attributes={attrs}
+GET /api/v1/ldap/{pluralName}?match={value}&attribute={attrs}&attributes={attrs}&limit={n}
 ```
 
 **Example:**
 
 ```bash
-curl http://localhost:8081/api/v1/ldap/users?match=uid=*smith*&attributes=uid,cn,mail
+curl 'http://localhost:8081/api/v1/ldap/users?match=smith&attribute=uid&attributes=uid,cn,mail&limit=50'
 ```
 
 **Response:**
@@ -340,6 +340,42 @@ curl http://localhost:8081/api/v1/ldap/users?match=uid=*smith*&attributes=uid,cn
 }
 ```
 
+#### Long lists
+
+A directory lists at most a set number of entries per search for the account
+LDAP-Rest binds as (OpenLDAP: `olcSizeLimit`, default 500, or `olcLimits`;
+`size.prtotal` bounds paged searches). OpenLDAP refuses a longer list as a
+whole rather than cutting it short:
+
+- **Without `limit`**, the answer is every match or `422`:
+
+  ```json
+  {
+    "error": "Too many entries to list at once: the directory's size limit was exceeded. Narrow the search, or pass `limit`."
+  }
+  ```
+
+- **With `limit`** (a positive integer, `400` otherwise), at most `limit`
+  entries come back, with the header `X-Result-Truncated: true` when others
+  were left out. When the directory refuses the list, LDAP-Rest asks again
+  for `limit + 1` entries and answers what it gets, at most `limit` —
+  possibly fewer, if the account's own limit is lower — always with the
+  header: the directory does not say whether that answer was cut, so a
+  shorter one is not taken for complete. A request with `limit` is never
+  answered `422`.
+
+The header is absent from a complete answer. LDAP-Rest sets no CORS headers:
+a browser client on another origin sees `X-Result-Truncated` only if the
+proxy answering for it lists the header in `Access-Control-Expose-Headers`.
+
+A small `limit` costs a page of the directory's answer. A `limit` larger than
+the directory's own limit costs a walk up to that limit, then the second
+search: memory stays bounded by the directory, not by `limit`.
+
+Only the lists of the entities this plugin serves honour `limit`,
+`X-Result-Truncated` and the `422` for now. The groups list
+(`GET /api/v1/ldap/groups`) ignores `limit` and still fails with `500`.
+
 ### Get Entry
 
 ```bash

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

@@ -16,7 +16,7 @@ Plugin to intercept LDAP delete operations and move entries to a trash branch in
 ### Environment Variables
 
 - `DM_TRASH_BASE`: LDAP base DN for trash (default: `ou=trash,dc=example,dc=com`)
-- `DM_TRASH_WATCHED_BASES`: Comma-separated list of branches to watch (default: all branches except trash)
+- `DM_TRASH_WATCHED_BASES`: branches to watch, each a full DN, separated by `;` (default: all branches except trash)
 - `DM_TRASH_ADD_METADATA`: Add metadata to trashed entries (default: `true`)
 - `DM_TRASH_AUTO_CREATE`: Auto-create trash branch if missing (default: `true`)
 
@@ -25,7 +25,7 @@ Plugin to intercept LDAP delete operations and move entries to a trash branch in
 ```bash
 --plugin core/ldap/trash \
 --trash-base "ou=trash,dc=example,dc=com" \
---trash-watched-bases "ou=users,dc=example,dc=com,ou=groups,dc=example,dc=com" \
+--trash-watched-bases "ou=users,dc=example,dc=com;ou=groups,dc=example,dc=com" \
 --trash-add-metadata true \
 --trash-auto-create true
 ```
@@ -68,7 +68,7 @@ This watches all LDAP branches except the trash branch itself.
 ldap-rest \
   --plugin core/ldap/trash \
   --trash-base "ou=trash,dc=example,dc=com" \
-  --trash-watched-bases "ou=users,dc=example,dc=com,ou=groups,dc=example,dc=com"
+  --trash-watched-bases "ou=users,dc=example,dc=com;ou=groups,dc=example,dc=com"
 ```
 
 This only intercepts deletes from `ou=users` and `ou=groups`. Deletes from other branches proceed normally.
@@ -248,7 +248,7 @@ ldap-rest \
   --ldap-pwd "admin" \
   --ldap-base "dc=example,dc=com" \
   --trash-base "ou=trash,dc=example,dc=com" \
-  --trash-watched-bases "ou=users,dc=example,dc=com,ou=groups,dc=example,dc=com" \
+  --trash-watched-bases "ou=users,dc=example,dc=com;ou=groups,dc=example,dc=com" \
   --trash-add-metadata true \
   --auth-token "secret-token"
 ```

package/docs/usage/upgrading.md

@@ -4,6 +4,62 @@ 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.13.0
+
+### An OpenID Connect session ends with its access token
+
+**Who is affected:** a deployment loading `core/auth/openidconnect`.
+
+A session used to last as long as its cookie, a day of inactivity and a week
+at most. It now ends when its access token expires, unless the provider gave
+a refresh token to renew it: a browser then goes back through the provider,
+silently while the provider's own session lasts, and a client asking for
+JSON only (`Accept: application/json`) is answered `401`.
+
+To keep sessions going without that round trip, have the provider issue
+refresh tokens to the client
+([details](plugins/auth/oidc.md#session-lifetime)).
+
+### SCIM `active` reads the lock value
+
+**Who is affected:** a SCIM client of a directory with ppolicy lockouts. An
+account locked out after failed binds now reads `active: true`, is left out
+of `active eq false`, and keeps its lockout on `"active": true`; only the
+configured lock value reads as inactive. See
+[the SCIM plugin documentation](plugins/integrations/scim.md#deactivating-an-account-active).
+
+### twake/instances links an organization before its members
+
+**Who is affected:** a deployment running 0.12.0 with
+`--twake-instance-provider cloudery` and `--twake-instance-organization-base`.
+
+0.12.0 sent each member's `user.created` at once and marked the member, while
+the Cloudery refused it because the organization was not linked to its
+instance. The plugin now links the organization and holds its members until
+then, but only releases members that are not marked, so those already marked
+are not sent again on their own.
+
+To repair an organization, clear `--twake-instance-sent-attribute` on its
+marked members, then replay its `workplace.created` or call
+`ensureOrganization` for it ([details](plugins/integrations/instances.md#organizations)).
+
+### Trash watched bases are separated by `;`
+
+**Who is affected:** a deployment loading `core/ldap/trash` with
+`--trash-watched-bases` set.
+
+The list was split on commas, so a DN such as `ou=users,dc=example,dc=com`
+became the suffixes `ou=users`, `dc=example` and `dc=com`, and the trash
+caught deletes in every branch under `dc=com`. Each base is now a whole DN,
+and bases are separated by `;`:
+`ou=users,dc=example,dc=com;ou=groups,dc=example,dc=com`. A single DN needs
+no change. A list of full DNs joined by commas, such as
+`ou=users,dc=example,dc=com,ou=groups,dc=example,dc=com`, or a list of RDNs,
+such as `ou=users,ou=groups`, now reads as one DN that no entry sits under,
+so the trash catches nothing and deletes there are permanent: rewrite it with
+`;`, each branch as its full DN. The server logs a warning at startup for a
+watched base that is not one DN under `--ldap-base`.
+
 ## To 0.12.0
 
 ### twake/instances replaces cozyProvision and clouderyProvision

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"
@@ -268,6 +268,10 @@
       "types": "./dist/src/plugins/twake/drive.d.ts",
       "import": "./dist/plugins/twake/drive.js"
     },
+    "./plugin-twake-groups": {
+      "types": "./dist/src/plugins/twake/groups.d.ts",
+      "import": "./dist/plugins/twake/groups.js"
+    },
     "./plugin-twake-instances": {
       "types": "./dist/src/plugins/twake/instances.d.ts",
       "import": "./dist/plugins/twake/instances.js"
@@ -660,6 +664,10 @@
       "import": "./static/schemas/twake/nomenclature/twakeTitle.json",
       "require": "./static/schemas/twake/nomenclature/twakeTitle.json"
     },
+    "./schema-twake-organizationgroups": {
+      "import": "./static/schemas/twake/organizationGroups.json",
+      "require": "./static/schemas/twake/organizationGroups.json"
+    },
     "./schema-twake-organizations": {
       "import": "./static/schemas/twake/organizations.json",
       "require": "./static/schemas/twake/organizations.json"

package/static/schemas/twake/organizationGroups.json

@@ -0,0 +1,32 @@
+{
+  "strict": true,
+  "attributes": {
+    "objectClass": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "test": "^[a-zA-Z][a-zA-Z0-9-]*$"
+      },
+      "default": ["top", "groupOfNames", "twakeGroup"],
+      "required": true,
+      "fixed": true
+    },
+    "cn": {
+      "type": "string",
+      "test": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+      "required": true
+    },
+    "member": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "test": "^[a-zA-Z]+=.*,__LDAP_BASE__$"
+      },
+      "required": false
+    },
+    "description": {
+      "type": "string",
+      "required": false
+    }
+  }
+}