The API Payload Security Pipeline: Order, Protection Levels and Keys closed by changing axis. A protection level governs the form of one call, and at no point does it ask which data this person may see.
Permissions are something an ERP system cannot avoid, and they have never been one question. They are three: whether a buyer may delete a purchase order, which orders may be deleted, and whether the cost column on that order can be seen at all, or changed. The three answers come from different sources, and they are enforced in different places.
This post covers:
- What
X-Api-KeyandAuthorizationeach answer, and why neither of them is a permission - Where the action axis is granted, and why a form that declares nothing skips the whole thing
- Who declares the scope on the row axis, how it becomes one SQL statement, and why assembling it never queries the database
- Why the column axis exists only on the front end, and why it is not bound to the same permission model
1. First, separating out the check that is not a permission
A remote caller carries two headers, and neither of them answers what this person may do:
| Header | What it answers | Where the answer comes from |
|---|---|---|
X-Api-Key |
Which application is calling | The keys already issued in st_api_key
|
Authorization: Bearer |
Who is calling | A session that has not expired |
The key itself grants no data permission at all. What it identifies is the calling application, and authenticating the user is the access token's job. JSON-RPC 2.0: Protocol Choice and the Request Pipeline mentioned a list of methods that need no header, and there are in fact two such lists, one per header.
On the token side there is one more check, declared on the method. [ApiAccessControl] takes two parameters. The protection level from the previous post is one of them, and the other has only two values, Anonymous and Authenticated. What it asks is whether this method needs a valid token, not what this person may do.
Once those are answered, who this is and which application they came from are both settled. Permissions start after that, and they split into three axes:
| Axis | What it asks | Server | Front end |
|---|---|---|---|
| Action | Whether this can be done at all | The authoritative decision | The state of toolbar commands |
| Row | Which records it can be done to | The query condition, and reading back on write | Takes no part |
| Column | What can be seen and what can be changed | Masks nothing | Hides, masks or locks read only |
The last two of those are the ones to look at. The three axes are not three parallel mechanisms, because where they run is not the same: action runs on both ends, row only on the server, and column only on the front end.
2. Action: whether this can be done at all
The action axis is bound to a business entity, not to a form. Which permissions there are to talk about is registered in PermissionModels, and a FormSchema declares a PermissionModelId pointing at one of them, with the grant sitting on that model. Both excerpts in this post come from FormBusinessObject.Permission.cs:
var modelId = DefineAccess.GetFormSchema(ProgId).PermissionModelId;
if (string.IsNullOrEmpty(modelId)) { return; }
if (!authorization.Can(AccessToken, modelId, action))
throw new ForbiddenException($"Permission denied: '{action}' on model '{modelId}'.");
Binding to a business entity buys something very practical in an ERP system: one model can be consumed by several ProgIds. Creating an order, querying orders and the report all reference the same PurchaseOrder, so one grant takes effect on all three. Bind to the form instead and the same purchasing permission has to be granted three times, once per form, and the one that gets missed shows no symptom at all. It is simply looser than the others.
There are six action flags: insert, query, update and delete, plus printing and exporting, the two that take data out. The latter two are listed separately because printing a purchase order or exporting it to a spreadsheet takes the data out of the system just the same, and being able to read is not the same thing as being able to carry the whole lot away once auditing is involved. State transitions such as submitting for approval, posting and confirming are deliberately kept off this axis, since those belong to workflow permissions.
There is one opening here. A form that declares no PermissionModelId skips the whole thing, with neither action nor row applied, so that existing forms can be rolled out one at a time.
The front end narrows too, but only follows
Action is the only one of the three axes that runs on both ends. The front end's share is only about not putting actions this user has no permission for in front of them to click: it receives a list of what this person may do, and hides or disables those commands accordingly.
But it stops nobody. The server's check is the boundary, and it has to be, because the standard screen is only one caller among several: another front end, a script, an integration hitting the API directly, none of them pass through that layer. If the front end fails to narrow, the server refuses all the same.
A command can carry more than one flag, since saving is both an insert and an update, and a command like that shows as long as one of them is held, with whether it is actually allowed decided on the server. Guessing wide on the front end is not a security problem, while guessing narrow leaves the user thinking the feature is broken.
3. Row: which records it can be done to
The declaration on the row axis is split across two places, and deliberately does not overlap. A role's grant states a strategy, and the FormSchema marks which column:
ScopeStrategy |
Condition added when reading |
|---|---|
All |
No restriction |
Own |
The owner column IN the user row id and the employee row id |
Dept |
The department column matches the department the person belongs to, ORed with Own
|
DeptAndSub |
The department column IN that department and all its descendants, ORed with Own
|
A strategy never names a column, and the column is marked Owner or Dept by FormField.ScopeRole. What splitting them buys is that the same set of strategies holds for every form: moving to another form changes only which column carries the mark, with no new strategy to write. Own matches two identities, because the same column can hold whoever entered the record on one form and the employee the record is about on another. One role can see a whole department while only being able to change its own records, since a grant is one row per action and the scope travels with that row.
The same role marker can sit on more than one column of a master table. A staff transfer document has a department transferred out of and a department transferred into, and the managers on both sides should see it, so both columns are marked Dept and the condition that comes out is the union of two branches.
The role, role grant and user role binding tables land in the company database rather than the shared one, so the same person can hold two completely different roles at two companies. This is one of the examples behind Connections, Transactions and Query Conditions in the Data Access Layer saying the prefix answers who owns a table and the database category answers where it lives: all three carry the framework's own prefix, yet sit on the company side.
Add a condition when reading, and read back when writing
What the strategy and the markers work out to is a FilterNode. That same post established that a query condition is a tree living in the definition layer, with not one conversion between the condition the user fills in and each of five databases assembling its own statement. Permission filtering produces a tree of the same type, attached straight alongside the user's, and the two together are one FilterGroup.All. Rows outside the scope are filtered out of a list, and a single record query returns null, indistinguishable from no such row, so a caller cannot use it to probe whether an invisible row exists.
The write side cannot use the same trick. The DataSet that arrives is the caller's, and the department column in it can say whatever they like, so comparing the value in the payload against the scope amounts to letting the person being blocked fill in the answer. What the framework does is read back once:
if (!repository.ExistsInScope(rowId, scopeFilter))
throw new ForbiddenException($"Record out of scope for '{action}' on model '{schema.PermissionModelId}'.");
ExistsInScope issues WHERE sys_rowid = this row AND the scope condition, asking whether that row in the database is inside the scope, which a forged payload cannot move. Delete takes the same path, and out of scope it deletes zero rows with no cascade. Insert applies no scope, since a row that does not exist yet has no existing scope to violate, and whether it may be inserted is the action axis's business.
Multiple roles are always unioned
One person carrying several roles is normal in an ERP system, and the rule is the same on the action and row axes: union. Action flags are ORed together and scope conditions are ORed together, and if any one role gives All on this action, the whole scope is unrestricted.
Put the other way, this model has no deny grants. Give him the purchasing manager role but block delete cannot be done here, since adding another role only adds permissions and never removes any, and the only way to get that effect is to split off a role without delete and give him that instead. What it buys is traceability: if someone can delete, some one role gave it to them.
How those conditions become one SQL statement
Turning that tree into SQL takes only two rules, and they are recursive: a group collapses into a pair of parentheses with AND or OR between the parts, and a single condition collapses into one comparison with the value always replaced by a parameter. With a role holding DeptAndSub, a master table marking a department column and an employee column, and the user filling in the start of a document number on the list, what comes out is this:
WHERE ((dept_rowid IN (@p0, @p1) OR emp_rowid IN (@p2, @p3)) AND sys_no LIKE @p4)
The outer AND is the seam between the permission and the user's condition, and the inner OR is the department subtree or one's own. The user only ever sees the half they filled in, with the other half attached by the server, and there is no way for them to work back from the returned data to what that half looks like.
Two details remain. First, @p0 through @p3 are four department and identity ids, all going through parameters, while column names take the other route, looked up against the definition and then given identifier quoting. The earlier post's line about parameterization stopping values but not column names is about exactly that fork, and permission conditions are no exception. Second, when the scope resolves to no usable grant, what comes out is not an empty condition but an empty IN, which lands in SQL as 1 = 0. That is deliberate, because an empty condition on this path means unrestricted, and the direction of failure has to be closed.
There is one more thing that statement does not say: assembling it never queried the database. Roles and grants and the department organization tree are all per company caches that read the source once when there is no hit, the same shape as in Cross-Node Invalidation for Definition and Data Caches with the source swapped for the database, and the three row ids come from the session snapshot that Session Management and Lifecycle resolves once on entering a company.
What the department part saves is more than one query. DeptAndSub wants this department and all its descendants, and with the organization tree already in memory the subtree flattens in place into a list of ids, landing in SQL as nothing more than a flat IN. Without that tree every query would have to expand the subtree recursively in the database, and recursive queries are written differently by each of five databases, which amounts to growing five more dialects along the permission path.
Deciding runs entirely in memory, and only applying touches data. The read side costs nothing, with the condition merged into the statement that was going to run anyway, and only the write side adds one SELECT sys_rowid per changed master row, while a save that only inserts queries nothing at all.
4. Column: what can be seen and what can be changed
A purchase order has a cost column. The buyer can see it, a sales assistant should not, and the cost column does not appear only on purchase orders. It is scattered across quotations, goods receipts and stock queries.
The column axis is declared on FormField.SensitiveCategory, whose value comes from a closed list: amount, cost, personal data, plus the default of no category. Picking a category rather than letting each form invent an identifier of its own is because a category is a cross form data question, not that form's question. A column marked cost is governed by the same grant wherever it appears, so whether this person may see cost is granted once and takes effect everywhere.
So the permission model it binds to is not the same one the other two axes use. Action and row go through the PermissionModelId the form declares for itself, and column goes through the one the category name maps to. That means whether a purchase order may be changed and whether cost may be seen are two independent grants, and one person can be given every action on purchase orders while still not being shown cost.
A column's permission has two levels, viewing and modifying, and modifying only comes into question once viewing is allowed. The front end handles them two ways: what may not be viewed is hidden or masked, and what may not be modified is locked read only.
Last is this axis's boundary: the column axis exists only on the front end. The server applies no column permission when fetching data, GetList and GetData return the values of sensitive columns just the same, and callers that do not pass through a front end get the complete row. This is not an oversight. Form fields often take part in computation, and the framework runs one and the same expression on both ends, so with one of those columns missing those calculations come out on neither end. The framework therefore marks this axis as a presentation layer matter, and data that genuinely must not leave the server has to be placed on one of the other two boundaries, action or row.
In closing
Permissions in this framework are three questions, not one, and what separates the three axes is not only what they ask but who enforces them:
- Action, whether this can be done at all. Granted on a business entity rather than on a form, so one model can be shared by several forms; done on both the server and the front end, with the server end being the boundary
- Row, which records it can be done to. The role gives the strategy and the
FormSchemamarks the column, deliberately without overlap, so moving to another form changes only which column carries the mark; the read side merges the condition into the statement that was going to run anyway, and the write side does not trust what arrives, always reading back the authoritative copy - Column, what can be seen and what can be changed. Bound to the other model the category name maps to, so independent of the first two axes; and it exists only on the front end
Multiple roles are always unioned, adding and never subtracting, and what that buys is that every permission can be traced to where it came from.
What lets the first two axes finish deciding without touching the database is holding the grants and the organization tree in memory in full. The tree matters most, since it turns a recursive query into a flat IN, one way of writing it shared by all five databases.
Resolving to no grant produces an always false condition rather than an empty one, and an out of scope single record query comes back as no such row rather than not authorized, both of them falling to the closed side. The one thing that falls to the open side is a form that declares nothing skipping the whole thing, a door left open so that an existing system can be rolled out one form at a time.
The next post, The Audit Trail and the Before and After Values of a Change, closes this chapter, on what these decisions leave behind: who, at what time, on which record, did what, and from which value to which value.
📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework
📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-24-permission-axes
📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook | HackMD | GitHub | NuGet
Top comments (0)