Read-only user accounts

[nhoening]

I want to muse about enabling read-only demo accounts. A user who can not make any changed, just view data.

For this, one needs to know how Flexmeasures handles authorization with the __acl__ attribute - it is basically a system, where anything you get as a user (your account membership, consultancy relationships, user roles, ..) adds more access (gaining permissions on objects like assets, sensros, etc).

Here, we look at three ways this could work. The favourite is to add a restricitve read-only role for users - a role that works different than other roles.

A preamble about users without any roles - they can do the following actions in their account (non-exhaustive):

• edit account details
• add sensors
• upload data
• create forecasts
• edit flex-context and flex-model

Certain things are not possible for them, e.g. creating assets, linking consultancy accounts, etc.
This separation makes some sense, assuming that anybody with a user accoun has rights to do limimted things, and we'll see in the audit log that they did so.
It might not be perfect, but we can adjust later.

My current goal is to be able to offer user accounts who can only read. Imagine a demo asset with data, for which I give outsiders the credentials of a demo user who can browse.

What is the best architectural approach for this?
I'm looking for something that keeps the auth modeling straightforward, but also keeps our code changes low.

1st approach: read-only restrictive role

Easy implementatiom: Existing read grants work as they do now, but non-read permissions are centrally vetoed in check_access()

2nd approach: Having no roles = reader

This would mean that a pure user without roles can do nothing (see above on what they can do now). The only thing left is to read things in their account. This is conceptually cleaner, but it is a breaking authorization migration.

3rd approach: Users with no actual account (just "visitors")

They get as account a specific "External Users" account (which should own no assets, obviously), and be assigned to accounts viia a visitor relationship to get any access. This also seems like a large migration. It would be conceptually in line with being a purely additive role system, and good if we ever want any visitors to be able to read in more than one account.

So to summarize, there are ideas, but I vote to take the simpler route, which is the first option. It is rather easy for everyone to see why someone cannot do something ("they have a read-only role") and the implementation is straightforward. FlexMeasures should not become complex at a faster rate than needed. Am migration from option 1 to one of the others seems pretty straightforward to me, as well.

Let me know if there are ideas or opinions.

[Flix6x]

Proposal: a capability layer, with read-only as its first use

Thanks for opening this, Nicolas. Thinking it through made me question something underneath it: what can a user without roles do today, and is that set on purpose? From the ACLs on main, plain account members can upload data; trigger schedules, forecasts and reports; set up automations; create and edit sensors; create child assets (but not top-level ones); edit and copy any asset in the account; and edit the account's own details. They can't delete assets, sensors or data, and they can't manage users. The only place this is written down is a note in GenericAsset.__acl__ about the copy-but-not-delete asymmetry.

So before adding a read-only role, I'd like to make these rights explicit. Then read-only becomes one case of a general mechanism.

The idea: ACLs scope, roles grant

Today an ACL answers two questions at once: which objects a user may touch (their account's), and what they may do with them (all four verbs, for anyone in the account). I propose splitting these:

• The ACL keeps the scoping: "members of account 3, or consultants of its consultancy account".
• A named capability says what you may do. You hold it through your roles.

"trigger-schedules": [
    (f"account:{self.account_id}", "cap:trigger-schedules"),
    (f"account:{self.owner.consultancy_account_id}", f"role:{CONSULTANT_ROLE}", "cap:trigger-schedules"),
]

A new cap: principal type in policy.py calls user.has_permission(...) from Flask-Security-Too. Flask-Security has supported permissions on roles since 3.3; our Role model just lacks the permissions column. The permission vocabulary also grows beyond create-children / read / update / delete. Those verbs can't tell "upload data" apart from "trigger a schedule" (both are create-children on a sensor), or "rename an asset" apart from "change its flex-model" (both are update). Pyramid, which inspired our ACLs, lets permissions be any named strings for exactly this reason.

Proposed capabilities

About a dozen, named after what users do, not after endpoints:

read · post-data · annotate · trigger-schedules · trigger-forecasts · trigger-reports · manage-automations · edit-flex-config · edit-assets · edit-sensors · delete-data · manage-users · edit-account

edit-assets and edit-sensors include deleting assets and sensors that hold no data (see below). delete-data covers deleting beliefs and annotations, and deleting anything that holds them.

Proposed predefined roles

Role	Capabilities	Notes
read-only	read	The use case from this Discussion
integration	read, post-data	For credentials stored on devices and in integrations. A leaked token today is a full member token that can rewrite the flex-model
member	everything except the last three	Operate and configure
account-admin	all of the above	Govern: users, account, deleting data
consultant, admin, admin-reader, task-runner	unchanged	Consultant rights expressed as bundles too, scoped to client accounts as today

Deleting: members can delete what is empty

Deleting a sensor cascades to all its beliefs and annotations, and deleting an asset cascades to its whole subtree. So "members may delete what they may create" would really mean "members may delete data". Instead:

• A member can delete an asset or sensor only if nothing in it holds data: no beliefs on any sensor in the subtree, and no annotations. Deleting an annotation directly also needs delete-data.
• Anything that holds data needs delete-data, i.e. an account-admin.
• Automations stay deletable by members. Deleting one loses configuration, not recorded data, and members can already change that configuration.

This ends the copy-but-not-delete asymmetry, because copies carry no data. It also makes an ownership rule unnecessary: deleting a colleague's empty asset does about as much harm as editing it, which members can already do. "Is it empty?" depends on the object's state, not on who the user is, so I'd check it in delete_asset() / delete_sensor() rather than in __acl__, which runs for every delete button on list pages. The check is cheap: sensor_id leads the belief table's primary key.

One gap to fix along the way: an asset's deletion is logged on that asset's own audit log, and affected_asset_id is set to NULL when the asset is gone. Since asset audit logs are only queried per asset, the record of an asset's deletion (and the rest of its history) can then no longer be found through the API or UI. Child assets deleted in the cascade get no record at all. Sensor deletions are fine, because they are logged on the parent asset. I'd log asset deletions on the parent asset, or on the account's audit log for top-level assets.

Backwards compatibility

• A migration gives every existing user without a role the member role, and create_user() gives it by default. The CLI, the API and the UI all create users through that function, so API clients that create users see no change.
• Two changes to members' rights are deliberate. Members can delete assets and sensors that hold no data, and automations. Editing account details moves to account-admins, because renaming the organisation is a governance action.
• role: and account: principals keep working, so plugin ACLs don't break. One catch: a plugin ACL that grants writes to a bare account:{id} would also grant them to read-only and integration users. I'd log a deprecation warning whenever a non-read permission matches only a bare account principal, and ask plugin authors to add a cap:.
• One test tries every POST, PATCH and DELETE route as a read-only user and expects a 403. The only exceptions are the UI session preference endpoints. This guards against write endpoints that are decorated with read and only check the real permission inside, like /assets/<id>/copy today.

Why not a restrictive role (option 1)?

It would work, and it's less code. But it adds the first rule that takes rights away, so "why can X do Y?" can no longer be answered by finding a grant. It also leaves the implicit member rights undocumented. With capabilities, read-only is simply the role with the fewest of them, and the model stays additive. Option 2 doesn't need to be breaking either, if existing users are grandfathered into member as above; this proposal is essentially option 2 plus named capabilities. If we want the demo account soon, option 1 can go first. Its veto is easy to remove once read-only becomes a bundle.

Admin-defined roles

Once roles are bundles stored in Role.permissions, letting admins compose their own roles in the UI is mostly a checkbox form. I'd only build that when someone asks for it. It's the Django model (groups made of permissions, editable in the admin). Django's default add/change/view/delete permissions per model are also a warning: CRUD verbs are too coarse to hand to admins, which is another reason for named capabilities.

Open questions

• Should members be able to create top-level assets? Today only account-admins can, which limits sprawl. I lean towards keeping that behind edit-account or a separate capability.
• Should the role-to-capability mapping live in the database, which Flask-Security reads and which makes admin-defined roles cheap, or in code, which is easier to review? I lean towards the database, seeded and upgraded by migrations.
• Is integration worth its own role now, or should it come in a follow-up?

References

• R. Sandhu, E. Coyne, H. Feinstein, C. Youman, "Role-Based Access Control Models", IEEE Computer 29(2):38–47, 1996, doi:10.1109/2.485845. This is the basic users → roles → permissions indirection that this proposal adds.
• D. Ferraiolo, R. Sandhu, S. Gavrila, R. Kuhn, R. Chandramouli, "Proposed NIST Standard for Role-Based Access Control", ACM TISSEC 4(3), 2001, doi:10.1145/501978.501980, later standardised as ANSI INCITS 359-2004.
• Pyramid, Security: "Permissions are usually just strings, and they have no required composition: you can name permissions whatever you like."
• Kubernetes, Using RBAC Authorization: a Role bundles verbs on resources, and a RoleBinding grants it within a namespace. That's the same split as capabilities scoped to an account.
• Django, Permissions and authorization: groups as admin-editable permission bundles, plus custom permissions beyond per-model CRUD.
• Flask-Security-Too, API: RoleMixin.get_permissions(), UserMixin.has_permission(), permissions_required / permissions_accepted (all since 3.3.0).
• OWASP, Authorization Cheat Sheet: "Enforce Least Privileges" and "Deny by Default", which is the case for integration.
• For option 3 (visitors across accounts): R. Pang et al., "Zanzibar: Google's Consistent, Global Authorization System", USENIX ATC 2019. It's the standard reference for relationship-based access, if we ever need it. I don't think we do yet.

[nhoening]

I like the direction and will start playing with it.

One caveat: I see no need for the term "capabilities". As I udnerstand this, we are expanding the power of "permissions", as also Flask-Security calls them.

Modeling permissions on the Role model is an update we should in any case have done, but our model pre-dates Flask-Security 3.3 so we solved it in another way. Then, we expand the list of permissions.

• I agree that top-level assets are not to be created by anyone.
• I would include the integration capability
• I vote for role-to-permission mapping in the code (on the Role model)

Here is another question:

Role grants are global, even when ACL scope is local. In (account:…, role:consultant, cap:…), the capability can come from another role the user holds. A consultant’s member grants may therefore work in client accounts; consultant capabilities may also work in their own account. Decide explicitly whether that combination is intended. If rights must differ by client account, global Role.permissions needs account-scoped role bindings.
I will assume global for now.

[Flix6x]

Agreed on "permissions" over "capabilities", on including integration, and on keeping the mapping in code. A property on Role is enough for that: Flask-Security's get_permissions() only reads self.permissions, so no column or migration is needed, and a role without a code entry gets nothing (deny by default).

Taking the naming one step further: if the permission a role grants has the same name as the permission an endpoint asks for, ACLs don't need cap: tuples at all. check_access(context, "trigger-schedules") then requires that the ACL's scope matches and that the user holds trigger-schedules through a role. ACLs go back to only scoping. As a bonus, plugin ACLs that grant update to a bare account:{id} no longer let read-only users through, because they don't hold update.

On top-level assets: do you mean nobody except account-admins (as today), or really nobody?

On global grants, I'd rather not assume global, because it changes rights compared to today, in both directions:

• Consultants can create users in and delete assets of their client accounts, so the consultant role would need manage-users and delete-data. Held globally, those would also apply in the consultant's own account, where today only account-admins have them.
• Every user becomes a grandfathered member, so member permissions would apply in all client accounts too. That also makes a read-only consultant impossible to express.

Switching from global to scoped later would change what existing grants mean, so I'd decide now. A middle way that needs no account-scoped role bindings: tie each role to the scope it counts in. Home roles (member, account-admin, read-only, integration) only count when a home-account principal matches; consultant only counts when a consultancy principal matches. In check_access, that means looking up the permission only in the roles bound to the scope of the ACL entry that matched. Both leaks close and today's behaviour is preserved. Full per-client role bindings stay available as a next step, if a consultant ever needs different rights per client.