Skip to content

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

fix(cognito): enforce OAuth scopes for client credentials and REST APIs (#2238)

gakuto-cw21418ea9667a11
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b60612b9..768224d9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@ Versioning follows [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Fixed
+- **Cognito / API Gateway REST — OAuth scope refusals** — the client credentials token endpoint now rejects undefined custom scopes with HTTP 400 `invalid_scope`, and defined scopes the app client does not allow with HTTP 400 `invalid_grant`, instead of issuing a token after dropping them. Whitespace-only scope requests are rejected as malformed, and clients with no allowed scopes no longer inherit the user sign-in scope. A REST Cognito authorizer whose method scopes do not match the token now answers HTTP 401 `Unauthorized` through the `UNAUTHORIZED` gateway response instead of 403. Scope refusals and REST authorization follow official AWS documentation; empty-value and malformed-scope handling follow OAuth 2.0. These changes have not been measured against a real AWS account.
- **S3 — signed browser POST policies** — SigV4 and legacy SigV2 form uploads now verify their policy signature and registered credentials, expiration, exact and prefix conditions, field coverage and file-size bounds before writing. Under `AUTH=true` the form signer also needs the object write permissions. Registered IAM keys retain the bucket owner's account scope. Anonymous form behavior is unchanged.
- **CloudWatch Logs — ordered, bounded event reads** — keep stream histories chronological for API, Lambda, CodeBuild and DynamoDB import logs, including late batches and restored snapshots. `FilterLogEvents` seeks to time bounds and merges stream cursors until its limit is reached instead of collecting, filtering and sorting every event; newer events in an earlier-scanned stream cannot displace older matches. Equal timestamps retain stream-selection and arrival order, `GetLogEvents` reads late arrivals chronologically with tokens anchored to returned events, so pages neither repeat nor skip events on the unread side, and Live Tail still receives the exact newly ingested batch.
diff --git a/ministack/services/apigateway_v1.py b/ministack/services/apigateway_v1.py
index a94c8b5f..86f650f8 100644
--- a/ministack/services/apigateway_v1.py
+++ b/ministack/services/apigateway_v1.py
@@ -1519,10 +1519,6 @@ def _gateway_error_response(error, request):
if customized is None:
# A deployment restored from state written before snapshots existed.
customized = _gateway_responses.get(api_id, {})
- if isinstance(error, _PlainGatewayError) and not customized.keys() & {
- error.response_type, _gateway_response_family(error.response_type)
- }:
- return error.response
response_type = error.response_type
response = _gateway_response_for_type(customized, response_type)
template = (response.get("responseTemplates") or {}).get("application/json")
@@ -1844,16 +1840,6 @@ def _token_scopes(claims):
return sorted(set(scopes))
-class _PlainGatewayError(_GatewayError):
- """A gateway error whose built-in default was not measured against AWS: it
- keeps the response it had before gateway responses were applied, while a
- customized response for its type still takes over."""
-
- def __init__(self, response_type, message, response):
- super().__init__(response_type, message)
- self.response = response
-
-
async def _validate_cognito_authorizer(authorizer, method_obj, headers, query_params, stage):
"""Verify a user-pool token for a COGNITO_USER_POOLS method.
@@ -1918,8 +1904,7 @@ async def _validate_cognito_authorizer(authorizer, method_obj, headers, query_pa
if required_scopes:
granted = _token_scopes(claims)
if not any(scope in granted for scope in required_scopes):
- forbidden = (403, {"Content-Type": "application/json"}, json.dumps({"message": "Forbidden"}).encode())
- return None, _PlainGatewayError("ACCESS_DENIED", "Forbidden", forbidden)
+ return None, _gw_error("UNAUTHORIZED", "Unauthorized")
return claims, None
diff --git a/ministack/services/cognito.py b/ministack/services/cognito.py
index 97aa2f7b..4490bdb3 100644
--- a/ministack/services/cognito.py
+++ b/ministack/services/cognito.py
@@ -792,8 +792,9 @@ def _granted_scopes(client: dict | None, requested: str | None, grant: str = "au
"""The scopes a token-endpoint grant carries: the requested ones the client allows, or all it allows."""
listed = (client or {}).get("AllowedOAuthScopes") or []
if not listed and not requested:
- # Nothing to grant from: keep the API sign-in scope
- return None
+ # Only user sign-ins inherit the user-pool API scope. M2M grants
+ # cannot gain that scope when the client has no custom scopes.
+ return "" if grant == "client_credentials" else None
# client_credentials grants only resource-server scopes
allowed = sorted(s for s in listed if "/" in s or grant != "client_credentials")
wanted = requested.split() if requested else allowed
@@ -807,6 +808,30 @@ def _id_token_granted(scope: str | None) -> bool:
return scope is None or "openid" in scope.split()
+def _client_credentials_scope_error(pool: dict, client: dict, requested: str | None):
+ """Reject the whole M2M grant when a custom scope is undefined or not allowed.
+
+ AWS's token endpoint documents invalid_scope for an unknown resource server
+ or scope, and invalid_grant for a defined scope the app client does not allow.
+ """
+ allowed = client.get("AllowedOAuthScopes") or []
+ # RFC 6749 treats an empty value as omitted, but a nonempty value must
+ # contain a scope token. Whitespace alone must not pass a vacuous check.
+ if requested and not requested.split():
+ return _oauth2_error("invalid_scope", "The requested scope is malformed.")
+ wanted = requested.split() if requested else [s for s in allowed if "/" in s]
+ defined = {
+ f"{identifier}/{scope['ScopeName']}"
+ for identifier, server in (pool.get("_resource_servers") or {}).items()
+ for scope in server.get("Scopes", [])
+ }
+ if any(scope not in defined for scope in wanted):
+ return _oauth2_error("invalid_scope", "The requested scope does not exist.")
+ if any(scope not in allowed for scope in wanted):
+ return _oauth2_error("invalid_grant", "The requested scope is not allowed for this client.")
+ return None
+
+
def _fake_token(sub: str, pool_id: str, client_id: str, token_type: str = "access",
username: str = "", user_attrs: dict | None = None,
groups: list[str] | None = None,
@@ -7221,6 +7246,10 @@ def _oauth2_token(data, query_params, raw_body: bytes = b"", headers: dict | Non
if csec != client["ClientSecret"]:
return _oauth2_error("invalid_client", "Invalid client credentials.")
+ scope_error = _client_credentials_scope_error(pool, client, form.get("scope"))
+ if scope_error:
+ return scope_error
+
# M2M's own client-metadata channel — a JSON object, urlencoded, in
# the aws_client_metadata POST field (there's no ClientMetadata
# request field on this grant the way there is on
@@ -7237,10 +7266,6 @@ def _oauth2_token(data, query_params, raw_body: bytes = b"", headers: dict | Non
pass
scope = _granted_scopes(client, form.get("scope"), "client_credentials")
- if scope == "" and form.get("scope"):
- # Nothing requested was granted: a resource-server scope the client lacks, or a non-custom scope.
- error = "invalid_grant" if any("/" in s for s in form.get("scope", "").split()) else "invalid_scope"
- return 400, {"Content-Type": "application/json"}, json.dumps({"error": error}).encode()
access_token = _fake_token(cid, pool_id, cid, "access",
trigger_source="TokenGeneration_ClientCredentials",
client_metadata=client_metadata, scope=scope)
diff --git a/tests/test_apigatewayv1.py b/tests/test_apigatewayv1.py
index ab3e93fa..bc2770f3 100644
--- a/tests/test_apigatewayv1.py
+++ b/tests/test_apigatewayv1.py
@@ -4781,17 +4781,122 @@ def test_apigwv1_cognito_authorization_scopes(apigw_v1, lam, cognito_idp):
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
- assert _auth_http(url, headers={"Host": host, "Authorization": _v1_signed_token({**base, "scope": "other/scope"})})[1] == b'{"message": "Forbidden"}'
+ # AWS documents 401 when none of the method's OAuth scopes match.
+ assert _call(_v1_signed_token({**base, "scope": "other/scope"})) == 401
+ assert json.loads(_auth_http(url, headers={"Host": host, "Authorization": _v1_signed_token({**base, "scope": "other/scope"})})[1]) == {"message": "Unauthorized"}
# 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
+ assert _call(_v1_signed_token({**base, "token_use": "id", "aud": "c1"})) == 401
finally:
apigw_v1.delete_rest_api(restApiId=api_id)
lam.delete_function(FunctionName=fname)
cognito_idp.delete_user_pool(UserPoolId=pool_id)
[email protected]("basic", [False, True])
+def test_apigwv1_cognito_client_credentials_http(apigw_v1, cognito_idp, basic):
+ """Real token endpoint -> REST Cognito authorizer, including OAuth refusals."""
+ import base64
+ import urllib.error
+ import urllib.request
+ from urllib.parse import urlencode
+
+ suffix = _uuid_mod.uuid4().hex[:8]
+ pool = cognito_idp.create_user_pool(PoolName=f"m2m-rest-{suffix}")["UserPool"]
+ pool_id = pool["Id"]
+ api_id = apigw_v1.create_rest_api(name=f"m2m-rest-{suffix}")["id"]
+ try:
+ cognito_idp.create_user_pool_domain(UserPoolId=pool_id, Domain=f"m2m-rest-{suffix}")
+ cognito_idp.create_resource_server(
+ UserPoolId=pool_id, Identifier="api", Name="api",
+ Scopes=[{"ScopeName": s, "ScopeDescription": s} for s in ("read", "write", "admin")],
+ )
+ client = cognito_idp.create_user_pool_client(
+ UserPoolId=pool_id, ClientName="m2m", GenerateSecret=True,
+ AllowedOAuthFlowsUserPoolClient=True, AllowedOAuthFlows=["client_credentials"],
+ AllowedOAuthScopes=["api/read", "api/write"],
+ )["UserPoolClient"]
+ authorizer = apigw_v1.create_authorizer(
+ restApiId=api_id, name="pool", type="COGNITO_USER_POOLS", providerARNs=[pool["Arn"]],
+ identitySource="method.request.header.Authorization", authorizerResultTtlInSeconds=0,
+ )
+ root_id = _auth_root_id(apigw_v1, api_id)
+ args = dict(restApiId=api_id, resourceId=root_id, httpMethod="GET")
+ apigw_v1.put_method(**args, authorizationType="COGNITO_USER_POOLS", authorizerId=authorizer["id"],
+ authorizationScopes=["api/read", "api/admin"])
+ apigw_v1.put_integration(**args, type="MOCK", requestTemplates={"application/json": '{"statusCode":200}'})
+ apigw_v1.put_method_response(**args, statusCode="200")
+ apigw_v1.put_integration_response(**args, statusCode="200", responseTemplates={"application/json": '{"ok":true}'})
+ apigw_v1.create_deployment(restApiId=api_id, stageName="dev")
+ assert apigw_v1.get_method(**args)["authorizationScopes"] == ["api/read", "api/admin"]
+
+ def get_token(scope):
+ form = {"grant_type": "client_credentials"}
+ if scope is not None:
+ form["scope"] = scope
+ headers = {"Content-Type": "application/x-www-form-urlencoded"}
+ if basic:
+ credentials = base64.b64encode(f"{client['ClientId']}:{client['ClientSecret']}".encode()).decode()
+ headers["Authorization"] = f"Basic {credentials}"
+ else:
+ form.update(client_id=client["ClientId"], client_secret=client["ClientSecret"])
+ request = urllib.request.Request(f"{_endpoint}/oauth2/token", data=urlencode(form).encode(), headers=headers)
+ try:
+ response = urllib.request.urlopen(request, timeout=30)
+ except urllib.error.HTTPError as exc:
+ response = exc
+ with response:
+ return response.status, json.loads(response.read())
+
+ def call(token=None):
+ headers = {"Host": f"{api_id}.execute-api.localhost:{_EXECUTE_PORT}"}
+ if token is not None:
+ headers["Authorization"] = f"Bearer {token}"
+ request = urllib.request.Request(f"{_endpoint}/dev/", headers=headers)
+ try:
+ response = urllib.request.urlopen(request, timeout=30)
+ except urllib.error.HTTPError as exc:
+ response = exc
+ with response:
+ return response.status, json.loads(response.read()), {k.lower(): v for k, v in response.headers.items()}
+
+ for scope in ("api/read", "api/read api/write", None):
+ status, response = get_token(scope)
+ assert status == 200, response
+ jwt = response["access_token"]
+ payload = jwt.split(".")[1]
+ claims = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
+ assert claims["iss"] == f"https://cognito-idp.us-east-1.amazonaws.com/{pool_id}"
+ assert claims["token_use"] == "access"
+ assert claims["client_id"] == client["ClientId"]
+ assert set(claims["scope"].split()) == set((scope or "api/read api/write").split())
+ assert call(jwt)[:2] == (200, {"ok": True})
+ status, response = get_token("api/write")
+ assert status == 200, response
+ insufficient = response["access_token"]
+ for jwt in (insufficient, None):
+ status, body, headers = call(jwt)
+ assert (status, body) == (401, {"message": "Unauthorized"})
+ assert headers["x-amzn-errortype"] == "UnauthorizedException"
+ for scope, error in (("api/admin", "invalid_grant"), ("api/missing", "invalid_scope"),
+ ("api/read api/admin", "invalid_grant"), ("api/read api/missing", "invalid_scope")):
+ status, response = get_token(scope)
+ assert status == 400, response
+ assert response["error"] == error
+ assert "access_token" not in response
+
+ # A scope failure must use UNAUTHORIZED, including a deployed override.
+ for kind, code in (("UNAUTHORIZED", "418"), ("ACCESS_DENIED", "419")):
+ apigw_v1.put_gateway_response(
+ restApiId=api_id, responseType=kind, statusCode=code,
+ responseTemplates={"application/json": '{"type":"' + kind + '"}'},
+ )
+ apigw_v1.create_deployment(restApiId=api_id, stageName="dev")
+ assert call(insufficient)[:2] == (418, {"type": "UNAUTHORIZED"})
+ finally:
+ apigw_v1.delete_rest_api(restApiId=api_id)
+ cognito_idp.delete_user_pool(UserPoolId=pool_id)
+
+
# ---- Data plane: gateway responses ----
_GWRESP_AUTHORIZER = (
diff --git a/tests/test_cognito.py b/tests/test_cognito.py
index 9e362bff..8070f35e 100644
--- a/tests/test_cognito.py
+++ b/tests/test_cognito.py
@@ -4742,9 +4742,23 @@ def test_oauth2_token_issues_no_id_token_without_openid():
assert sorted(json.loads(body)) == ['access_token', 'expires_in', 'token_type']
+def _client_credentials_client(cognito_idp, allowed_scopes=None, identifier='api'):
+ pool_id = cognito_idp.create_user_pool(PoolName=f'm2m-{_uuid_mod.uuid4().hex[:8]}')['UserPool']['Id']
+ cognito_idp.create_resource_server(
+ UserPoolId=pool_id, Identifier=identifier, Name='api',
+ Scopes=[{'ScopeName': name, 'ScopeDescription': name} for name in ('read', 'write', 'admin')],
+ )
+ client = cognito_idp.create_user_pool_client(
+ UserPoolId=pool_id, ClientName='m2m', GenerateSecret=True,
+ AllowedOAuthFlowsUserPoolClient=True, AllowedOAuthFlows=['client_credentials'],
+ AllowedOAuthScopes=allowed_scopes if allowed_scopes is not None else [f'{identifier}/read'],
+ )['UserPoolClient']
+ return pool_id, client
+
+
def test_oauth2_token_client_credentials():
cognito_idp = make_client('cognito-idp')
- pool_id, client = _setup_pool_with_user(cognito_idp, generate_secret=True)
+ pool_id, client = _client_credentials_client(cognito_idp)
client_id = client['ClientId']
client_secret = client['ClientSecret']
@@ -4752,6 +4766,7 @@ def test_oauth2_token_client_credentials():
'grant_type': 'client_credentials',
'client_id': client_id,
'client_secret': client_secret,
+ 'scope': 'api/read',
})
assert status == 200
@@ -4765,7 +4780,7 @@ def test_oauth2_token_client_credentials():
def test_oauth2_token_client_credentials_expires_with_the_client():
cognito_idp = make_client('cognito-idp')
- pool_id, client = _setup_pool_with_user(cognito_idp, generate_secret=True)
+ pool_id, client = _client_credentials_client(cognito_idp)
cognito_idp.update_user_pool_client(
UserPoolId=pool_id, ClientId=client['ClientId'],
AccessTokenValidity=5, TokenValidityUnits={'AccessToken': 'minutes'},
@@ -4775,6 +4790,7 @@ def test_oauth2_token_client_credentials_expires_with_the_client():
'grant_type': 'client_credentials',
'client_id': client['ClientId'],
'client_secret': client['ClientSecret'],
+ 'scope': 'api/read',
})
assert status == 200
@@ -4785,10 +4801,10 @@ def test_oauth2_token_client_credentials_expires_with_the_client():
@pytest.mark.parametrize('requested,scope', [
(None, 'zeta/x api/write api/read'),
+ ('', 'zeta/x api/write api/read'),
('api/read', 'api/read'),
('api/read api/write zeta/x', 'zeta/x api/write api/read'),
('api/read api/read', 'api/read'),
- ('api/read bogus/x', 'api/read'),
])
def test_oauth2_token_client_credentials_carries_granted_scopes(requested, scope):
"""No scope parameter grants every scope the client allows."""
@@ -4831,12 +4847,117 @@ def test_oauth2_token_client_credentials_refuses_scopes_it_cannot_grant(requeste
'grant_type': 'client_credentials', 'client_id': client['ClientId'],
'client_secret': client['ClientSecret'], 'scope': requested,
})
- assert (status, json.loads(body)) == (400, {'error': error})
+ assert status == 400, body
+ response = json.loads(body)
+ assert response['error'] == error
+ assert 'access_token' not in response
+
+
[email protected]('basic', [False, True])
[email protected]('requested,error', [
+ ('api/admin', 'invalid_grant'),
+ ('api/missing', 'invalid_scope'),
+ ('missing/read', 'invalid_scope'),
+ ('api/read api/admin', 'invalid_grant'),
+ ('api/read api/missing', 'invalid_scope'),
+ ('openid', 'invalid_scope'),
+ (' ', 'invalid_scope'),
+])
+def test_oauth2_token_client_credentials_rejects_invalid_scopes(requested, error, basic):
+ """Official token endpoint docs: reject the entire invalid scope request."""
+ cognito_idp = make_client('cognito-idp')
+ pool_id, client = _client_credentials_client(cognito_idp)
+ try:
+ form = {'grant_type': 'client_credentials', 'scope': requested}
+ headers = {}
+ if basic:
+ credentials = base64.b64encode(f"{client['ClientId']}:{client['ClientSecret']}".encode()).decode()
+ headers['Authorization'] = f'Basic {credentials}'
+ else:
+ form.update(client_id=client['ClientId'], client_secret=client['ClientSecret'])
+ status, _, body = _post_form(f'{ENDPOINT}/oauth2/token', form, headers=headers)
+ response = json.loads(body)
+ assert status == 400, body
+ assert response['error'] == error
+ assert 'access_token' not in response
+ finally:
+ cognito_idp.delete_user_pool(UserPoolId=pool_id)
+
+
+def test_oauth2_token_client_credentials_rejects_scope_with_no_client_permissions():
+ cognito_idp = make_client('cognito-idp')
+ pool_id, client = _client_credentials_client(cognito_idp, allowed_scopes=[])
+ try:
+ status, _, body = _post_form(f'{ENDPOINT}/oauth2/token', {
+ 'grant_type': 'client_credentials', 'client_id': client['ClientId'],
+ 'client_secret': client['ClientSecret'], 'scope': 'api/read',
+ })
+ assert status == 400, body
+ assert json.loads(body)['error'] == 'invalid_grant'
+ finally:
+ cognito_idp.delete_user_pool(UserPoolId=pool_id)
+
+
[email protected]('requested', [None, ''])
+def test_oauth2_token_client_credentials_empty_permissions_never_grant_user_scope(requested):
+ """M2M cannot inherit a user sign-in scope from an empty configuration.
+
+ AWS does not document whether this configuration is rejected or gets a
+ scopeless token, so check the permission invariant without fixing a status.
+ """
+ cognito_idp = make_client('cognito-idp')
+ pool_id, client = _client_credentials_client(cognito_idp, allowed_scopes=[])
+ try:
+ form = {'grant_type': 'client_credentials', 'client_id': client['ClientId'],
+ 'client_secret': client['ClientSecret']}
+ if requested is not None:
+ form['scope'] = requested
+ status, _, body = _post_form(f'{ENDPOINT}/oauth2/token', form)
+ response = json.loads(body)
+ assert status in (200, 400), body
+ if status == 200:
+ assert _decode_jwt_claims(response['access_token']).get('scope', '') == ''
+ else:
+ assert 'error' in response
+ assert 'access_token' not in response
+ finally:
+ cognito_idp.delete_user_pool(UserPoolId=pool_id)
+
+
+def test_oauth2_token_client_credentials_scope_definition_is_pool_scoped():
+ cognito_idp = make_client('cognito-idp')
+ other_pool, _ = _client_credentials_client(cognito_idp, identifier='other')
+ pool_id, client = _client_credentials_client(cognito_idp)
+ try:
+ status, _, body = _post_form(f'{ENDPOINT}/oauth2/token', {
+ 'grant_type': 'client_credentials', 'client_id': client['ClientId'],
+ 'client_secret': client['ClientSecret'], 'scope': 'other/read',
+ })
+ assert status == 400, body
+ assert json.loads(body)['error'] == 'invalid_scope'
+ finally:
+ cognito_idp.delete_user_pool(UserPoolId=pool_id)
+ cognito_idp.delete_user_pool(UserPoolId=other_pool)
+
+
+def test_oauth2_token_client_credentials_accepts_url_resource_server_identifier():
+ cognito_idp = make_client('cognito-idp')
+ identifier = 'https://example.test/api/v1'
+ pool_id, client = _client_credentials_client(cognito_idp, identifier=identifier)
+ try:
+ status, _, body = _post_form(f'{ENDPOINT}/oauth2/token', {
+ 'grant_type': 'client_credentials', 'client_id': client['ClientId'],
+ 'client_secret': client['ClientSecret'], 'scope': f'{identifier}/read',
+ })
+ assert status == 200, body
+ assert _decode_jwt_claims(json.loads(body)['access_token'])['scope'] == f'{identifier}/read'
+ finally:
+ cognito_idp.delete_user_pool(UserPoolId=pool_id)
def test_oauth2_token_client_auth_basic():
cognito_idp = make_client('cognito-idp')
- pool_id, client = _setup_pool_with_user(cognito_idp, generate_secret=True)
+ pool_id, client = _client_credentials_client(cognito_idp)
client_id = client['ClientId']
client_secret = client['ClientSecret']
@@ -4846,6 +4967,7 @@ def test_oauth2_token_client_auth_basic():
f'{ENDPOINT}/oauth2/token',
{
'grant_type': 'client_credentials',
+ 'scope': 'api/read',
},
headers={'Authorization': f'Basic {basic}'},
)