Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

feat(iot): evaluate IAM policies on MQTT over WebSocket under AUTH=true (#2277)

iot-rocketd076638bc7b7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fdc14164..5972b49f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@ Versioning follows [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Added
+- **IoT — MQTT over WebSocket evaluates the signer's IAM policies under `AUTH=true`** — a session signed with an IAM user or STS session key could connect under any client id and publish, subscribe and receive on any topic; with `AUTH=true` its CONNECT, will, PUBLISH, SUBSCRIBE and deliveries now need the key's IAM policies to allow `iot:Connect`, `iot:Publish` (and `iot:RetainPublish`), `iot:Subscribe` and `iot:Receive` on the client, topic and topic filter ARNs, with the same refusals as a certificate session. Contributed by @iot-rocket.
+- **Auth — WebSocket handshakes are verified for IAM user and STS session keys** — under `AUTH=true` an MQTT-over-WebSocket upgrade or an `AWS_IAM` WebSocket `$connect` signed with such a key was accepted with a wrong secret, a date more than 5 minutes off or a wrong session token; the signature in the query string or `Authorization` header is now checked like that of other requests, IoT answers 403 `Forbidden` and expects the session token after the signed part of the URL, and API Gateway names the canonical string it expected. Contributed by @iot-rocket.
- **Auth — WebSocket handshakes are verified for IAM user and STS session keys** — under `AUTH=true` an MQTT-over-WebSocket upgrade or an `AWS_IAM` WebSocket `$connect` signed with such a key was accepted with a wrong secret, a date more than 5 minutes off or a wrong session token; the signature in the query string or `Authorization` header is now checked like that of other requests, IoT answers 403 `Forbidden` and expects the session token after the signed part of the URL, and API Gateway names the canonical string it expected. Contributed by @iot-rocket.
- **RDS Data, S3 Control — calls are authorized under `AUTH=true`** — RDS Data calls and S3 Control tagging calls were served whatever the caller's policies allowed; each RDS Data call is now authorized as `rds-data:<operation>` on the cluster its `resourceArn` names, and `ListTagsForResource`, `TagResource` and `UntagResource` as `s3:<operation>` on the bucket, with a 403 denial (`AccessDeniedException` from RDS Data, `AccessDenied` from S3 Control) naming the action and resource, as on AWS. Contributed by @iot-rocket.
- **SES v2 — calls are authorized under `AUTH=true`** — SES v2 calls were served whatever the caller's policies allowed; each is now authorized as `ses:<operation>` on the configuration set, contact list, custom verification email template, dedicated IP pool, identity or template its path or create body names (`*` otherwise), and a denial answers 403 `AccessDeniedException` naming the action and resource, as on AWS. Contributed by @iot-rocket.
diff --git a/ministack/app.py b/ministack/app.py
index 573e4097..5ad2539a 100644
--- a/ministack/app.py
+++ b/ministack/app.py
@@ -91,8 +91,8 @@ def _ws_resolve_iot_account_id(scope: dict, ws_headers: dict) -> str:
3. Fall back to ``MINISTACK_ACCOUNT_ID`` / ``000000000000``.
SigV4 signature *verification* is intentionally lax (any
- well-formed credential is accepted) unless AUTH=true; IoT policy enforcement is not yet
- feature. The point here is multi-tenancy isolation, not auth.
+ well-formed credential is accepted) unless AUTH=true, which also evaluates the key's IAM
+ policies per MQTT action. The point here is multi-tenancy isolation, not auth.
"""
qs = scope.get("query_string", b"").decode("utf-8", errors="replace")
qp = parse_qs(qs, keep_blank_values=True) if qs else {}
diff --git a/ministack/services/iot.py b/ministack/services/iot.py
index 3b1cc065..25335e5e 100644
--- a/ministack/services/iot.py
+++ b/ministack/services/iot.py
@@ -95,7 +95,7 @@ from urllib.parse import parse_qs, parse_qsl
from ministack.core.arn import ArnParseError, parse_arn
from ministack.core.concurrency import run_reentrant
-from ministack.core.iam_evaluator import EvalContext, evaluate, parse_policy_document
+from ministack.core.iam_evaluator import AuthError, EvalContext, ResolvedCredential, evaluate, parse_policy_document
from ministack.core.responses import (
AccountRegionScopedDict,
_request_account_id,
@@ -9053,6 +9053,17 @@ def _mqtt_policy_allows(
return evaluate(ctx, [_parsed_iot_policy(doc, variables) for doc in documents]).decision == "Allow"
+def _mqtt_iam_allows(
+ account_id: str, region: str, credential: tuple[str, str], action: str, resource: str
+) -> bool:
+ """Whether the IAM policies of the key that signed a WebSocket session allow ``action`` on ``resource``."""
+ from ministack.core.iam_evaluator import enforce
+
+ access_key_id, key_account = credential
+ with request_scope(key_account, region):
+ return enforce(access_key_id, action, "iot", region, f"arn:aws:iot:{region}:{account_id}:{resource}") is None
+
+
# ---------------------------------------------------------------------------
# Broker public API (consumed by iot_data.py and handle_websocket)
# ---------------------------------------------------------------------------
@@ -10805,6 +10816,9 @@ class _WSSession:
self.certificate_id: str | None = None
# The template of a provisioning claim certificate, which has a policy of its own.
self.provisioning_template: str | None = None
+ # The access key and account of an IAM principal that signed a WebSocket
+ # session; its IAM policies are evaluated under AUTH=true.
+ self.iam_credential: tuple[str, str] | None = None
self._policy_context: dict = {}
def disconnect_reason(self) -> str:
@@ -10813,7 +10827,7 @@ class _WSSession:
Only the reasons the broker can actually tell apart are ever reported: a
DISCONNECT packet (``CLIENT_INITIATED_DISCONNECT``), a takeover by a
second connection using the same client id (``DUPLICATE_CLIENTID``),
- a packet the certificate's policies refuse (``CLIENT_ERROR`` on 3.1.1,
+ a packet the session's policies refuse (``CLIENT_ERROR`` on 3.1.1,
``AUTH_ERROR`` on MQTT 5), and everything else — a transport that went
away (``CONNECTION_LOST``).
AWS's remaining reasons name machinery this broker does not have
@@ -11016,13 +11030,15 @@ class _WSSession:
)
def _evaluates_policies(self) -> bool:
- """Whether this session is held to its certificate's IoT policies (AUTH=true only)."""
+ """Whether this session is held to its certificate's IoT policies or its signer's IAM policies (AUTH=true)."""
from ministack import app
- return app.AUTH and self.certificate_id is not None
+ return app.AUTH and (self.certificate_id is not None or self.iam_credential is not None)
def _policy_allows(self, action: str, resource: str) -> bool:
"""Whether this session may do ``action`` on ``resource``."""
+ if self._evaluates_policies() and self.iam_credential is not None:
+ return _mqtt_iam_allows(self.account_id, self.region, self.iam_credential, action, resource)
return not self._evaluates_policies() or _mqtt_policy_allows(
self.account_id,
self.region,
@@ -11220,7 +11236,7 @@ class _WSSession:
self._will_retain = False
self._will_properties = b""
- if self._evaluates_policies():
+ if self._evaluates_policies() and self.certificate_id is not None:
self._policy_context = _mqtt_policy_context(
self.account_id, self.region, self.certificate_id, client_id
)
@@ -11603,12 +11619,12 @@ async def _feed_session(session: _WSSession, data: bytes, max_buffer: int) -> bo
return False
-def _ws_handshake_refused(scope: dict) -> bool:
- """Under AUTH=true, whether the upgrade's SigV4 signature, time or session token fails."""
+def _ws_handshake_check(scope: dict) -> AuthError | ResolvedCredential | None:
+ """Under AUTH=true, the upgrade's verified IAM credential or the ``AuthError`` refusing it; else None."""
from ministack.app import AUTH
- from ministack.core.iam_evaluator import AuthError, authenticate_handshake
+ from ministack.core.iam_evaluator import authenticate_handshake
- return bool(AUTH) and isinstance(authenticate_handshake(scope), AuthError)
+ return authenticate_handshake(scope) if AUTH else None
async def _refuse_ws_handshake(scope: dict, send) -> None:
@@ -11639,7 +11655,8 @@ async def handle_websocket(
sub_headers[name.decode("latin-1").lower()] = value.decode("utf-8")
except UnicodeDecodeError:
sub_headers[name.decode("latin-1").lower()] = value.decode("latin-1")
- if _ws_handshake_refused(scope):
+ checked = _ws_handshake_check(scope)
+ if isinstance(checked, AuthError):
await _refuse_ws_handshake(scope, send)
return
requested = sub_headers.get("sec-websocket-protocol", "")
@@ -11660,6 +11677,8 @@ async def handle_websocket(
query = parse_qs(scope.get("query_string", b"").decode("latin-1"))
principal = _caller_principal(extract_access_key_id(sub_headers, query))
session = _WSSession(send, account_id, region, principal)
+ if checked is not None:
+ session.iam_credential = (checked.access_key_id, checked.account_id)
max_buffer = _max_frame_buffer_bytes()
try:
diff --git a/tests/test_iot_data.py b/tests/test_iot_data.py
index 130587b1..8afcc3ac 100644
--- a/tests/test_iot_data.py
+++ b/tests/test_iot_data.py
@@ -1060,6 +1060,96 @@ def test_iot_ws_handshake_signature_contract(auth_enabled, iam_user, case):
assert status == 101
+async def _mqtt_over_signed_ws(query: str, packets: list[bytes]) -> list[str]:
+ """The packets the broker answers over an MQTT WebSocket signed in ``query``, named; a PINGREQ goes last."""
+ names: list[str] = []
+ async with websockets.connect(f"ws://{_iot_ws_host()}/mqtt?{query}", subprotocols=["mqtt"]) as ws:
+ try:
+ for packet in (*packets, b"\xc0\x00"):
+ await ws.send(packet)
+ while "PINGRESP" not in names:
+ buf = await asyncio.wait_for(ws.recv(), timeout=_WS_HANDSHAKE_TIMEOUT)
+ while parsed := _parse_packet(bytes(buf)):
+ kind, _flags, body, used = parsed
+ buf = buf[used:]
+ names.append({
+ 2: lambda: f"CONNACK {body[1]:#04x}",
+ 3: lambda: f"PUBLISH {_dec_str(body, 0)[0]}",
+ 4: lambda: f"PUBACK {body[2] if len(body) > 2 else 0:#04x}",
+ 9: lambda: f"SUBACK {body[-1]:#04x}",
+ 13: lambda: "PINGRESP",
+ 14: lambda: f"DISCONNECT {body[0] if body else 0:#04x}",
+ }[kind]())
+ except websockets.ConnectionClosed:
+ pass
+ return names
+
+
+_MQTT_WS_CASES = { # case: (packets as (kind, name, v5), names under AUTH=true, names with AUTH off)
+ "connect-allowed": ([("connect", "dev-1", False)], ["CONNACK 0x00", "PINGRESP"], None),
+ "connect-other-client": ([("connect", "other", False)], [], ["CONNACK 0x00", "PINGRESP"]),
+ "connect-denied-client": ([("connect", "dev-denied", False)], [], ["CONNACK 0x00", "PINGRESP"]),
+ "connect-other-client-v5": ([("connect", "other", True)], ["CONNACK 0x87"], ["CONNACK 0x00", "PINGRESP"]),
+ "receive-allowed": ([("connect", "dev-1", False), ("subscribe", "t/a", False), ("publish", "t/a", False)],
+ ["CONNACK 0x00", "SUBACK 0x01", "PUBACK 0x00", "PUBLISH t/a", "PINGRESP"], None),
+ "receive-not-allowed": (
+ [("connect", "dev-1", False), ("subscribe", "t/nr", False), ("publish", "t/nr", False)],
+ ["CONNACK 0x00", "SUBACK 0x01", "PUBACK 0x00", "PINGRESP"],
+ ["CONNACK 0x00", "SUBACK 0x01", "PUBACK 0x00", "PUBLISH t/nr", "PINGRESP"]),
+ "publish-other-topic": ([("connect", "dev-1", False), ("publish", "other/x", False)], ["CONNACK 0x00"],
+ ["CONNACK 0x00", "PUBACK 0x00", "PINGRESP"]),
+ "publish-denied-topic": ([("connect", "dev-1", False), ("publish", "t/denied", False)], ["CONNACK 0x00"],
+ ["CONNACK 0x00", "PUBACK 0x00", "PINGRESP"]),
+ "subscribe-other-filter": ([("connect", "dev-1", False), ("subscribe", "other/x", False)], ["CONNACK 0x00"],
+ ["CONNACK 0x00", "SUBACK 0x01", "PINGRESP"]),
+ "publish-other-topic-v5": ([("connect", "dev-1", True), ("publish", "other/x", True)],
+ ["CONNACK 0x00", "PUBACK 0x87", "PINGRESP"],
+ ["CONNACK 0x00", "PUBACK 0x00", "PINGRESP"]),
+ "retain-without-retain-publish-v5": ([("connect", "dev-1", True), ("retain", "t/a", True)],
+ ["CONNACK 0x00", "PUBACK 0x87", "PINGRESP"],
+ ["CONNACK 0x00", "PUBACK 0x00", "PINGRESP"]),
+ "subscribe-other-filter-v5": ([("connect", "dev-1", True), ("subscribe", "other/x", True)],
+ ["CONNACK 0x00", "SUBACK 0x87", "PINGRESP"],
+ ["CONNACK 0x00", "SUBACK 0x01", "PINGRESP"]),
+}
+
+
[email protected]("signer", ["user", "session", "root"])
[email protected]("case", list(_MQTT_WS_CASES))
+def test_iot_ws_session_iam_policy_contract(auth_enabled, iam_user, case, signer):
+ """Under AUTH=true an IAM-signed MQTT-over-WebSocket session is held to the signer's IAM policies."""
+ run = _unique("p")
+ statements = [
+ {"Effect": "Allow", "Action": "iot:Connect", "Resource": f"arn:aws:iot:*:*:client/{run}-dev-*"},
+ {"Effect": "Deny", "Action": "iot:Connect", "Resource": f"arn:aws:iot:*:*:client/{run}-dev-denied"},
+ {"Effect": "Allow", "Action": "iot:Publish", "Resource": f"arn:aws:iot:*:*:topic/{run}/t/*"},
+ {"Effect": "Deny", "Action": "iot:Publish", "Resource": f"arn:aws:iot:*:*:topic/{run}/t/denied"},
+ {"Effect": "Allow", "Action": "iot:Subscribe", "Resource": f"arn:aws:iot:*:*:topicfilter/{run}/t/*"},
+ {"Effect": "Allow", "Action": "iot:Receive", "Resource": f"arn:aws:iot:*:*:topic/{run}/t/a"},
+ {"Effect": "Allow", "Action": "sts:GetSessionToken", "Resource": "*"},
+ ]
+ packets, strict, permissive = _MQTT_WS_CASES[case]
+ frames = []
+ for kind, name, v5 in packets:
+ level = MQTT_5 if v5 else MQTT_311
+ if kind == "connect":
+ frames.append(_make_connect(f"{run}-{name}", protocol_level=level))
+ elif kind == "subscribe":
+ frames.append(_make_subscribe(1, f"{run}/{name}", qos=1, protocol_level=level))
+ else:
+ frames.append(_make_publish(f"{run}/{name}", b"{}", qos=1, packet_id=2, protocol_level=level,
+ retain=kind == "retain"))
+ with _second_access_key(iam_user(policy={"Version": "2012-10-17", "Statement": statements})) as (key, secret):
+ if signer == "root":
+ key, secret = "test", "test"
+ query, _ = _signed_mqtt_upgrade(key, secret, session=signer == "session",
+ token="session" if signer == "session" else None)
+ names = asyncio.run(_mqtt_over_signed_ws(query, frames))
+ expected = strict if auth_enabled and signer != "root" else (permissive or strict)
+ assert sorted(names) == sorted(n.replace(" t/", f" {run}/t/") for n in expected)
+
+
# ---------------------------------------------------------------------------
# Device Shadow (GetThingShadow / UpdateThingShadow / DeleteThingShadow)
# ---------------------------------------------------------------------------