The most dangerous authorization defect in a multi-tenant device platform is rarely a missing menu permission. It is the assumption that a principal with command:write may control every device returned by the application. RBAC can state which type of action a role may perform. By itself, it cannot establish which tenant the request belongs to, which site or device group contains the target, which service provider owns the operational relationship, how far a bulk action can fan out, or whether a temporary maintenance grant has already expired.
A dependable model therefore evaluates a chain of conditions for every resource request: the subject identity is trusted, the tenant context is valid, the action is permitted, the resource scope intersects, the service-owner boundary matches, and the operational context remains valid. A failure at any layer must deny the request. The same principle applies to list queries, object reads, APIs, service accounts, remote commands, OTA jobs, and fleet operations, although each surface needs a different enforcement shape.
This article uses the current Grus IoT Core authorization implementation and 13 targeted tests as first-hand evidence. Those tests show fail-closed behavior for tenant, permission, scope, service-owner, and cross-tenant command boundaries in the tested code. They are not a production penetration test, a compliance certification, or evidence that policy caching, database concurrency, and MQTT topic ACLs work at arbitrary fleet scale.
1. Model the complete request before defining roles
An authorization request in a device platform contains at least six objects: subject, tenant, action, resource, scope, and context. A matrix containing only roles, menus, and buttons controls the user interface. It does not define the resource boundary.
- The
subjectmay be a human user, service account, or integration adapter, not merely a username. - The
tenantis the customer boundary the request may enter; ordinary callers must not select it freely. - The
actionis a stable auditable verb such asdevice:read,command:write, orota:write. - The
resourceis a device, device group, site, alarm, command, report, or rollout job. - The
scopeidentifies the project, site, space tree, or device group visible to the subject. - The
contextcarries service ownership, access channel, expiry, work order, risk level, and trace identity.
RBAC remains useful because action capabilities need centralized governance. The problem begins when the role decision is treated as the final answer. A vendor role may legitimately hold device:read and command:write, but those permissions should apply only to devices assigned to that vendor and should remain constrained by tenant and site scope. If a platform authorizes by role first and leaves resource filtering to individual business handlers, the first endpoint that forgets the filter becomes a cross-customer leak.
The API boundary should obtain a trusted identity and the target resource facts, then submit a complete decision input to a shared authorization layer. Application services should not infer that an administrator “probably has access.” Repositories should not fetch an unrestricted table and rely on an in-memory loop to delete rows after pagination, aggregation, or caching has already exposed information.
2. Close the five-layer decision chain at every resource boundary
The following chain is not five unrelated permission systems. It is one decision in which RBAC covers the action dimension while the other layers constrain the resource and operational context.
flowchart LR
A("Trusted identity and tenant"):::blue --> B("Action permission"):::cyan
B --> C("Site / device-group scope"):::orange
C --> D("Service-owner boundary"):::violet
D --> E("Expiry, ticket, and risk context"):::slate
E --> F("Allow and audit"):::green
A -. mismatch .-> X("Deny by default"):::deny
B -. not allowed .-> X
C -. no intersection .-> X
D -. owner mismatch .-> X
E -. expired or unsupported .-> X
classDef blue fill:#EAF4FF,stroke:#3B82F6,color:#16324F,stroke-width:2px;
classDef cyan fill:#E9FBF8,stroke:#14B8A6,color:#134E4A,stroke-width:2px;
classDef orange fill:#FFF3E8,stroke:#F08A24,color:#7C3F00,stroke-width:2px;
classDef violet fill:#F4EDFF,stroke:#8B5CF6,color:#4C1D95,stroke-width:2px;
classDef green fill:#ECFDF3,stroke:#22C55E,color:#14532D,stroke-width:2px;
classDef slate fill:#F8FAFC,stroke:#64748B,color:#1F2937,stroke-width:2px;
classDef deny fill:#FFF1F2,stroke:#E11D48,color:#881337,stroke-width:2px;
The first layer is identity-bound tenancy. A tenant_id claim or request header must not become a general tenant switch. In the tested Grus OIDC path, the platform resolves the immutable external identity binding before loading effective roles and scopes from the database. Only a platform-level role obtained from a trusted authority may select another tenant context. Targeted tests verify that a tenant administrator cannot switch tenants and that a role self-asserted in an otherwise untrusted token cannot grant cross-tenant access.
The second layer is action permission. Permission names should be stable resource-and-verb contracts such as device:read, command:write, and audit:read. Separating device observation from physical control allows a diagnostic operator to investigate without receiving command authority. Granularity can also go too far: one permission string per button creates a policy set that is difficult to review and encourages unexplained role exceptions.
The third layer is resource scope. A tenant can contain projects, sites, production lines, rooms, homes, or device groups. Membership in the same tenant does not imply visibility across all of them. A site engineer may read devices and alarms for one plant without seeing a sibling plant. This scope check must constrain repository queries and object reads, not merely hide nodes in a frontend tree.
The fourth layer is service ownership. Devices may be operated by installers, channel partners, vendors, or integration adapters. Service ownership is not another tenant: the tenant identifies the customer isolation boundary, while the owner states who is responsible for a resource inside that customer. The tested Grus policy requires an owner claim for service subjects such as installer, vendor, and service_adapter, then compares it for device, command, alarm, audit, OTA, and reporting actions. A missing or mismatched owner fails closed.
The fifth layer is operational context. Long-lived roles should not permanently open high-risk actions. Bulk restart, firmware rollout, credential rotation, and remote control need an expiry, work or change ticket, frozen target set, reason, approval source, and trace id. This context is not a note attached after approval; it must be part of the authorization decision and the audit record.
3. Lists, object reads, and commands need different enforcement shapes
Authorization often looks correct on a single-object endpoint while leaking through list and bulk paths. These surfaces fail differently and should not share one generic “check access” call without resource-aware query behavior.
List queries must narrow data at the source. Every query should include tenant_id and, where relevant, scope and owner predicates. Fetching a tenant-wide or global result and deleting unauthorized rows in the API process exposes count, pagination, aggregation, cache, and memory risks. Even when device details remain hidden, totals, search suggestions, exports, and exception trends can reveal another site's size and operational state.
An object read should locate the resource within a tenant boundary, authorize it, and only then serialize fields. A repository contract that accepts tenant_id + device_id is safer than a global device_id lookup followed by late filtering. Error handling should also avoid disclosing whether an unknown ID exists in another tenant; otherwise, the difference between “not found” and “forbidden” becomes an enumeration channel.
A command write demands stronger checks because it creates a physical side effect. In addition to command:write, the service should verify current device ownership, scope, controllability, model compatibility, command template, idempotency key, risk class, and audit context. Authorization at creation time is not automatically valid at retry time. A delayed worker or protocol adapter must carry a non-forgeable tenant and owner context and revalidate relevant facts rather than trust a caller-supplied topic or device ID.
Bulk operations must not infer that a permitted task creator may act on every device produced by a broad query. The platform should freeze the target set, evaluate each resource and compatibility constraint, then persist separate allowed and denied sets. A fail-all policy may terminate the batch when any target is invalid. A partial-success policy may continue, but it must retain per-target decisions and consequences instead of one aggregate statement such as “93% successful.”
During an operations handoff, the important questions are not limited to the new engineer's role. The platform needs to know the access channel, start and expiry time, work order, sites and device groups, and who will verify revocation. When those facts remain only in chat or a ticketing comment, the command service cannot enforce the same decision at execution time.
4. Threat Model: five authorization paths that frequently escape review
| Attack or error path | Direct trigger | Root cause | Required control |
|---|---|---|---|
| Cross-tenant switch | Change X-Tenant-Id |
Treat a request header as an identity fact | Resolve identity binding first; allow only trusted platform roles to switch |
| Cross-site read | Keep device:read, replace site or device ID |
RBAC has no resource scope | Enforce scope in both query and object paths |
| Service-provider lateral access | Vendor A requests vendor B’s device | Tenant isolation substitutes for owner isolation | Require an owner claim and match resource ownership |
| Low privilege to high-risk action | Construct a command API request from a read-only view | UI hiding is treated as authorization | Independently verify command:write, target, and context |
| Bulk fan-out escape | Build targets from a query containing unauthorized devices | Only the batch creator is checked | Freeze targets, authorize each, and record allow/deny sets |
The shared root cause is not one missing conditional. Authorization has not been defined as an invariant of every resource request. When each module writes a different tenant_id == current_tenant check, new endpoints, background jobs, and cache paths eventually drift. Decision inputs and denial reasons should become stable contracts shared by API, service, worker, and message-consumer boundaries.
The current Grus targeted run covers tenant mismatch, denied permission, scope mismatch, and service-owner mismatch. It also includes cross-tenant command and cross-owner command cases. All 13 selected tests passed, which proves fail-closed behavior in those code paths. The suite did not exercise broker-side MQTT topic ACLs, so the result must not be presented as end-to-end data-plane isolation. Device credentials, topic templates, and broker policies require separate evidence.
5. Controls: assign stable responsibility to roles, scopes, and temporary grants
Roles express durable responsibilities. A tenant_admin maintains tenant configuration; an operator runs day-to-day operations; an installer completes installation work; a vendor supports assigned devices; and a rule_auditor inspects rules and audit evidence. The role catalog should remain explainable. If every customer needs many nearly identical roles, the platform is probably trying to encode scope, ownership, and temporary access as role variants.
Scopes express resource sets. Sites, space trees, projects, and device groups may become scope roots, but inheritance must be explicit. Does a parent-site grant include descendants? When a device moves, when does the old grant stop applying? If a group is dynamic, who owns the risk when a tag change expands membership? For high-risk actions, a dynamic query should not expand without review after approval; freeze its members or preserve a reproducible selector version.
Service owners express operational responsibility. The value should come from controlled device binding, integration provenance, or service-contract state, not a field supplied by an ordinary caller. Reassigning a device to another service provider should address outstanding commands, alarm subscriptions, OTA jobs, API credentials, and historical audit visibility. Changing one owner column while those dependent objects retain the old boundary creates a half-migrated security state.
Temporary grants express high-risk and short-lived work. An enforceable grant includes requester, approver, action set, resource snapshot, start and expiry, purpose, ticket, revocation state, and trace identity. Expiry should take effect in the decision layer rather than waiting for an administrator to remove a role the next morning. Break-glass access may shorten the approval path, but it still requires strong authentication, minimum scope, a short lifetime, real-time alerting, and post-event review.
Access channels are another control dimension. Web administration, Open API, device data planes, and internal workers carry different risks. A user allowed into the web console should not automatically receive API access, and an adapter service account should not enter the administrative UI. Treating channel access as part of effective authorization closes the “one grant opens every surface” failure mode.
6. Verification: test denials before celebrating the happy path
Each decision dimension needs an allowed and denied case, and the denial must happen before sensitive data or side effects leave the boundary. The following matrix is a stronger acceptance surface than “the administrator can open the device page.”
| Dimension | Allowed example | Required denial | Side effects to inspect |
|---|---|---|---|
| Tenant | Trusted platform role enters a target tenant | Tenant admin modifies the tenant header | No object details, audit leak, or cache contamination |
| Action | Operator reads devices | Tenant user edits role policy | No write and no job creation |
| Scope | Site A engineer reads Site A devices | Same subject reads Site B | No leak through lists, counts, exports, or search |
| Owner | Vendor A operates assigned devices | Vendor A operates Vendor B devices | No command, notification, or retry record |
| Context | Valid ticket permits one diagnostic command | Expired grant starts a bulk restart | No target snapshot, or an explicit terminal rejection |
Failure behavior for identity and authorization dependencies also matters. A production system must not fall back to token-supplied roles when effective-role lookup fails, nor replace an unresolved scope with * to preserve operational availability. For write and cross-tenant paths, denial is usually safer than authorization from stale state. If a business requires short-lived policy caching, define the maximum staleness, revocation propagation bound, cache integrity, and emergency invalidation path.
Audit verification must check more than the existence of a log entry. High-risk events should carry the subject, effective tenant, target resource, permission, scope and owner decision, policy version, request source, trace id, outcome, and denial reason. The audit query is itself a protected multi-tenant resource. Without tenant, scope, and owner enforcement, it may become the richest cross-customer information leak in the platform.
7. Remediation Plan: migrate a platform that currently has only RBAC
The first phase establishes resource facts before adding more roles. Add immutable tenant fields to devices, sites, groups, commands, alarms, OTA jobs, and audit records. Define where service ownership and resource scope originate and how they change. A shadow decision can record what the new policy would do without changing production results, exposing interfaces that lack required facts.
The second phase standardizes action vocabulary and decision input. Replace separate menu, API, and job permission concepts with stable resource actions, then route every resource entry through one authorization contract. Apply tenant, scope, and owner predicates in list repositories and repeat object-aware authorization at service write boundaries. Do not map every legacy role to * during migration; derive the minimum action set from actual responsibility.
The third phase blocks cross-tenant and cross-owner paths before gradually tightening scopes. Cross-tenant leakage has the largest blast radius and should fail closed first. Service-provider lateral access follows. Scope migration may interrupt legitimate site operations, so compare shadow results, repair missing grants, and review each difference rather than classifying every denial as a false positive.
The fourth phase adds contextual authorization to remote command, OTA, credential, and fleet jobs. Introduce expiry, work orders, frozen targets, idempotency, and break-glass handling. Workers should verify that a grant remains valid before execution. Continuous governance follows: every new resource type, list, export, aggregate, and message consumer requires an unauthorized test and an audit assertion.
A very small deployment with one customer and no external service provider may not need a complete owner and just-in-time access subsystem on day one. It should still preserve tenant, action, resource-scope, and audit seams. Retrofitting those facts after the second customer, site, or vendor arrives is usually more expensive than defining the full authorization input early.
8. Conclusion
A multi-tenant device permission model should not collapse into a role table. RBAC governs durable action capability. Tenant identity protects customer boundaries. Scope constrains sites and device sets. Service ownership protects operational responsibility. Context constrains time, ticket, and risk. A shared decision chain combines them into an explainable allow or deny outcome.
Completion is not “the administrator can use the page and ordinary users cannot see the button.” Cross-tenant, cross-scope, cross-owner, denied-action, and bulk-fan-out paths need reproducible rejection evidence, and the denial must not create commands, jobs, notifications, or cache side effects. Until those guarantees are shared across the frontend, API, workers, and data plane, security still depends on developer memory rather than a verifiable contract.
FAQ
Should ABAC replace RBAC?
Treating them as exclusive choices is usually unhelpful. RBAC handles durable responsibilities, while attributes and relationships constrain tenant, scope, owner, time, and work context. Most device platforms need a composition.
Should a platform administrator access every tenant?
A cross-tenant platform role can exist, but it must come from a trusted identity and policy source. Tenant switching, sensitive reads, and writes need stronger audit. A self-asserted token role must never provide this capability.
Can MQTT topic ACLs replace API authorization?
No. Broker ACLs protect the message data plane, while API authorization protects control-plane and business resources. Their tenant, device, and owner semantics should align, but their enforcement points and tests remain separate.