Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.
Python awsaws-emulatoraws-localaws-sdkdevtoolsdockerdynamodbec2emulatorlambdalocalstacklocalstack-alternativeministackmock-awsopen-sourcepythons3sqsterraform
feat(iot): evaluate IAM policies on MQTT over WebSocket under AUTH=true (#2277)
iot-rocketd076638bc7b7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.pyindex 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.pyindex 3b1cc065..25335e5e 100644--- a/ministack/services/iot.py+++ b/ministack/services/iot.py@@ -95,7 +95,7 @@ from urllib.parse import parse_qs, parse_qslfrom ministack.core.arn import ArnParseError, parse_arnfrom 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_documentfrom 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 = Noneself._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: aDISCONNECT packet (``CLIENT_INITIATED_DISCONNECT``), a takeover by asecond 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 wentaway (``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 = Falseself._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) -> boreturn 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 Noneasync 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)returnrequested = 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.pyindex 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]_contract[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)# ---------------------------------------------------------------------------