RainMaker Neo Controller
1. Overview
A RainMaker Neo Controller is an ordinary RainMaker Neo node that can observe and control the other nodes in the single group it belongs to — much like the phone app, but running on a device with no human user and no user credentials.
Within its one group a controller can:
Read the group’s nodes and their config over the existing user REST APIs.
Read params of any node in the group over MQTT (named-shadow get and observe).
Set params at node, subgroup or group level over MQTT, and listen to group events.
It is a node by registration: own certificate, own shadow, joins a group like any other node. Its
group-wide reach rests on two things — a dedicated IoT policy (rmng-controller-policy) scoped to
its group through the group_id Thing attribute, and the SigV4 credentials the IoT credential
provider issues for its certificate, which is what the REST path identifies it by.
There is no user refresh token on the device. The certificate is the only root of trust, and the controller learns which group it belongs to from the MQTT group info every node receives rather than from provisioning.
Goals
Reuse the existing user REST APIs and RBAC for reads. Only one additive endpoint is needed (§3.4), because the existing list endpoint is keyed on the caller’s memberships.
No user credential on the device. Revocation is deactivating the certificate.
Per-controller, per-group isolation enforced server-side from authoritative state.
Non-goals
Cross-group control. A controller belongs to exactly one group, like any node.
Group-level write or admin — create, delete, share, edit membership. Read and control only.
2. Background
2.1 Two planes
Capability |
Plane |
Mechanism |
|---|---|---|
Read nodes and config (#1) |
REST |
RBAC over group membership; identity from the certificate behind its credentials |
Read params (#2) |
MQTT |
named-shadow get/observe on |
Set params and events (#3) |
MQTT |
unicast and group/subgroup control publishes |
The asymmetry that shapes the design: REST identity in RMNG comes from the OIDC/Cognito principal
(rmneo/principal → FromAPIRequest), not from the IAM or certificate principal. A
certificate-only device is therefore invisible to the data APIs as they stand — hence §3.3, which
teaches the checkpoint to recognise the certificate principal.
3. Design
3.1 Registration
Registered like any node, with the controller capability:
Single node:
POST /v1/admin/nodeswith"capabilities": ["controller"].Bulk: the same value on the registration job, applied to every node in the CSV — so controllers are registered in their own batch.
Assisted claiming:
capabilitieson the claim-verify request, carried through to the same registration path. Re-claim after a factory erase must restate it, since the capability policies are attached to the replacement certificate (seeassisted-claiming.md§3.6).
The controller’s node-register hook (src/controller/hooks) attaches rmng-controller-policy for
the capability, through the same nodelifecycle.CapabilityPolicy helper bridge uses. If the
controller stack is not deployed the policy does not exist, and registration answers 400
(capability unavailable) rather than failing opaquely. Core also records the registered capabilities on the node_details row as
reg_capabilities.
Note what core does not do: it never writes node_type. That field belongs to the node-register
lifecycle hook, which a separately-deployed optional stack owns, and core stores it without
interpreting it. Admitting the controller by its capability policy keeps that boundary intact — see
§7.1.
3.2 rmng-controller-policy
Attached alongside rmng-base-node-policy. Every MQTT resource is scoped to the controller’s group
through ${iot:Connection.Thing.Attributes[group_id]}, an attribute trusted backend code sets on
group join and leave and which the device has no way to assert for itself. Statements:
Read params — Subscribe/Receive/Publish on
*/$aws/things/*/shadow/name/params-${…group_id…}*/*.Set params, node level — Publish on
topic/rainmaker/nodes/*/user/params-${…group_id…}*/*.Set params, group and subgroup — Publish/Subscribe/Receive on
*/rainmaker/nodes/groups/${…group_id…}/controland.../subgroups/*/control.Credential provider —
iot:AssumeRoleWithCertificateon the controller role alias.
This is the same full-group MQTT permission set assume_role already grants a user, expressed as a
static device policy. Source: src/controller/controller_policy.json.
Statement 1’s Publish covers every shadow topic under those names, not only …/get, so a controller
can also write a group node’s reported state (…/update) or delete its shadow (…/delete). An app
user’s assume_role credentials carry the same grant, so narrowing it is a change to both, not to the
controller alone.
Policy variables resolve at connection time, so a controller that has just been added to a group must reconnect before the new scope takes effect, and one that has been removed keeps its old scope on the open connection until it reconnects.
3.3 Identity: the certificate behind the credentials
The controller obtains SigV4 credentials from the AWS IoT Credential Provider (certificate → controller role alias). Only a certificate carrying
rmng-controller-policymay use that alias, and the register hook attaches it only for thecontrollercapability.It signs every data call with them. The credential provider names the role session after the certificate ID (the SHA-256 of the certificate), so API Gateway hands the Lambda
assumed-role/<role>/<certificate id>as the caller’sUserArn.The checkpoint (§3.4) resolves that certificate ID to the thing the certificate is attached to (
iot:ListPrincipalThings), which is the node id. A certificate never moves to another thing, so the lookup is cached for the container’s life.The controller learns its group over MQTT, from the
from_cloudgroup info every node receives, which it needs anyway for the topics of §3.6.
There is no token and nothing to mint: the certificate is resolved on every request.
3.4 RBAC: one checkpoint
The data APIs are unchanged. rmneo/principal.FromAPIRequest, the single place every handler
builds its RBAC context, is where the caller’s kind is decided: a request SigV4-signed by a
non-Cognito IAM principal yields a DeviceActor principal identified by the node its certificate is
attached to (§3.3); anything else is resolved as a user from the Cognito identity the gateway
attached. A non-Cognito signer whose session is not named after an attached certificate is refused
(401), never resolved as a user. Package user knows only about users.
The device’s group is not fixed before the request. The checkpoint reads the node’s current row in
the group-node mapping and grants group:get and group:listsubentities on that group and nothing
else. A node in no group gets no context (401). A node moved between groups therefore follows the
move on its very next request, with the same credentials. The MQTT plane follows on the next
connection, when the policy re-reads the group_id Thing attribute (§3.2). It costs one query per
request, the same one the group listing used to make.
Below the checkpoint, group.ListGroupForUser resolves “which groups can the caller see” for either
principal — a user from their user-group-assoc rows, a device from its node’s membership — and is
what every group-scoped handler calls. The code behind GET /v1/groups would serve a controller
too, returning its one group, but the edge never lets one reach it: the role’s execute-api grant
is GET /v1/groups/*, which in an execute-api ARN requires a segment after groups/, so API
Gateway refuses the bare list route (§3.5). GET /v1/groups/{groupId} is therefore the one
additive endpoint and the controller’s only way to read its group: the group-keyed form a caller
who already knows its group id, from its MQTT group info, uses. A caller with no access and a
group that does not exist both answer 404, so the response never reveals whether a group exists.
3.5 What makes the REST surface read-only
Worth being precise, because it is not the RBAC grant. Once any call lists a group’s nodes, the
group-membership flow grants node-level access per node — today that grant is node:*, the same as
for a shared secondary user. What confines the controller to reads is the edge: its role’s
execute-api permission allows only GET on /v1/groups/*, so a write method is refused by API
Gateway before a Lambda ever runs. Only the controller role holds that grant, and only a
certificate carrying rmng-controller-policy can assume it.
Within GET /v1/groups/*, the controller reads its group (/v1/groups/{groupId}) and, for each node
of the group, config, schedules, triggers, timeseries/* and tags. It cannot read the group’s
automations or its users: the controller grant has no group:getautomation or
group:listprimaryusers. The bare GET /v1/groups is refused at the edge (§3.4).
3.6 MQTT topics (group g, node n, subgroup sg)
Operation |
Direction |
Topic |
|---|---|---|
Get params |
Pub |
|
Set params (node) |
Publish |
|
Set params (group) |
Publish |
|
Set params (subgroup) |
Publish |
|
Group events |
Subscribe |
|
3.7 Refresh
The certificate is the root of trust; nothing long-lived is stored. The only short-lived layer is the
SigV4 credentials from the credential provider — re-fetch them from the credentials endpoint on
expiry. If group_id changes, the controller learns it from MQTT group info and re-subscribes to the
group topics; REST access already follows the new group on the next request (§3.4).
3.8 Bootstrap inputs
The device already has the MQTT endpoint and the credential-provider endpoint, provisioned as for
any node. The only new value is the REST API base URL, which is not derivable from the IoT
endpoint. It is written into NVS as rmaker_creds/api_base_url by the dashboard’s Generate flow
when the operator opts in, or set via firmware menuconfig. group_id is not a bootstrap input —
it comes from the MQTT group info every node receives.
4. Resources
The controller is its own optional stack group, controller, deployed by cdk/apps/controller.py
and skipped by make deploy-rmng. Core references none of its stacks.
In rmng-controller-base: the controller IAM role (trusting credentials.iot.amazonaws.com) and
role alias rmng-controller-role-v1, with execute-api:Invoke on GET /v1/groups/*; and the
rmng-controller-policy IoT policy. The controller has no compute of its own.
In core, and generic: every data Lambda may call iot:ListPrincipalThings on certificates, the
lookup §3.3 needs. Registration needs no IAM change: the register hook runs in-process inside the
registration and claim Lambdas, whose shared node-register policy already grants
iot:AttachPolicy on *.
5. Firmware
examples/esp-idf/rmng_controller in rmng-sdk, plus the reusable components/rmng-aws-sign
component (credential provider, SigV4 signer, signed-request helper) shared with file storage and
KVS. The controller uses it with service="execute-api".
6. Security analysis
6.1 Per-controller, per-group isolation
Each controller has its own certificate and its own group_id Thing attribute, and the single
policy self-scopes per connection. Group ids are globally unique, so params-<group_id> namespaces
never collide across tenants.
6.2 Membership is not forgeable
group_id is set only by trusted backend code on join and leave. The device has no MQTT operation
to change its own Thing attribute, and the certificate policy grants no IoT control-plane API.
6.3 Identity is certificate-bound
The node id comes from the certificate the credential provider named the session after, resolved by
AWS IoT, so a device cannot assert another node’s id. App users’ Identity Pool credentials carry a
Cognito identity and are always resolved as users (§3.4). The one way around it is an IAM principal
that can assume a role with execute-api rights and pick its own session name; that takes
account-admin IAM rights.
6.4 Capability, not classification
Who may act as a controller is decided by the certificate’s policy: only a certificate carrying
rmng-controller-policy, attached for the controller capability, can assume the controller role.
Nothing consults node_type, which an optional stack owns and core does not interpret.
6.5 No user credentials on the device
The device holds only its X.509 key, already required for MQTT. Revoking the certificate stops the credential provider issuing SigV4 credentials; those already issued expire within their lifetime.
6.6 Cross-subgroup access
Like a full-group user, a controller reaches every subgroup of its group. Subgroup-internal isolation is a firmware concern, consistent with the rest of the device plane.
7. Extending this
7.1 A second controller kind
A different kind of controller — a Matter controller, say — layers on this baseline rather than replacing it. Three seams matter:
Classification. Because core never writes
node_type, an optional stack’s node-register hook attaches its own policy and may classify the node however it likes. Hooks accumulate and all of them run, so two capability modules do not contend;node_typecarries one value, so the first non-empty classification wins. This controller registers a hook (src/controller/hooks) and deliberately classifies nothing, since its capability policy is what admits it.The capability gate. A second kind adds its own capability, policy and role alias rather than a second
node_typeliteral.The checkpoint. Core resolves any credential-provider session to its node and grants identically whatever the node’s kind, so adding a kind is additive and cannot widen access: scope is a property of live membership.
The IoT policies are orthogonal and additive, so a node holding two controller capabilities is not a policy conflict.
7.2 Controller-initiated membership changes
The controller is read and control only (§1). Nothing in the identity model prevents more:
membership editing is an additive permission (group:editnodes) on the controller principal plus
the corresponding route. The certificate-bound identity and per-group isolation already hold.
7.3 When the membership lookup should become lazy
The checkpoint resolves a device’s group eagerly, on every request, before the handler knows
whether it needs it (§3.4). Today that costs nothing extra: the controller’s execute-api policy
admits only the group routes, every one of which calls group.ListGroupForUser, and that call
performed the same single-item read in the earlier design. The read moved earlier; the count per
request is unchanged. It is one GSI lookup on the group-node mapping by node id, small next to the
Lambda invocation around it, and doing it at the door is what yields a clean 401 for a device that
belongs to no group. The certificate-to-thing lookup (§3.3) runs once per certificate per Lambda
container, so IoT sees it only on cold starts.
The trade-off changes if a device is ever granted a route that does not involve groups, since the
eager read would then be wasted there. The fix at that point is lazy, memoised resolution: the
DeviceActor holds a resolver rather than a stored group id, ScopedGroupID runs the read on first
use and caches it for the rest of the request. The cost is a less tidy accessor that must surface or
swallow an error, and a node in no group is refused with 403 at first group access instead of
401 at the door. Two alternatives were considered and rejected: carrying the group in a cached
claim reintroduces the staleness §3.4 removed, and a warm-container cache keyed by node id does the
same across requests for the sake of a read that is already cheap.
7.4 Unifying credential vending
RMNG vends caller credentials through three paths that differ on two axes — the authenticating principal, and what is vended:
Path |
Principal |
Transport |
Vends |
|---|---|---|---|
|
user (JWT → SigV4) |
API Gateway |
scoped AWS credentials |
device-file / KVS credentials |
device X.509 |
IoT Credential Provider (mTLS) |
AWS credentials |
controller data calls |
device certificate (→ credential provider → SigV4) |
API Gateway |
nothing; the certificate is resolved per request |
The checkpoint (§3.4) recognises the certificate principal directly: the credential provider names the role session after the certificate ID, which identifies the device without any vended token.
8. Verification
test/itest/test_controller.py covers:
registration attaching the policy, and a plain node not getting it;
REST, signed with credential-provider credentials: reads of the group and of a group node’s config, a write refused at the edge, and another group refused;
MQTT: a node’s shadow read, unicast, group and subgroup control, receiving group broadcasts, and every policy statement refusing another group;
removal from the group: REST refused on the next request, MQTT kept on the open connection and refused after reconnecting, with no wider shadow access once
group_idis cleared;a node that is both a bridge and a controller.
test/itest/test_assisted_claiming.py covers a re-claim adding and removing the controller policy.
The controller tests skip themselves when rmng-controller-base reports no ControllerRoleAliases
output.