Merge pull request #10 from co-cddo/add-cross-account-access

gillespied · web-flow · commit 3cba0b75d3bb · 2026-05-05T15:24:31.000+01:00
Add cross-account access support to WebApp
diff --git a/docs/api/webapp.md b/docs/api/webapp.md
@@ -225,3 +225,30 @@ In the development environment, the task role can be assumed by developers with
 
 
 This feature is **disabled** in production environments.
+
+### Cross-Account Access
+
+When `cross_account_access=True` is set, the construct enables the ECS task to assume
+a cross-account role for accessing production data resources from non-production
+environments.
+
+```python
+WebApp(
+    app,
+    deployment_config=deployment_config,
+    app_config=app_config,
+    cross_account_access=True,
+)
+```
+
+**What it does (non-production only):**
+
+- Grants `sts:AssumeRole` permission to the task role for the cross-account role
+- Injects `CROSS_ACCOUNT_ROLE_ARN` environment variable into the container
+
+**In production:** No action is taken regardless of the flag value — the task role
+should have direct access to resources via IAM policies.
+
+**App-side usage:** Applications should read `CROSS_ACCOUNT_ROLE_ARN` from the
+environment and assume the role when creating boto3 sessions. When the variable is
+not set (production), a default session with direct credentials is used instead.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -272,6 +272,50 @@ app_config = AppConfig(
 )
 ```
 
+### Cross-Account Data Access
+
+If your application needs to access data in the production account when deployed to
+the development environment (e.g., querying Athena or reading S3), enable
+cross-account access:
+
+```python
+WebApp(
+    app,
+    deployment_config=deployment_config,
+    app_config=app_config,
+    cross_account_access=True,  # Enable cross-account role assumption in dev
+    # ... other parameters
+)
+```
+
+When enabled and deploying to a non-production environment, the construct automatically:
+
+1. Grants the task role `sts:AssumeRole` permission on the cross-account role
+2. Injects `CROSS_ACCOUNT_ROLE_ARN` as a container environment variable
+
+Your application code can then use this environment variable to create a boto3 session
+that assumes the cross-account role:
+
+```python
+import os
+import boto3
+
+def get_session():
+    role_arn = os.getenv("CROSS_ACCOUNT_ROLE_ARN")
+    if role_arn:
+        sts = boto3.client("sts")
+        creds = sts.assume_role(RoleArn=role_arn, RoleSessionName="app")["Credentials"]
+        return boto3.Session(
+            aws_access_key_id=creds["AccessKeyId"],
+            aws_secret_access_key=creds["SecretAccessKey"],
+            aws_session_token=creds["SessionToken"],
+        )
+    return boto3.Session()
+```
+
+In production, `CROSS_ACCOUNT_ROLE_ARN` is not set, so the default session (using the
+task role's direct permissions) is used. No code changes needed between environments.
+
 ## Next Steps
 
 - [API Reference](api/webapp.md) - Detailed API documentation
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "gds-idea-cdk-constructs"
-version = "0.4.0"
+version = "0.4.1"
 description = "A repo for commonly used constructs in the team."
 readme = "README.md"
 authors = [
diff --git a/src/gds_idea_cdk_constructs/config.py b/src/gds_idea_cdk_constructs/config.py
@@ -159,6 +159,17 @@ def _apply_config(self, config: dict[str, str]) -> None:
         # Derived from domain_name
         self.redirect_unauthorised_url = f"{self.domain_name}/401.html"
 
+        # Cross-account role for non-prod environments to access production data.
+        # Hardcoded for now — swap to config["cross_account_role_arn"] when
+        # the value is available from Parameter Store. See #11.
+        if self.environment == DeploymentEnvironment.PRODUCTION:
+            self.cross_account_role_arn: str | None = None
+        else:
+            self.cross_account_role_arn = (
+                f"arn:aws:iam::{DeploymentEnvironment.PRODUCTION.value}"
+                ":role/assume_role_for_development_account"
+            )
+
     def _fetch_from_parameter_store(self) -> dict[str, str]:
         """Fetch configuration from AWS Systems Manager Parameter Store.
 
diff --git a/src/gds_idea_cdk_constructs/web_app/stack.py b/src/gds_idea_cdk_constructs/web_app/stack.py
@@ -45,6 +45,7 @@ def __init__(
         container_props: WebAppContainerProperties | None = None,
         task_role: iam.Role | None = None,
         disable_waf: bool = False,
+        cross_account_access: bool = False,
     ) -> None:
         """Initialize a WebApp stack with containerized application infrastructure.
 
@@ -76,6 +77,11 @@ def __init__(
                 for short-term debugging when WAF rules are blocking legitimate traffic.
                 Never use in production. Disabling WAF removes critical security
                 protections against common web exploits.**
+            cross_account_access: Enable cross-account access to production resources.
+                Defaults to False. When True and deploying to a non-production
+                environment, grants the task role sts:AssumeRole permission on
+                the cross-account role and injects CROSS_ACCOUNT_ROLE_ARN as a
+                container environment variable.
 
         Example:
             Basic usage with Cognito authentication::
@@ -140,6 +146,11 @@ def __init__(
         if self.deployment_config.environment == DeploymentEnvironment.DEVELOPMENT:
             self._add_assume_policy_for_dev()
 
+        # Cross-account access to production resources from non-prod environments
+        self._cross_account_env: dict[str, str] = {}
+        if cross_account_access:
+            self._setup_cross_account_access()
+
         logger.info(
             f"Creating web app: {self.app_name} with authentication: {authentication}"
         )
@@ -186,6 +197,26 @@ def _add_assume_policy_for_dev(self):
             "can assume TaskRole for local development"
         )
 
+    def _setup_cross_account_access(self) -> None:
+        """Grant the task role permission to assume the cross-account role
+        and inject the role ARN as a container environment variable."""
+        role_arn = self.deployment_config.cross_account_role_arn
+        if role_arn is None:
+            logger.info(
+                "Cross-account access enabled but no role configured "
+                "for this environment — skipping"
+            )
+            return
+
+        self.task_role.add_to_policy(
+            iam.PolicyStatement(
+                actions=["sts:AssumeRole"],
+                resources=[role_arn],
+            )
+        )
+        self._cross_account_env = {"CROSS_ACCOUNT_ROLE_ARN": role_arn}
+        logger.info(f"Cross-account access enabled: {role_arn}")
+
     def _import_existing_resources(self) -> None:
         """Import existing VPC and other shared resources."""
         self.vpc = ec2.Vpc.from_lookup(
@@ -296,6 +327,7 @@ def _setup_ecs_resources(
             logging=ecs.LogDrivers.aws_logs(stream_prefix=f"{self.app_name}-app"),
             environment={
                 **self._auth_strategy.get_environment_variables(),
+                **self._cross_account_env,
                 **environment,
             },
         )
diff --git a/tests/test_config.py b/tests/test_config.py
@@ -94,6 +94,20 @@ def test_deployment_config_from_dict_derived_fields(test_cdk_env):
     assert config.redirect_unauthorised_url == f"{config.domain_name}/401.html"
 
 
+def test_deployment_config_cross_account_role_arn_dev(dev_cdk_env):
+    """Test that cross_account_role_arn is set for non-prod environments."""
+    config = DeploymentConfig.from_dict(dev_cdk_env, TEST_CONFIG)
+    assert config.cross_account_role_arn is not None
+    assert "588077357019" in config.cross_account_role_arn
+    assert "assume_role_for_development_account" in config.cross_account_role_arn
+
+
+def test_deployment_config_cross_account_role_arn_prod(prod_cdk_env):
+    """Test that cross_account_role_arn is None in production."""
+    config = DeploymentConfig.from_dict(prod_cdk_env, TEST_CONFIG)
+    assert config.cross_account_role_arn is None
+
+
 def test_deployment_config_from_dict_missing_key_raises_error(test_cdk_env):
     """Test that from_dict raises ValueError when required keys are missing."""
     incomplete = {"domain_name": "test.example.com"}
diff --git a/tests/web_app/test_stack.py b/tests/web_app/test_stack.py
@@ -95,6 +95,25 @@ def dev_deployment_config():
     return DeploymentConfig.from_dict(dev_env, TEST_CONFIG)
 
 
+@pytest.fixture
+def prod_cdk_app():
+    """Fixture for CDK App using PROD environment."""
+    account_id = "588077357019"
+    region = "eu-west-2"
+    vpc_id = TEST_CONFIG["vpc_id"]
+    domain_name = TEST_CONFIG["domain_name"]
+
+    app = App(context=_build_cdk_context(account_id, region, vpc_id, domain_name))
+    return app
+
+
+@pytest.fixture
+def prod_deployment_config():
+    """Fixture for PROD DeploymentConfig using from_dict."""
+    prod_env = CdkEnvironment(account="588077357019", region="eu-west-2")
+    return DeploymentConfig.from_dict(prod_env, TEST_CONFIG)
+
+
 @pytest.fixture
 def webapp_no_auth(cdk_app, deployment_config, app_config):
     """Fixture for WebApp with NoAuth."""
@@ -581,3 +600,124 @@ def test_web_app_stack_invalid_authentication_raises_error(
             docker_context_path="tests/fixtures",
             dockerfile_path="Dockerfile",
         )
+
+
+# Cross-account access tests
+
+
+def test_web_app_stack_cross_account_access_in_dev(
+    dev_cdk_app, dev_deployment_config, app_config
+):
+    """Test that cross_account_access=True adds IAM policy and env var in dev."""
+    stack = WebApp(
+        dev_cdk_app,
+        dev_deployment_config,
+        app_config,
+        authentication=AuthType.NONE,
+        docker_context_path="tests/fixtures",
+        dockerfile_path="Dockerfile",
+        cross_account_access=True,
+    )
+    template = Template.from_stack(stack)
+
+    # Task role should have sts:AssumeRole policy
+    template.has_resource_properties(
+        "AWS::IAM::Policy",
+        {
+            "PolicyDocument": {
+                "Statement": Match.array_with(
+                    [
+                        Match.object_like(
+                            {
+                                "Action": "sts:AssumeRole",
+                                "Effect": "Allow",
+                                "Resource": Match.string_like_regexp(
+                                    r".*assume_role_for_development_account"
+                                ),
+                            }
+                        )
+                    ]
+                )
+            }
+        },
+    )
+
+    # Container should have CROSS_ACCOUNT_ROLE_ARN env var
+    template.has_resource_properties(
+        "AWS::ECS::TaskDefinition",
+        {
+            "ContainerDefinitions": Match.array_with(
+                [
+                    Match.object_like(
+                        {
+                            "Environment": Match.array_with(
+                                [
+                                    {
+                                        "Name": "CROSS_ACCOUNT_ROLE_ARN",
+                                        "Value": Match.string_like_regexp(
+                                            r".*assume_role_for_development_account"
+                                        ),
+                                    }
+                                ]
+                            )
+                        }
+                    )
+                ]
+            )
+        },
+    )
+
+
+def test_web_app_stack_cross_account_access_disabled_by_default(
+    cdk_app, deployment_config, app_config
+):
+    """Test that cross_account_access defaults to False and adds nothing."""
+    stack = WebApp(
+        cdk_app,
+        deployment_config,
+        app_config,
+        authentication=AuthType.NONE,
+        docker_context_path="tests/fixtures",
+        dockerfile_path="Dockerfile",
+    )
+    template = Template.from_stack(stack)
+
+    # Should have no IAM policy with sts:AssumeRole for cross-account role
+    # (the only policies should be for logging, not sts:AssumeRole)
+    policies = template.find_resources("AWS::IAM::Policy")
+    for _policy_id, policy in policies.items():
+        statements = (
+            policy.get("Properties", {}).get("PolicyDocument", {}).get("Statement", [])
+        )
+        for stmt in statements:
+            if stmt.get("Action") == "sts:AssumeRole":
+                resource = stmt.get("Resource", "")
+                assert "assume_role_for_development_account" not in str(resource)
+
+
+def test_web_app_stack_cross_account_access_true_in_prod(
+    prod_cdk_app, prod_deployment_config, app_config
+):
+    """Test that cross_account_access=True in production adds no AssumeRole policy."""
+    stack = WebApp(
+        prod_cdk_app,
+        prod_deployment_config,
+        app_config,
+        authentication=AuthType.NONE,
+        docker_context_path="tests/fixtures",
+        dockerfile_path="Dockerfile",
+        cross_account_access=True,
+    )
+    template = Template.from_stack(stack)
+
+    # Even with cross_account_access=True, production should have no
+    # sts:AssumeRole policy for the cross-account role
+    policies = template.find_resources("AWS::IAM::Policy")
+    for _policy_id, policy in policies.items():
+        statements = (
+            policy.get("Properties", {}).get("PolicyDocument", {}).get("Statement", [])
+        )
+        for stmt in statements:
+            if stmt.get("Action") == "sts:AssumeRole":
+                resource = stmt.get("Resource", "")
+                assert "assume_role_for_development_account" not in str(resource)
diff --git a/uv.lock b/uv.lock
