ldap-rest 0.26.0 → 1.0.1

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.1",
   "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": [