This post documents our current asset API security, what users can read and write in the asset tree.
You can read more following the docs on the main entry point: https://github.com/openremote/openremote/blob/master/manager/shared/src/main/java/org/openremote/manager/shared/asset/AssetResource.java
There is the superuser who has full access across all tenants (realms). In an OpenRemote installation there is only one superuser, and it's always named 'admin' and it's always in the 'master' realm. It cannot be renamed or deleted, just like the master realm.
Each realm can have regular users. Those would usually have administrative functions within a realm, they manage the realm. Depending on assigned roles, a regular user may read/write any asset data in the realm or manage other users in the realm.
Finally there are restricted users within a realm. The definition of such a user is a regular user that has been linked to a set of assets within its realm. This is a many-to-many relationship, an asset might be linked to many users, and a user might have links to many assets. The position of the assets within the asset tree is not relevant, linking a user with a parent doesn't mean it is linked to its child assets. The existence of linked assets is what makes a user "restricted". Assets which are linked to a user are considered "protected"; they are not private or for managers only, yet still require authentication to access. (In future we might add "public" to our access permissions, which would then not require authentication.)
Consider the following example: You are the manager of a smart building with many apartments. A realm/tenant has been created for the whole building. The superuser who created the realm gives you a regular account in that realm and all the roles you need. You now want to give the residents of the apartments individual accounts, one per residence. You must limit what the residents can access within the building. Each resident's account should only be able to access a particular Residence asset, representing their apartment, but not the whole Building asset. To further limit access to the necessary minimum, you would then also give each resident access to some Room and Thing assets within the apartment. You would however not give access to any Agent assets, as this would allow the resident to configure connections to actual services and devices. Only managers should be allowed to do that; the same applies to any other assets you want to keep private.
Restricted users can only access their linked assets and depending on assigned roles, may read/write such asset data. Furthermore, not all asset data can be accessed by restricted users. Within each asset there are basic properties such as asset name, type, and location. Each asset can contain arbitrary attributes, and each attribute can have metadata associated with it. Some of those details should be kept private, even if the asset is made protected and linked to restricted users. Consider a Thing asset, which you make protected so users can read some sensor attributes and modify some actuator attributes. You don't want to expose configuration attributes however, which might contain sensitive information, such as internal device identifiers or credentials.
A restricted user can therefore only access "protected" asset details. Some asset details are always considered protected, for example, the asset name, type, and location. The attributes of an asset can be marked individually as "protected". By default each attribute is "private" and not exposed to restricted users. Finally, asset attribute metadata is only exposed to restricted users if the meta item name matches an internal whitelist of safe metadata. (We might switch to a metadata blacklist but as we can only filter by item name, it's not obvious how we can avoid leaking sensitive data.)