Terraforming IAM: Organizing Permissions for Clarity and Flexibility

Managing IAM permissions in complex cloud environments can quickly become overwhelming. One effective approach is to design a Terraform lookup module that organizes, groups, and cascades fine-grained permissions into coarse-grained building blocks. This strategy allows downstream authors to work with simplified abstractions while retaining the flexibility to “drill down” when needed.

Transforming the Permission Space

Consider transforming the granular space of IAM actions into structured, high-level building blocks. Rather than working directly with every individual action, you can combine detailed IAM permission elements into larger, logically grouped units. This transformation provides users with the flexibility to choose a view that best fits their needs without enforcing a single rigid perspective.

Imagine the following abstract action space:

{
  "Action": "*:*"  # '*' for service and '*' for the specific action.
}

For a specific service (say, Athena), the space is carved down further:

athena =
  { read =
      { actions      = [ 
          "athena:BatchGetNamedQuery", 
          "athena:GetQueryExecution", 
          "athena:ListNamedQueries", 
          "athena:ListWorkGroups" ]
      , actions_glob = [ 
          "athena:BatchGet*", 
          "athena:Get*", 
          "athena:List*" 
        ]
      }
  , write =
      { actions      = [ "athena:CreateNamedQuery", "athena:StartQueryExecution" ]
      , actions_glob = [ "athena:Start*", "athena:Stop*" ]
      }
  }

This structured carving of the permission space lets users interact with well-defined "spaces" without being overwhelmed by a multitude of fine-grained decisions.

Least Harmful Privilege for Humans

Instead of strictly enforcing least privilege - as is ideal for automated services - design your module with the concept of least harmful privilege in mind. For human operators, broader contextual access is often necessary to connect the dots and make informed decisions. For example, while a service might be confined to writing to a specific bucket, a human operator may require read access across multiple services to diagnose and resolve issues effectively.

Layering Permissions: Base Blocks and Statement Layers

A common strategy is to use a two-tiered approach:

1. Base Blocks:
   These represent always-allowed actions grouped by invariants (i.e., rules that must always hold true). This layer serves as the stable foundation of permissions, ensuring that basic operations (such as listing resources) are consistently available.

2. Statement Layers:
   On top of the base blocks, you can build complete IAM policy statements by combining actions with resources and conditions. This hierarchical structure permits the introduction of contextual restrictions without having to re-evaluate the invariants.

For instance, when dealing with a service like KMS, a design might be:

kms =
  { read =
      { statements =
          [ { effect    = "Allow"
            , actions   = kmsReadActionsGlob
            , resources = ["*"]
            }
          , { effect    = "Allow"
            , actions   = [ "kms:GenerateDataKey*", "kms:Decrypt" ]
            , resources = ["*"]
            , condition = { test     = "StringEquals"
                          , variable = "kms:EncryptionContext:service"
                          , values   = ["rds"]
                          }
            }
          ]
      }
  , write =
      { statements =
          [ { effect    = "Allow"
            , actions   = kmsWriteActionsGlob
            , resources = ["*"]
            }
          ]
      }
  }

This approach ensures consistency in how permissions are defined and combined, reducing the risk of conflicts when merging different permission sets.

Handling Edge Cases with Conditional Layers

Not every action fits neatly into "read" or "write" categories. Some services - like KMS - may require a blend of both to perform essential functions. In these cases, adding a conditional layer that combines blocks of actions with additional conditions or resource restrictions can capture nuanced dependencies between different types of actions.

Encoding Conditions and Dynamic Lookups

A flexible design can include a dynamic lookup tool - a repository of reusable IAM actions, conditions, and principals. By encoding these components, you empower downstream authors to dynamically build and reference permission sets. For example, a conditions lookup might be defined as:

conditions =
  { "StringEquals" = {}
  , "ArnLike"      = {}
  , "DateEquals"   = {}
  -- additional conditions
  }

Over time, as requirements evolve, this abstraction can pivot from a lookup tool to a mechanism that instantiates actual AWS resources. In practice, abstract permission definitions can be combined to form deployable IAM policies within your Terraform configuration.

From Abstraction to Deployed Reality

The Terraform configuration - often found in a file like main.tf -serves as the bridge between abstract permission definitions and real AWS resources. Here, the encoded actions, conditions, and resource mappings are used to generate concrete IAM policies:

data "aws_iam_policy_document" "this" {
  for_each = { for v in flatten([for access in keys(iam_actions) : [for k in keys(iam_actions[access]) : "${access},${k}"]]) : v => v }

  dynamic "statement" {
    for_each = iam_actions[split(",", each.key)[0]][split(",", each.key)[1]]
    content {
      effect    = statement.value.effect
      resources = lookup(statement.value, "resources", null)
      actions   = lookup(statement.value, "actions", null)
      dynamic "condition" {
        for_each = lookup(statement.value, "condition", null) == null ? [] : [statement.value.condition]
        content {
          test     = condition.value.test
          variable = condition.value.variable
          values   = condition.value.values
        }
      }
    }
  }
}

This configuration illustrates how abstract building blocks can be reified into actual IAM policies, enabling a smooth transition from design to deployment.

Visualizing the Flow

To illustrate how the permissions flow from abstraction to deployed policy, consider the following ASCII diagram:

          +-------------------------+
          |   Fine-Grained Actions  |
          +-------------------------+
                     │
                     ▼
          +-------------------------+
          |    Base Permission      |
          |         Blocks          |
          +-------------------------+
                     │
                     ▼
          +-------------------------+
          |  Conditional Statement  |
          |         Layers          |
          +-------------------------+
                     │
                     ▼
          +-------------------------+
          |  Deployed IAM Policies  |
          +-------------------------+

This diagram captures the essence of the process: starting with granular permissions, grouping them into stable base blocks, layering in additional conditions, and finally deploying robust IAM policies.

Conclusion

Designing an IAM Terraform lookup module is a balancing act. By organizing permissions into coarse-grained components, you provide clarity and flexibility, helping engineers manage complexity without sacrificing expressiveness. While tool limitations may occasionally necessitate drilling down into finer details, the overall design should aim for consistency, reusability, and a reduced cognitive load. Ultimately, embracing the principle of least harmful privilege empowers human operators with the access they need while safeguarding critical operations.

Happy coding, and may your IAM policies be ever in your favor!