5.8.8. Security Constraints for Collection Attributes

Let’s consider the following situation:

  • Your data model contains Order and OrderLine entities which form the one-to-many composition.

  • Your REST client loads an instance of Order together with the nested collection of OrderLine instances.

  • There are security constraints that filter out some OrderLine instances, so the client does not load them and doesn’t know they exist. Say line5 is not loaded by the client but exists in the database.

  • If your client removes, say, line2 from the collection and then saves the whole composition using the /entities/{entityName}/{entityId} endpoint, there are two outcomes:

    1. If the constraints were not changed since the entities were loaded, the framework restores the filtered line5 instance in the collection and deletes only line2, which is the correct behavior.

    2. If the constraints were changed in a way that line5 is now available to the client, the framework cannot restore the information about filtered collection elements correctly. As a result, both line2 and line5 will be deleted.

If you are concerned with the case described above, you can eliminate possible data loss by sending a special system attribute in the JSON representing your entities. This attribute is called __securityToken and automatically included in resulting JSON if the cuba.rest.requiresSecurityToken application property is set to true. The responsibility of your REST client is to return this attribute back when saving entities.

An example of entity JSON including security token:

{
  "id": "fa430b56-ceb2-150f-6a85-12c691908bd1",
  "number": "OR-000001",
  "items": [
    {
      "id": "82e6e6d2-be97-c81c-c58d-5e2760ae095a",
      "description": "Item 1"
    },
    {
      "id": "988a8cb5-d61a-e493-c401-f717dd9a2d66",
      "description": "Item 2"
    }
  ],
  "__securityToken": "0NXc6bQh+vZuXE4Fsk4mJX4QnhS3lOBfxzUniltchpxPfi1rZ5htEmekfV60sbEuWUykbDoY+rCxdhzORaYQNQ=="
}

The __securityToken attribute contains encoded identifiers of filtered instances, so the framework can always restore the required information regardless of changes in constraints.