Skip to content

feat: Add IAM module with policies and roles management #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nhs-oliverslater merged 2 commits into from
May 27, 2026
Merged

feat: Add IAM module with policies and roles management #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3558fa0
feat: Add IAM module with policies and roles management
nhs-oliverslater May 27, 2026
511f39a
fix: restore markdownlint processing in .tool-versions
nhs-oliverslater May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .tool-versions
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,4 +25,4 @@ nodejs 24.16.0
# docker/koalaman/shellcheck latest@sha256:e40388688bae0fcffdddb7e4dea49b900c18933b452add0930654b2dea3e7d5c # SEE: https://hub.docker.com/r/koalaman/shellcheck/tags
# docker/mstruebing/editorconfig-checker 2.7.1@sha256:dd3ca9ea50ef4518efe9be018d669ef9cf937f6bb5cfe2ef84ff2a620b5ddc24 # SEE: https://hub.docker.com/r/mstruebing/editorconfig-checker/tags
# docker/sonarsource/sonar-scanner-cli 5.0.1@sha256:494ecc3b5b1ee1625bd377b3905c4284e4f0cc155cff397805a244dee1c7d575 # SEE: https://hub.docker.com/r/sonarsource/sonar-scanner-cli/tags
<!-- markdownlint-enable -->
<!-- markdownlint-restore -->
222 changes: 222 additions & 0 deletions infrastructure/modules/iam/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,222 @@
# iam

Creates iam customer-managed policies and (optionally) iam roles for any
team on the screening platform. Thin wrapper around the community
[`terraform-aws-modules/iam/aws`](https://registry.terraform.io/modules/terraform-aws-modules/iam/aws/latest)
submodules (`iam-policy` and `iam-role`), with naming and tagging supplied
by the central `tags` module via `context.tf` — so every team gets
consistent `/<service>/<project>/` paths and the standard NHS tag set
automatically.

## Usage

The module is map-driven — one invocation can produce many policies and
roles. Three typical consumer patterns:

### 1. SSO customer-managed policies (no roles)

Use this when defining the iam policies that AWS Identity Center
permission sets will reference. The SSO wiring itself
(`aws_ssoadmin_permission_set`, `aws_ssoadmin_customer_managed_policy_attachment`,
account assignments) lives in the consumer stack, not in this module.

```hcl
data "aws_iam_policy_document" "readonly" {
statement {
actions = ["s3:Get*", "s3:List*", "logs:Get*", "logs:Describe*"]
resources = ["*"]
}
}

module "iam" {
source = "git::https://github.com/NHSDigital/screening-terraform-modules-aws.git//infrastructure/modules/iam?ref=<tag>"
context = module.label.context

policies = {
sso-readonly = {
policy = data.aws_iam_policy_document.readonly.json
description = "Read-only access for the team's SSO permission set"
}
}
}
```

Reference the output from the SSO permission set in the consumer stack:

```hcl
resource "aws_ssoadmin_customer_managed_policy_attachment" "readonly" {
instance_arn = local.sso_instance_arn
permission_set_arn = aws_ssoadmin_permission_set.readonly.arn

customer_managed_policy_reference {
name = module.iam.policy_names["sso-readonly"]
path = "/<service>/<project>/" # matches the module's default iam path
}
}
```

> **Note:** customer-managed policies must exist in every account a
> permission set is provisioned into. Run this module in every workload
> account; the permission set lives once, in the Identity Center
> delegated admin account.

### 2. Service roles (no SSO)

Use this for ECS task roles, Lambda execution roles, EventBridge invoke
roles, etc.

```hcl
data "aws_iam_policy_document" "ecs_assume" {
statement {
actions = ["sts:AssumeRole"]
principals {
type = "Service"
identifiers = ["ecs-tasks.amazonaws.com"]
}
}
}

module "iam" {
source = "git::https://github.com/NHSDigital/screening-terraform-modules-aws.git//infrastructure/modules/iam?ref=<tag>"
context = module.label.context

roles = {
ecs-task = {
assume_role_policy = data.aws_iam_policy_document.ecs_assume.json
description = "ECS task role for the screening API"
policy_arns = [
"arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore",
]
inline_policies = {
secrets = data.aws_iam_policy_document.read_secrets.json
}
}
}
}
```

### 3. Role + matching policy in one call

Use `policy_keys` to wire a role to a policy created by *this same module
invocation* — useful for IRSA/OIDC trust patterns or any service role
whose policy you also want to manage here.

```hcl
module "iam" {
source = "git::https://github.com/NHSDigital/screening-terraform-modules-aws.git//infrastructure/modules/iam?ref=<tag>"
context = module.label.context

policies = {
s3-data-rw = {
policy = data.aws_iam_policy_document.data_rw.json
description = "Read/write to the screening data bucket"
}
}

roles = {
data-processor = {
assume_role_policy = data.aws_iam_policy_document.lambda_assume.json
policy_keys = ["s3-data-rw"]
}
}
}
```

## Conventions

- **Naming.** Resource names are derived from `module.this.id` plus an
`attributes` suffix — e.g. `<id>-policy-<key>` and `<id>-role-<key>`.
- **iam path.** Defaults to `/<service>/<project>/` from context. Override
globally with `var.path` or per-entry with `entry.path`.
- **Enabled switch.** Set `context.enabled = false` to disable the entire
module (e.g. in development tfvars). All resources are gated by it.
- **Descriptions.** Strongly encouraged on every policy and role —
whoever sees them in the iam console later will thank you.
- **Inline policies.** `inline_policies` is a map of name -> JSON document;
the upstream `iam-role` submodule merges all documents into a single
inline policy on the role, so the map keys are used only for caller-side
bookkeeping (they do not become inline-policy names in AWS). Prefer
`policy_keys` + `var.policies` when you need a named, attachable policy.

## What this module does NOT do

- SSO permission sets, account assignments, group/user management — lives
in the consumer stack via `aws_ssoadmin_*` and `aws_identitystore_*`.
- iam users, iam groups, SAML/OIDC identity providers
- Account-wide iam settings (password policy, account alias, MFA enforcement).

<!-- vale off -->
<!-- markdownlint-disable -->
<!-- BEGIN_TF_DOCS -->
## Requirements

No requirements.

## Providers

No providers.

## Modules

| Name | Source | Version |
| ---- | ------ | ------- |
| <a name="module_policies"></a> [policies](#module\_policies) | terraform-aws-modules/iam/aws//modules/iam-policy | 6.6.0 |
| <a name="module_policy_label"></a> [policy\_label](#module\_policy\_label) | ../tags | n/a |
| <a name="module_role_label"></a> [role\_label](#module\_role\_label) | ../tags | n/a |
| <a name="module_roles"></a> [roles](#module\_roles) | terraform-aws-modules/iam/aws//modules/iam-role | 6.6.0 |
| <a name="module_this"></a> [this](#module\_this) | git::https://github.com/NHSDigital/screening-terraform-modules-aws.git//infrastructure/modules/tags | v2.4.1 |

## Resources

No resources.

## Inputs

| Name | Description | Type | Default | Required |
| ---- | ----------- | ---- | ------- | :------: |
| <a name="input_additional_tag_map"></a> [additional\_tag\_map](#input\_additional\_tag\_map) | Additional key-value pairs to add to each map in `tags_as_list_of_maps`. Not added to `tags` or `id`.<br/>This is for some rare cases where resources want additional configuration of tags<br/>and therefore take a list of maps with tag key, value, and additional configuration. | `map(string)` | `{}` | no |
| <a name="input_application_role"></a> [application\_role](#input\_application\_role) | The role the application is performing | `string` | `"General"` | no |
| <a name="input_attributes"></a> [attributes](#input\_attributes) | ID element. Additional attributes (e.g. `workers` or `cluster`) to add to `id`,<br/>in the order they appear in the list. New attributes are appended to the<br/>end of the list. The elements of the list are joined by the `delimiter`<br/>and treated as a single ID element. | `list(string)` | `[]` | no |
| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | The AWS region | `string` | `"eu-west-2"` | no |
| <a name="input_context"></a> [context](#input\_context) | Single object for setting entire context at once.<br/>See description of individual variables for details.<br/>Leave string and numeric variables as `null` to use default value.<br/>Individual variable settings (non-null) override settings in context object,<br/>except for attributes, tags, and additional\_tag\_map, which are merged. | `any` | <pre>{<br/> "additional_tag_map": {},<br/> "attributes": [],<br/> "delimiter": null,<br/> "descriptor_formats": {},<br/> "enabled": true,<br/> "environment": null,<br/> "id_length_limit": null,<br/> "label_key_case": null,<br/> "label_order": [],<br/> "label_value_case": null,<br/> "labels_as_tags": [<br/> "unset"<br/> ],<br/> "name": null,<br/> "project": null,<br/> "regex_replace_chars": null,<br/> "region": null,<br/> "service": null,<br/> "stack": null,<br/> "tags": {},<br/> "terraform_source": null,<br/> "workspace": null<br/>}</pre> | no |
| <a name="input_data_classification"></a> [data\_classification](#input\_data\_classification) | Used to identify the data classification of the resource, e.g 1-5 | `string` | `"n/a"` | no |
| <a name="input_data_type"></a> [data\_type](#input\_data\_type) | The tag data\_type | `string` | `"None"` | no |
| <a name="input_delimiter"></a> [delimiter](#input\_delimiter) | Delimiter to be used between ID elements.<br/>Defaults to `-` (hyphen). Set to `""` to use no delimiter at all. | `string` | `null` | no |
| <a name="input_descriptor_formats"></a> [descriptor\_formats](#input\_descriptor\_formats) | Describe additional descriptors to be output in the `descriptors` output map.<br/>Map of maps. Keys are names of descriptors. Values are maps of the form<br/>`{<br/> format = string<br/> labels = list(string)<br/>}`<br/>(Type is `any` so the map values can later be enhanced to provide additional options.)<br/>`format` is a Terraform format string to be passed to the `format()` function.<br/>`labels` is a list of labels, in order, to pass to `format()` function.<br/>Label values will be normalized before being passed to `format()` so they will be<br/>identical to how they appear in `id`.<br/>Default is `{}` (`descriptors` output will be empty). | `any` | `{}` | no |
| <a name="input_enabled"></a> [enabled](#input\_enabled) | Set to false to prevent the module from creating any resources | `bool` | `null` | no |
| <a name="input_environment"></a> [environment](#input\_environment) | ID element. Usually used to indicate role, e.g. 'prd', 'dev', 'test', 'preprod', 'prod', 'uat' | `string` | `null` | no |
| <a name="input_id_length_limit"></a> [id\_length\_limit](#input\_id\_length\_limit) | Limit `id` to this many characters (minimum 6).<br/>Set to `0` for unlimited length.<br/>Set to `null` for keep the existing setting, which defaults to `0`.<br/>Does not affect `id_full`. | `number` | `null` | no |
| <a name="input_label_key_case"></a> [label\_key\_case](#input\_label\_key\_case) | Controls the letter case of the `tags` keys (label names) for tags generated by this module.<br/>Does not affect keys of tags passed in via the `tags` input.<br/>Possible values: `lower`, `title`, `upper`.<br/>Default value: `title`. | `string` | `null` | no |
| <a name="input_label_order"></a> [label\_order](#input\_label\_order) | The order in which the labels (ID elements) appear in the `id`.<br/>Defaults to ["namespace", "environment", "stage", "name", "attributes"].<br/>You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present. | `list(string)` | `null` | no |
| <a name="input_label_value_case"></a> [label\_value\_case](#input\_label\_value\_case) | Controls the letter case of ID elements (labels) as included in `id`,<br/>set as tag values, and output by this module individually.<br/>Does not affect values of tags passed in via the `tags` input.<br/>Possible values: `lower`, `title`, `upper` and `none` (no transformation).<br/>Set this to `title` and set `delimiter` to `""` to yield Pascal Case IDs.<br/>Default value: `lower`. | `string` | `null` | no |
| <a name="input_labels_as_tags"></a> [labels\_as\_tags](#input\_labels\_as\_tags) | Set of labels (ID elements) to include as tags in the `tags` output.<br/>Default is to include all labels.<br/>Tags with empty values will not be included in the `tags` output.<br/>Set to `[]` to suppress all generated tags.<br/>**Notes:**<br/> The value of the `name` tag, if included, will be the `id`, not the `name`.<br/> Unlike other `null-label` inputs, the initial setting of `labels_as_tags` cannot be<br/> changed in later chained modules. Attempts to change it will be silently ignored. | `set(string)` | <pre>[<br/> "default"<br/>]</pre> | no |
| <a name="input_name"></a> [name](#input\_name) | ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.<br/>This is the only ID element not also included as a `tag`.<br/>The "name" tag is set to the full `id` string. There is no tag with the value of the `name` input. | `string` | `null` | no |
| <a name="input_on_off_pattern"></a> [on\_off\_pattern](#input\_on\_off\_pattern) | Used to turn resources on and off based on a time pattern | `string` | `"n/a"` | no |
| <a name="input_owner"></a> [owner](#input\_owner) | The name and or NHS.net email address of the service owner | `string` | `"None"` | no |
| <a name="input_path"></a> [path](#input\_path) | Default IAM path applied to policies and roles when an entry does not override it. Defaults to `/<service>/<project>/` derived from context. | `string` | `null` | no |
| <a name="input_policies"></a> [policies](#input\_policies) | Map of IAM customer-managed policies to create.<br/><br/>Each key is a logical identifier (e.g. "read-only", "ssm-session") used<br/>in the rendered policy name. Each value is an object with:<br/><br/> policy - (required) IAM policy document JSON<br/> description - (optional) policy description<br/> path - (optional) IAM path; overrides `var.path` / context default<br/><br/>Example:<br/> policies = {<br/> readonly = {<br/> policy = data.aws\_iam\_policy\_document.readonly.json<br/> description = "Read-only access for SSO permission set"<br/> }<br/> } | <pre>map(object({<br/> policy = string<br/> description = optional(string)<br/> path = optional(string)<br/> }))</pre> | `{}` | no |
| <a name="input_project"></a> [project](#input\_project) | ID element. A project identifier, indicating the name or role of the project the resource is for, such as `website` or `api` | `string` | `null` | no |
| <a name="input_public_facing"></a> [public\_facing](#input\_public\_facing) | Whether this resource is public facing | `bool` | `false` | no |
| <a name="input_regex_replace_chars"></a> [regex\_replace\_chars](#input\_regex\_replace\_chars) | Terraform regular expression (regex) string.<br/>Characters matching the regex will be removed from the ID elements.<br/>If not set, `"/[^a-zA-Z0-9-]/"` is used to remove all characters other than hyphens, letters and digits. | `string` | `null` | no |
| <a name="input_region"></a> [region](#input\_region) | ID element \_(Rarely used, not included by default)\_. Usually an abbreviation of the selected AWS region e.g. 'uw2', 'ew2' or 'gbl' for resources like IAM roles that have no region | `string` | `null` | no |
| <a name="input_roles"></a> [roles](#input\_roles) | Map of IAM roles to create.<br/><br/>Each key is a logical identifier used in the rendered role name. Each<br/>value is an object with:<br/><br/> assume\_role\_policy - (required) trust policy JSON<br/> description - (optional) role description<br/> path - (optional) IAM path; overrides `var.path` / context default<br/> max\_session\_duration - (optional) session duration in seconds (3600-43200)<br/> permissions\_boundary - (optional) ARN of a permissions boundary policy<br/> policy\_arns - (optional) list of existing/managed policy ARNs to attach<br/> policy\_keys - (optional) list of keys from `var.policies` to attach<br/> inline\_policies - (optional) map of inline policy name -> JSON document<br/><br/>Example:<br/> roles = {<br/> ec2-bastion = {<br/> assume\_role\_policy = data.aws\_iam\_policy\_document.ec2\_assume.json<br/> policy\_arns = ["arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"]<br/> policy\_keys = ["readonly"]<br/> }<br/> } | <pre>map(object({<br/> assume_role_policy = string<br/> description = optional(string)<br/> path = optional(string)<br/> max_session_duration = optional(number, 3600)<br/> permissions_boundary = optional(string)<br/> policy_arns = optional(list(string), [])<br/> policy_keys = optional(list(string), [])<br/> inline_policies = optional(map(string), {})<br/> }))</pre> | `{}` | no |
| <a name="input_service"></a> [service](#input\_service) | ID element. Usually an abbreviation of your service directorate name, e.g. 'bcss' or 'csms', to help ensure generated IDs are globally unique | `string` | `null` | no |
| <a name="input_service_category"></a> [service\_category](#input\_service\_category) | The tag service\_category | `string` | `"n/a"` | no |
| <a name="input_stack"></a> [stack](#input\_stack) | ID element. The name of the stack/component, e.g. `database`, `web`, `waf`, `eks` | `string` | `null` | no |
| <a name="input_tag_version"></a> [tag\_version](#input\_tag\_version) | Used to identify the tagging version in use | `string` | `"1.0"` | no |
| <a name="input_tags"></a> [tags](#input\_tags) | Additional tags (e.g. `{'BusinessUnit': 'XYZ'}`).<br/>Neither the tag keys nor the tag values will be modified by this module. | `map(string)` | `{}` | no |
| <a name="input_terraform_source"></a> [terraform\_source](#input\_terraform\_source) | Source location to record in the Terraform\_source tag. Defaults to the caller module path when not set. | `string` | `null` | no |
| <a name="input_tool"></a> [tool](#input\_tool) | The tool used to deploy the resource | `string` | `"Terraform"` | no |
| <a name="input_workspace"></a> [workspace](#input\_workspace) | ID element. The Terraform workspace, to help ensure generated IDs are unique across workspaces | `string` | `null` | no |

## Outputs

| Name | Description |
| ---- | ----------- |
| <a name="output_policy_arns"></a> [policy\_arns](#output\_policy\_arns) | Map of policy key -> arn for every IAM policy created by this module. |
| <a name="output_policy_names"></a> [policy\_names](#output\_policy\_names) | Map of policy key -> name for every IAM policy created by this module. |
| <a name="output_role_arns"></a> [role\_arns](#output\_role\_arns) | Map of role key -> arn for every IAM role created by this module. |
| <a name="output_role_names"></a> [role\_names](#output\_role\_names) | Map of role key -> name for every IAM role created by this module. |
<!-- END_TF_DOCS -->
<!-- markdownlint-restore -->
<!-- vale on -->
Loading
Loading