Skip to content

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

fix(apigateway): enforce COGNITO_USER_POOLS authorizers on REST methods (#1669)

ppettitaua0dd9197e990
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d2684d4b..fa2d58ba 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,10 @@ All notable changes to MiniStack will be documented here.
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
Versioning follows [Semantic Versioning](https://semver.org/).
-
## [Unreleased]
+### Changed
+- **API Gateway — a REST method's `COGNITO_USER_POOLS` authorizer is enforced** — the v1 data plane matched only `NONE`, `AWS_IAM` and `CUSTOM` and passed everything else through, so a method fronted by a user-pool authorizer served every caller: an anonymous request reached the backend, and `requestContext.authorizer.claims` was never populated, leaving a handler that branches on `claims` to take its no-claims path locally while the same code denied the request on AWS. The token named by the authorizer's `identitySource` (defaulting to the Authorization header, with or without a `Bearer` prefix) is now verified against the pools in `providerARNs` — RS256 signature against the pool's JWKS, `iss` naming one of those pools, and `exp`/`nbf`/`iat` — and its claims reach the backend as `requestContext.authorizer.claims`, stringified as API Gateway passes them, a list claim such as `cognito:groups` space-joined in brackets (`[admins staff]`). ID and access tokens are both accepted and the app client is never checked, matching AWS: a REST authorizer is configured with pool ARNs only, which is why it has no audience to validate. A method carrying `authorizationScopes` additionally requires one of those scopes in the token's `scope`/`scp` and answers `403` otherwise; everything else that fails is `401`. `PutMethod` also stops discarding `authorizationScopes`, so `GetMethod` reports it and a CloudFormation `AWS::ApiGateway::Method` declaring it provisions it.
+
### Added
- **CloudFormation — the `Rules` section is evaluated** — a template's rules were ignored; they now run after the parameters resolve and before any resource is touched, on `CreateStack`, `UpdateStack` and `CreateChangeSet`: a rule whose `RuleCondition` is false is skipped, a false `Assert` refuses the operation with its `AssertDescription` as a `ValidationError`, and the CDK's `CheckBootstrapVersion` rule therefore refuses an outdated bootstrap version instead of passing silently. `Fn::And`, `Fn::Or`, `Fn::Not`, `Fn::Equals`, `Fn::If`, `Fn::Contains`, `Fn::EachMemberEquals`, `Fn::EachMemberIn` and `Ref` are evaluated; `Fn::RefAll`, `Fn::ValueOf` and `Fn::ValueOfAll` are served from the EC2 store for the VPC, subnet and security-group id types, and a rule over any other type is skipped with a warning. A function outside the rule set is refused as a template format error. Contributed by @iot-rocket.
diff --git a/ministack/services/apigateway_v1.py b/ministack/services/apigateway_v1.py
index c6092b25..e26115e3 100644
--- a/ministack/services/apigateway_v1.py
+++ b/ministack/services/apigateway_v1.py
@@ -111,7 +111,14 @@ from ministack.core.responses import (
get_region,
new_uuid,
)
-from ministack.services.apigateway import _timeout_from_env, _urlopen_async
+from ministack.services.apigateway import (
+ _b64url_decode,
+ _fetch_jwks,
+ _resolve_jwks_url,
+ _timeout_from_env,
+ _urlopen_async,
+ _verify_rs256_signature,
+)
def _now_unix():
@@ -1562,6 +1569,155 @@ def _iam_caller_identity(headers, query_params):
return identity
+def _cognito_pool_issuers(authorizer):
+ """The token issuers a COGNITO_USER_POOLS authorizer accepts.
+
+ Each ``providerARNs`` entry is a user-pool ARN
+ (``arn:aws:cognito-idp:{region}:{account}:userpool/{poolId}``) and the
+ issuer Cognito stamps into a token minted by that pool is
+ ``https://cognito-idp.{region}.amazonaws.com/{poolId}``. Unparsable and
+ non-``cognito-idp`` entries are skipped rather than raising: CreateAuthorizer
+ stores the list verbatim, so a malformed ARN only surfaces here and must not
+ take down the request handler.
+ """
+ issuers = []
+ for arn in authorizer.get("providerARNs") or []:
+ try:
+ parsed = parse_arn(arn)
+ except ArnParseError:
+ continue
+ if parsed.service != "cognito-idp" or not parsed.region:
+ continue
+ pool_id = parsed.resource.split("/", 1)[-1] if "/" in parsed.resource else ""
+ if pool_id:
+ issuers.append(f"https://cognito-idp.{parsed.region}.amazonaws.com/{pool_id}")
+ return issuers
+
+
+def _cognito_token_from_request(authorizer, headers, query_params, stage):
+ """The raw JWT named by a Cognito authorizer's ``identitySource``.
+
+ REST identity sources use the ``method.request.header.X`` syntax (not the
+ HTTP API's ``$request.header.X``), and AWS defaults the field to the
+ Authorization header. A ``Bearer `` prefix is tolerated — Cognito authorizers
+ accept the bare token, but clients routinely send the OAuth-style form.
+ """
+ source = authorizer.get("identitySource") or "method.request.header.Authorization"
+ present, values = _request_identity_sources(source, headers, query_params, stage)
+ if not present or not values:
+ return None
+ token = (values[0] or "").strip()
+ if token.lower().startswith("bearer "):
+ token = token.split(" ", 1)[1].strip()
+ return token or None
+
+
+def _stringify_claims(claims):
+ """Render JWT claims as the backend receives them.
+
+ API Gateway passes claims through as strings. A list-valued claim —
+ ``cognito:groups`` being the one that matters — arrives space-joined inside
+ square brackets (``"[admins staff]"``), which is why a handler cannot simply
+ index it as an array.
+ """
+ out = {}
+ for key, value in (claims or {}).items():
+ if value is None:
+ continue
+ if isinstance(value, bool):
+ out[key] = "true" if value else "false"
+ elif isinstance(value, list):
+ out[key] = "[" + " ".join(str(v) for v in value) + "]"
+ elif isinstance(value, dict):
+ out[key] = json.dumps(value, separators=(",", ":"))
+ else:
+ out[key] = str(value)
+ return out
+
+
+def _token_scopes(claims):
+ """The OAuth scopes carried by an access token (``scope`` or ``scp``)."""
+ scopes = []
+ raw_scope = claims.get("scope")
+ raw_scp = claims.get("scp")
+ if isinstance(raw_scope, str):
+ scopes.extend([s for s in raw_scope.split(" ") if s])
+ if isinstance(raw_scp, list):
+ scopes.extend([str(s) for s in raw_scp])
+ elif isinstance(raw_scp, str):
+ scopes.extend([s for s in raw_scp.split(" ") if s])
+ return sorted(set(scopes))
+
+
+async def _validate_cognito_authorizer(authorizer, method_obj, headers, query_params, stage):
+ """Verify a user-pool token for a COGNITO_USER_POOLS method.
+
+ Returns ``(claims, error_response)``. Unlike the HTTP API's JWT authorizer
+ there is no audience to check: a REST Cognito authorizer is configured with
+ pool ARNs only, so AWS validates the signature, the standard time claims and
+ that ``iss`` names one of those pools — never the app client. Both ID and
+ access tokens are accepted, as on AWS.
+ """
+ issuers = _cognito_pool_issuers(authorizer)
+ if not issuers:
+ # An authorizer with no usable pool cannot authorize anything; AWS
+ # reports this as a configuration error rather than letting it through.
+ return None, _gw_error(500, "Internal server error")
+
+ token = _cognito_token_from_request(authorizer, headers, query_params, stage)
+ if not token:
+ return None, _gw_error(401, "Unauthorized")
+
+ parts = token.split(".")
+ if len(parts) != 3:
+ return None, _gw_error(401, "Unauthorized")
+ try:
+ header = json.loads(_b64url_decode(parts[0]))
+ claims = json.loads(_b64url_decode(parts[1]))
+ except (ValueError, json.JSONDecodeError):
+ return None, _gw_error(401, "Unauthorized")
+ if not isinstance(claims, dict) or not isinstance(header, dict):
+ return None, _gw_error(401, "Unauthorized")
+
+ issuer = claims.get("iss")
+ if issuer not in issuers:
+ return None, _gw_error(401, "Unauthorized")
+
+ kid = header.get("kid")
+ jwks_url = await _resolve_jwks_url({"jwtConfiguration": {"issuer": issuer}})
+ if not kid or not jwks_url:
+ return None, _gw_error(401, "Unauthorized")
+ try:
+ keys = ((await _fetch_jwks(jwks_url)).get("keys") or [])
+ except (OSError, ValueError, json.JSONDecodeError):
+ return None, _gw_error(401, "Unauthorized")
+ jwk = next((k for k in keys if k.get("kid") == kid), None)
+ if not jwk or not _verify_rs256_signature(token, jwk):
+ return None, _gw_error(401, "Unauthorized")
+
+ now = int(time.time())
+ try:
+ if "exp" in claims and int(claims["exp"]) <= now:
+ return None, _gw_error(401, "Unauthorized")
+ if "nbf" in claims and int(claims["nbf"]) > now:
+ return None, _gw_error(401, "Unauthorized")
+ if "iat" in claims and int(claims["iat"]) > now:
+ return None, _gw_error(401, "Unauthorized")
+ except (TypeError, ValueError):
+ return None, _gw_error(401, "Unauthorized")
+
+ # authorizationScopes on the method turns the check into an OAuth one: the
+ # token must carry at least one of the listed scopes, and a token without
+ # scopes at all (an ID token) can never satisfy it.
+ required_scopes = method_obj.get("authorizationScopes") or []
+ if required_scopes:
+ granted = _token_scopes(claims)
+ if not any(scope in granted for scope in required_scopes):
+ return None, _gw_error(403, "Forbidden")
+
+ return claims, None
+
+
async def _authorize_request_v1(
api_id, stage_name, method_obj, method, request_path, resource,
headers, body, query_params, path_params, stage,
@@ -1582,8 +1738,19 @@ async def _authorize_request_v1(
if not _header_ci(headers, "authorization"):
return _gw_error(403, "Missing Authentication Token"), None
return None, None
+ if auth_type == "COGNITO_USER_POOLS":
+ authorizer_id = method_obj.get("authorizerId")
+ authorizer = _authorizers_v1.get(api_id, {}).get(authorizer_id) if authorizer_id else None
+ if not authorizer:
+ return _gw_error(500, "Internal server error"), None
+ claims, auth_error = await _validate_cognito_authorizer(
+ authorizer, method_obj, headers, query_params, stage
+ )
+ if auth_error:
+ return auth_error, None
+ return None, {"claims": _stringify_claims(claims)}
if auth_type != "CUSTOM":
- # COGNITO_USER_POOLS and any future type: not enforced here (pass through).
+ # Any future authorization type: not enforced here (pass through).
return None, None
authorizer_id = method_obj.get("authorizerId")
@@ -2709,6 +2876,7 @@ def _put_method(api_id, resource_id, http_method, data):
"httpMethod": http_method,
"authorizationType": data.get("authorizationType", "NONE"),
"authorizerId": data.get("authorizerId"),
+ "authorizationScopes": data.get("authorizationScopes", []),
"apiKeyRequired": data.get("apiKeyRequired", False),
"operationName": data.get("operationName", ""),
"requestParameters": data.get("requestParameters", {}),
diff --git a/ministack/services/cloudformation/provisioners.py b/ministack/services/cloudformation/provisioners.py
index 65638d92..84bbd12b 100644
--- a/ministack/services/cloudformation/provisioners.py
+++ b/ministack/services/cloudformation/provisioners.py
@@ -3527,6 +3527,7 @@ def _apigw_method_create(logical_id, props, stack_name):
data = {
"authorizationType": props.get("AuthorizationType", "NONE"),
"authorizerId": props.get("AuthorizerId"),
+ "authorizationScopes": props.get("AuthorizationScopes", []),
"apiKeyRequired": props.get("ApiKeyRequired", False),
"operationName": props.get("OperationName", ""),
"requestParameters": props.get("RequestParameters", {}),
diff --git a/tests/test_apigatewayv1.py b/tests/test_apigatewayv1.py
index 9a1bebaf..f12b76eb 100644
--- a/tests/test_apigatewayv1.py
+++ b/tests/test_apigatewayv1.py
@@ -4281,3 +4281,219 @@ def test_apigwv1_aws_iam_method_fills_caller_identity(apigw_v1, lam, cognito_idp
finally:
apigw_v1.delete_rest_api(restApiId=api_id)
lam.delete_function(FunctionName=fname)
+
+
+def _v1_signed_token(claims: dict) -> str:
+ """Mint an RS256 token signed with the local Cognito pool key."""
+ import base64 as _b64
+
+ from ministack.services import cognito as _cognito
+
+ if _cognito._RSA_PRIVATE_KEY is None:
+ pytest.skip("cryptography-backed Cognito signing key unavailable")
+
+ from cryptography.hazmat.primitives import hashes
+ from cryptography.hazmat.primitives.asymmetric import padding
+
+ header = {"alg": "RS256", "kid": "ministack-key-1"}
+ h = _b64.urlsafe_b64encode(json.dumps(header).encode()).rstrip(b"=").decode()
+ p = _b64.urlsafe_b64encode(json.dumps(claims).encode()).rstrip(b"=").decode()
+ sig = _cognito._RSA_PRIVATE_KEY.sign(f"{h}.{p}".encode(), padding.PKCS1v15(), hashes.SHA256())
+ s = _b64.urlsafe_b64encode(sig).rstrip(b"=").decode()
+ return f"{h}.{p}.{s}"
+
+
+def test_apigwv1_cognito_user_pools_authorizer_enforced(apigw_v1, lam, cognito_idp):
+ """A COGNITO_USER_POOLS method verifies the pool token and injects claims.
+
+ The REST path previously served these methods unconditionally, so an
+ anonymous request reached the backend and requestContext.authorizer.claims
+ was never populated.
+ """
+ import urllib.error as _urlerr
+ import urllib.request as _urlreq
+ import uuid as _uuid
+
+ suffix = _uuid.uuid4().hex[:8]
+ fname = f"intg-v1-cognito-{suffix}"
+ code = (
+ b"import json\n"
+ b"def handler(event, context):\n"
+ b" auth = event.get('requestContext', {}).get('authorizer')\n"
+ b" return {'statusCode': 200, 'body': json.dumps(auth)}\n"
+ )
+ buf = io.BytesIO()
+ with zipfile.ZipFile(buf, "w") as zf:
+ zf.writestr("index.py", code)
+ lam.create_function(
+ FunctionName=fname, Runtime="python3.12",
+ Role="arn:aws:iam::000000000000:role/test-role",
+ Handler="index.handler", Code={"ZipFile": buf.getvalue()},
+ )
+
+ pool_id = cognito_idp.create_user_pool(PoolName=f"apigwv1-{suffix}")["UserPool"]["Id"]
+ pool_region = pool_id.split("_")[0]
+ issuer = f"https://cognito-idp.{pool_region}.amazonaws.com/{pool_id}"
+ pool_arn = f"arn:aws:cognito-idp:{pool_region}:000000000000:userpool/{pool_id}"
+
+ api_id = apigw_v1.create_rest_api(name=f"v1-cognito-{suffix}")["id"]
+ try:
+ root = next(r for r in apigw_v1.get_resources(restApiId=api_id)["items"] if r["path"] == "/")
+ resource_id = apigw_v1.create_resource(
+ restApiId=api_id, parentId=root["id"], pathPart="private",
+ )["id"]
+ authorizer_id = apigw_v1.create_authorizer(
+ restApiId=api_id, name="pool-auth", type="COGNITO_USER_POOLS",
+ providerARNs=[pool_arn],
+ identitySource="method.request.header.Authorization",
+ )["id"]
+ apigw_v1.put_method(
+ restApiId=api_id, resourceId=resource_id, httpMethod="GET",
+ authorizationType="COGNITO_USER_POOLS", authorizerId=authorizer_id,
+ )
+ apigw_v1.put_integration(
+ restApiId=api_id, resourceId=resource_id, httpMethod="GET",
+ type="AWS_PROXY", integrationHttpMethod="POST",
+ uri=(
+ f"arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/"
+ f"arn:aws:lambda:us-east-1:000000000000:function:{fname}/invocations"
+ ),
+ )
+ dep_id = apigw_v1.create_deployment(restApiId=api_id)["id"]
+ apigw_v1.create_stage(restApiId=api_id, stageName="dev", deploymentId=dep_id)
+
+ host = f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}"
+ url = f"http://{host}/dev/private"
+
+ def _call(token):
+ req = _urlreq.Request(url, method="GET")
+ req.add_header("Host", host)
+ if token is not None:
+ req.add_header("Authorization", token)
+ try:
+ r = _urlreq.urlopen(req)
+ return r.status, r.read()
+ except _urlerr.HTTPError as e:
+ return e.code, e.read()
+
+ now = int(time.time())
+
+ def _claims(**overrides):
+ base = {
+ "sub": "user-123", "iss": issuer, "aud": "client-1",
+ "token_use": "id", "iat": now, "exp": now + 3600,
+ "cognito:username": "alice", "cognito:groups": ["admins", "staff"],
+ }
+ base.update(overrides)
+ return base
+
+ # No token at all: the gap this closes — previously a 200.
+ assert _call(None)[0] == 401
+ # Structurally invalid token.
+ assert _call("not-a-jwt")[0] == 401
+ # Correctly signed but expired.
+ assert _call(_v1_signed_token(_claims(exp=now - 60)))[0] == 401
+ # Signed by this pool's key but claiming another pool as issuer.
+ other = f"https://cognito-idp.{pool_region}.amazonaws.com/{pool_region}_ffffffff"
+ assert _call(_v1_signed_token(_claims(iss=other)))[0] == 401
+ # Tampered payload fails the signature check.
+ good = _v1_signed_token(_claims())
+ h, _p, s = good.split(".")
+ forged = json.dumps(_claims(sub="attacker")).encode()
+ import base64 as _b64
+ tampered = f"{h}.{_b64.urlsafe_b64encode(forged).rstrip(b'=').decode()}.{s}"
+ assert _call(tampered)[0] == 401
+
+ # Valid token: 200, with claims stringified as the backend sees them.
+ status, body = _call(good)
+ assert status == 200
+ auth = json.loads(body)
+ assert auth["claims"]["sub"] == "user-123"
+ assert auth["claims"]["cognito:username"] == "alice"
+ # A list claim arrives space-joined in brackets, as on AWS.
+ assert auth["claims"]["cognito:groups"] == "[admins staff]"
+
+ # The Bearer prefix is tolerated.
+ assert _call(f"Bearer {good}")[0] == 200
+ finally:
+ apigw_v1.delete_rest_api(restApiId=api_id)
+ lam.delete_function(FunctionName=fname)
+ cognito_idp.delete_user_pool(UserPoolId=pool_id)
+
+
+def test_apigwv1_cognito_authorization_scopes(apigw_v1, lam, cognito_idp):
+ """authorizationScopes on the method turns the check into an OAuth one."""
+ import urllib.error as _urlerr
+ import urllib.request as _urlreq
+ import uuid as _uuid
+
+ suffix = _uuid.uuid4().hex[:8]
+ fname = f"intg-v1-scope-{suffix}"
+ code = b"def handler(event, context):\n return {'statusCode': 200, 'body': 'ok'}\n"
+ buf = io.BytesIO()
+ with zipfile.ZipFile(buf, "w") as zf:
+ zf.writestr("index.py", code)
+ lam.create_function(
+ FunctionName=fname, Runtime="python3.12",
+ Role="arn:aws:iam::000000000000:role/test-role",
+ Handler="index.handler", Code={"ZipFile": buf.getvalue()},
+ )
+
+ pool_id = cognito_idp.create_user_pool(PoolName=f"apigwv1-scope-{suffix}")["UserPool"]["Id"]
+ pool_region = pool_id.split("_")[0]
+ issuer = f"https://cognito-idp.{pool_region}.amazonaws.com/{pool_id}"
+ pool_arn = f"arn:aws:cognito-idp:{pool_region}:000000000000:userpool/{pool_id}"
+
+ api_id = apigw_v1.create_rest_api(name=f"v1-scope-{suffix}")["id"]
+ try:
+ root = next(r for r in apigw_v1.get_resources(restApiId=api_id)["items"] if r["path"] == "/")
+ resource_id = apigw_v1.create_resource(
+ restApiId=api_id, parentId=root["id"], pathPart="files",
+ )["id"]
+ authorizer_id = apigw_v1.create_authorizer(
+ restApiId=api_id, name="pool-auth", type="COGNITO_USER_POOLS",
+ providerARNs=[pool_arn],
+ )["id"]
+ method = apigw_v1.put_method(
+ restApiId=api_id, resourceId=resource_id, httpMethod="GET",
+ authorizationType="COGNITO_USER_POOLS", authorizerId=authorizer_id,
+ authorizationScopes=["files/read"],
+ )
+ # PutMethod used to discard the field, so GetMethod never reported it.
+ assert method["authorizationScopes"] == ["files/read"]
+
+ apigw_v1.put_integration(
+ restApiId=api_id, resourceId=resource_id, httpMethod="GET",
+ type="AWS_PROXY", integrationHttpMethod="POST",
+ uri=(
+ f"arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/"
+ f"arn:aws:lambda:us-east-1:000000000000:function:{fname}/invocations"
+ ),
+ )
+ dep_id = apigw_v1.create_deployment(restApiId=api_id)["id"]
+ apigw_v1.create_stage(restApiId=api_id, stageName="dev", deploymentId=dep_id)
+
+ host = f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}"
+ url = f"http://{host}/dev/files"
+ now = int(time.time())
+
+ def _call(token):
+ req = _urlreq.Request(url, method="GET")
+ req.add_header("Host", host)
+ req.add_header("Authorization", token)
+ try:
+ return _urlreq.urlopen(req).status
+ except _urlerr.HTTPError as e:
+ return e.code
+
+ base = {"sub": "u1", "iss": issuer, "iat": now, "exp": now + 3600}
+
+ assert _call(_v1_signed_token({**base, "scope": "files/read files/write"})) == 200
+ # A token whose scopes do not overlap is authenticated but not authorized.
+ assert _call(_v1_signed_token({**base, "scope": "other/scope"})) == 403
+ # An ID token carries no scopes at all, so it can never satisfy one.
+ assert _call(_v1_signed_token({**base, "token_use": "id", "aud": "c1"})) == 403
+ finally:
+ apigw_v1.delete_rest_api(restApiId=api_id)
+ lam.delete_function(FunctionName=fname)
+ cognito_idp.delete_user_pool(UserPoolId=pool_id)