ldap-rest 0.26.0 → 1.0.0

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
 

package/docs/usage/upgrading.md

@@ -4,6 +4,234 @@ 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.
 
+## From 0.26 to 1.0.0
+
+Every breaking change since 0.26.0. Authorization fails closed in 1.0.0:
+what used to pass because a call site forgot the request, or because a
+name was spelled otherwise, is now judged, and may be refused.
+
+### Attribute names in a write: one name per attribute, no option
+
+**Who is affected:** a client, a CSV of the bulk import or a plugin writing
+an attribute with an option other than `;binary` (`title;lang-fr`,
+`member;x-tag`), or naming one attribute twice in one part of a write
+(`mail` and `MAIL`, `mail` and `rfc822Mailbox`).
+
+Every add and modify now names its attributes as this server does before
+it is judged: the name is resolved through the directory schema, so `MAIL`,
+`rfc822Mailbox` and `0.9.2342.19200300.100.1.3` are all written `mail`.
+The spelling kept is the configuration's or a loaded schema's, else the
+first name the directory declares. An option other than `;binary` is
+refused with a 400: a tagged value is one of its own, which the rules
+guarding the attribute would not see. Two names for one attribute in one
+`add`, `replace` or `delete` are refused with a 400 too. Values already
+stored under an option are still read, but cannot be written or deleted
+through ldap-rest: clean them up in the directory.
+
+A rename gives the entry one value of the attribute it is already named by
+(`cn=new` for a group named by `cn`): a new RDN holding several values, or
+naming another attribute, is refused with a 400. The directory writes the
+values of the new RDN on the entry, where no check of a write saw them.
+
+When the directory schema cannot be read, the names, aliases and OIDs of
+the standard types (`cn`, `mail`, `uid`, `ou`…) are still resolved, as are
+the spellings of the configuration and the schemas. A name given as another
+OID is refused, and another alias is written as given.
+
+### SCIM group members are looked up as the caller
+
+**Who is affected:** a SCIM client writing group members by DN, and one
+that tells an absent user from a hidden one by the message of
+`PUT /Users/{id}`.
+
+A member given by DN in `POST`, `PUT` or `PATCH /Groups` was taken as it
+stood. It is now looked up as the caller, as a member given by id is: a DN
+the caller cannot read, or that names no entry, is left out of the group,
+and under a model judging by branch a member in a refused branch makes the
+whole write refused. A DN outside the user base is left out, compared RDN by
+RDN. A client that wrote members it may not read asks an administrator
+whose rules cover them.
+
+`PUT /Users/{id}` on a user that is not there answered `Resource not found`;
+it now answers `User {id} not found`, as it did for a user the caller may
+not read. The status, `404`, is unchanged.
+
+### The group routes take a DN for a group only
+
+**Who is affected:** a client calling `/api/v1/ldap/groups/{cn}` with a
+DN rather than a name.
+
+A DN given to these routes, to read, write, delete, create or rename a
+group, must name a group below the groups branch (`--ldap-group-base`),
+named by the groups' main attribute (`--ldap-groups-main-attribute`, `cn`
+by default) and of a group class (`--group-class`, or a standard one) the
+caller reads; anything else answers `404 Group not found`, and a DN the
+directory would refuse `400`. A client that managed the organization
+groups of `core/twake/groups` by DN through these routes, when they lie
+outside `--ldap-group-base`, uses `/api/v1/organizations/{id}/groups`.
+A deployment whose groups carry a class of their own, and none of the
+standard ones, declares it in `--group-class`.
+
+### Reference data still in use is not deleted
+
+**Who is affected:** a deployment loading the shipped `twake` or `example`
+schemas with `core/ldap/enterpriseRules`.
+
+Deleting a mail domain an organization links, or a nomenclature value an
+entry holds (account status, delivery mode, personal title, list type,
+mailbox type), answers `409 still referenced` instead of leaving the
+reference naming nothing. Change the referrers first. A deployment with
+its own schemas marks its pointers `"referentialIntegrity": "restrict"` to
+get the same. References are looked for under the base each entity is
+configured with; a base the directory does not hold is logged once and
+holds none.
+
+### Plugins: an operation naming no request is judged as the caller
+
+**Who is affected:** a third-party plugin calling `this.server.ldap.search`,
+`add`, `modify`, `rename` or `delete` without a request, from a route, while
+an authorization plugin is loaded. `move` is the server's and stays unjudged:
+move an entry for a caller with `rename`.
+
+Such an operation used to pass unjudged, as the server's. While an
+authenticated request is being served, it is now judged as that request's
+caller, and refused where the caller may not. Hand the request down
+(`ldap.forRequest(req)`), or, for the server's own work, go through
+`ldap.system`. Hooks run outside the request and keep acting as the server.
+
+Under `core/auth/authzDynamic`, a hook's operations that named no request
+used to be judged against the token, through an async context of the
+plugin's own; they now act as the server, as under the other authorization
+plugins. A hook writing on the caller's behalf passes the request it is
+handed. That context, `authzContext`, is no longer exported: read the token
+off the request (`req.authzToken`).
+
+### An authorization plugin needs an authentication plugin
+
+**Who is affected:** a deployment loading `core/auth/authzPerBranch`,
+`core/auth/authzLinid1` or `core/auth/authzPerRoute` without any
+authentication plugin.
+
+Such a server no longer starts. No request carried an identity, so each of
+these plugins stepped aside and every request passed, whatever the rules
+said. Load the authentication plugin the rules were written for, or remove
+the authorization plugins to serve the directory openly, as it already was.
+
+### Nested branch rules of `authzPerBranch`
+
+**Who is affected:** a deployment of `core/auth/authzPerBranch` whose rules
+for one user, or one group, name a branch and a sub-branch of it.
+
+The rule of the sub-branch now applies to everything below it, whatever
+order the two are written in. It used to apply only where it matched
+exactly — the sub-branch entry, and writes on its direct children, judged
+on their parent — and below that the first rule written won. A sub-branch rule that
+was ignored, a restriction or a grant, now takes effect in single reads and
+writes and in searches: a search on the parent no longer lists what the
+sub-branch rule refuses, so a listing may now be shorter. Check such rules:
+they now mean what they say.
+
+`default` no longer adds to what the rules grant: it applies to a
+permission none of the rules that apply sets. A rule's `read`, `write` or
+`delete` set to `false` now refuses, where `"default": {"read": true}` used
+to grant it anyway. A permission a rule leaves unset is still the
+default's, not the broader rule's.
+
+Renaming or moving an entry a rule names, or one holding such an entry, now
+needs read and write permission at each of those rules, and deleting it
+needs delete there; changing the entry itself needs that rule's write
+permission, as does creating it. A write setting the organization link and
+changing anything besides the link and its path needs write where the
+entry stands — its branch, or under `--authz-filter-attached-entries` the
+organization it leaves: it used to need only read there, so the rest of
+the write — a password, say — went through. Moving an entry between
+organizations is unchanged.
+
+### Organization groups need read access to the organization
+
+**Who is affected:** a deployment loading an authorization plugin together
+with `core/twake/groups` (and `core/twake/spaces`, which goes through it).
+
+The `/organizations/{id}/groups` and `/organizations/{id}/spaces` routes read
+as the caller. A client calling them must be granted read access to the
+organization, its groups and its users, write access to change them and
+delete access to delete one. An organization it cannot read answers `404`,
+and a user it cannot read `404 USER_NOT_FOUND` where it used to get `403`.
+
+Under `core/auth/authzLinid1` or `--authz-filter-attached-entries`, groups
+written in an organization's branch now carry its link
+(`--ldap-organization-link-attribute`): creating or changing a group needs
+write on the organization, and a group without a link is read and changed by
+every administrator. Link the groups written before; this script is an
+example to adapt to your patterns, attribute names and organization names
+(it expects plain ones, without spaces or commas):
+
+```sh
+# Connection to the directory, as for any ldapsearch
+OPTS="-H ldap://localhost -D cn=admin,dc=example,dc=com -w secret"
+# --twake-group-organization-dn and --twake-group-base, {org} left out
+ORGS="dc=example,dc=com"
+for org in $(ldapsearch $OPTS -LLL -s one -b "$ORGS" '(ou=*)' ou |
+  sed -n 's/^ou: //p'); do
+  ldapsearch $OPTS -LLL -o ldif-wrap=no -s one \
+    -b "ou=groups,ou=$org,$ORGS" '(!(twakeDepartmentLink=*))' objectClass |
+    awk -v link="ou=$org,$ORGS" '
+      function flush() {
+        if (!dn) return
+        print "dn: " dn "\nchangetype: modify"
+        # The class is added only to a group lacking one allowing the link
+        if (!held) print "add: objectClass\nobjectClass: twakeGroup\n-"
+        print "add: twakeDepartmentLink\ntwakeDepartmentLink: " link "\n"
+        dn = ""
+      }
+      /^dn: / { flush(); dn = substr($0, 5); held = 0 }
+      tolower($0) ~ /^objectclass: (twakegroup|twakestaticgroup)$/ { held = 1 }
+      END { flush() }'
+done | ldapmodify $OPTS
+```
+
+### The organization link holds one organization
+
+**Who is affected:** a client or a CSV writing several organization links on
+one entry, or an empty one.
+
+A write giving the organization link (`--ldap-organization-link-attribute`)
+several values, or an empty value, is refused with a 400: only one of them
+was judged. Under any spelling of the attribute, adding a link to an entry
+that had none is judged as a move: write where it goes and, judged by
+branch, read where it stands.
+
+### Smaller changes in answers
+
+- `GET /api/v1/ldap/raw/search` below a base the caller may not read
+  answers 404, as for a base that is not there; under `authzPerBranch`
+  judging by DN it answered 403.
+- Changing only the case of an account's mail is refused (409) while an
+  applicative copy holds the old spelling, which the directory takes for
+  the same address.
+
+### External members in a domain the directory declares
+
+**Who is affected:** a deployment of `core/ldap/externalUsersInGroups`
+adding as external members addresses in a mail domain the directory
+declares, without listing it in `--mail-domain`.
+
+Such a member is refused, as one in a `--mail-domain` already was. The
+managed domains are now also those of the directory's domain branches,
+[docs](plugins/ldap/external-users.md#important-notes); `GET /config` lists
+them in `managedDomains`.
+
+### Quota and app accounts need read access to the account
+
+**Who is affected:** a deployment loading an authorization plugin
+(`core/auth/authzPerBranch`, `authzLinid1`, `authzDynamic`) together with
+`core/twake/james` or `core/twake/appAccountsApi`.
+
+`GET /users/{user}/quota-usage` and the app account routes answer `404` for
+an account the caller cannot read. A client calling them must be granted
+read access to the accounts it asks about, as it already needed write
+access to create or delete an app account.
+
 ## To 0.24.0
 
 ### Links to deleted accounts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ldap-rest",
-  "version": "0.26.0",
+  "version": "1.0.0",
   "description": "Light directory manager",
   "keywords": [
     "Identity-Manager"

package/static/schemas/example/groups.json

@@ -50,6 +50,7 @@
     "businessCategory": {
       "type": "pointer",
       "branch": ["ou=twakeListType,ou=nomenclature,__LDAP_BASE__"],
+      "referentialIntegrity": "restrict",
       "required": false,
       "role": "writePolicy",
       "label": "List type"

package/static/schemas/example/organizations.json

@@ -89,6 +89,7 @@
         "type": "pointer",
         "branch": ["ou=domains,ou=nomenclature,__LDAP_BASE__"]
       },
+      "referentialIntegrity": "restrict",
       "required": false,
       "role": "domainLink",
       "label": "Mail domains"

package/static/schemas/example/users.json

@@ -77,6 +77,7 @@
     "personalTitle": {
       "type": "pointer",
       "branch": ["ou=twakeTitle,ou=nomenclature,__LDAP_BASE__"],
+      "referentialIntegrity": "restrict",
       "required": false,
       "label": "Title"
     },
@@ -203,6 +204,7 @@
     "twakeAccountStatus": {
       "type": "pointer",
       "branch": ["ou=twakeAccountStatus,ou=nomenclature,__LDAP_BASE__"],
+      "referentialIntegrity": "restrict",
       "required": true,
       "generated": true,
       "role": "accountStatus",
@@ -220,6 +222,7 @@
         "type": "pointer",
         "branch": ["ou=twakeDeliveryMode,ou=nomenclature,__LDAP_BASE__"]
       },
+      "referentialIntegrity": "restrict",
       "required": true,
       "generated": true,
       "default": [

package/static/schemas/twake/groups.json

@@ -82,6 +82,7 @@
     "businessCategory": {
       "type": "pointer",
       "branch": ["ou=twakeListType,ou=nomenclature,__LDAP_BASE__"],
+      "referentialIntegrity": "restrict",
       "required": false,
       "role": "writePolicy",
       "label": {
@@ -98,6 +99,7 @@
     "twakeMailboxType": {
       "type": "pointer",
       "branch": ["ou=twakeMailboxType,ou=nomenclature,__LDAP_BASE__"],
+      "referentialIntegrity": "restrict",
       "group": {
         "en": "Mailbox Settings",
         "fr": "Paramètres de messagerie",

package/static/schemas/twake/organizations.json

@@ -123,6 +123,7 @@
         "type": "pointer",
         "branch": ["ou=domains,ou=nomenclature,__LDAP_BASE__"]
       },
+      "referentialIntegrity": "restrict",
       "required": false,
       "role": "domainLink",
       "label": {

package/static/schemas/twake/teamMailboxes.json

@@ -80,7 +80,9 @@
       }
     },
     "twakeMailboxType": {
-      "type": "string",
+      "type": "pointer",
+      "branch": ["ou=twakeMailboxType,ou=nomenclature,__LDAP_BASE__"],
+      "referentialIntegrity": "restrict",
       "default": "cn=teamMailbox,ou=twakeMailboxType,ou=nomenclature,__LDAP_BASE__",
       "fixed": true,
       "required": true,

package/static/schemas/twake/users.json

@@ -124,6 +124,7 @@
     "personalTitle": {
       "type": "pointer",
       "branch": ["ou=twakeTitle,ou=nomenclature,__LDAP_BASE__"],
+      "referentialIntegrity": "restrict",
       "required": false,
       "label": {
         "en": "Title",
@@ -324,6 +325,7 @@
     "twakeAccountStatus": {
       "type": "pointer",
       "branch": ["ou=twakeAccountStatus,ou=nomenclature,__LDAP_BASE__"],
+      "referentialIntegrity": "restrict",
       "required": true,
       "generated": true,
       "role": "accountStatus",
@@ -346,6 +348,7 @@
         "type": "pointer",
         "branch": ["ou=twakeDeliveryMode,ou=nomenclature,__LDAP_BASE__"]
       },
+      "referentialIntegrity": "restrict",
       "required": true,
       "generated": true,
       "default": [