> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastfoundation.nimble.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage AWS Users & Groups

> Create and manage users, permission sets, and access groups for AWS accounts and resources

## Understanding the Configuration

User and access group definitions live in your Infrastructure as Code (IaC) repository as Terragrunt parameters. The configuration has three **main building blocks**:

<Tabs>
  <Tab title="Permission Sets">
    Permission sets are **reusable policy definitions** that can be shared across multiple groups. Each permission set defines the policies and session duration independently from the groups that use it.

    ```hcl theme={null}
    permission_sets = {
      "PowerUser" = {
        description          = "Power user access"
        session_duration     = "PT8H"
        aws_managed_policies = ["arn:aws:iam::aws:policy/PowerUserAccess"]
      }
      "EKSAdmin" = {
        description     = "Administrator access to EKS resources"
        relay_state     = "https://console.aws.amazon.com/eks"
        session_duration = "PT1H"
        inline_policies = [
          {
            name = "EKSClusterAccess"
            statements = [
              {
                sid       = "EKSFullAccess"
                actions   = ["eks:*"]
                resources = ["*"]
              }
            ]
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Access Groups">
    Access groups define **who can access what**. Each group has a list of **assignments** that map a permission set to a list of accounts. One group can have different permission sets on different accounts.

    ```hcl theme={null}
    access_groups = {
      "DevelopmentTeam" = {
        description = "Full access for development team"
        assignments = [
          {
            permission_set = "PowerUser"
            accounts       = ["workload-development", "workload-staging"]
          },
          {
            permission_set = "EKSAdmin"
            accounts       = ["workload-development"]
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Users">
    Users represent individuals in your organization. Each user belongs to one or more groups, which determine their access:

    ```hcl theme={null}
    users = [
      {
        display_name = "Jane Smith"
        email        = "jane.smith@company.com"
        given_name   = "Jane"
        family_name  = "Smith"
        groups       = [
          "DevelopmentTeam",
          "LogsReadOnly"
        ]
      }
    ]
    ```
  </Tab>
</Tabs>

***

## Permission Set Examples

<AccordionGroup>
  <Accordion title="Administrative Access">
    Full administrative rights:

    ```hcl theme={null}
    "Management" = {
      description          = "Administrator access for all member accounts"
      session_duration     = "PT4H"
      aws_managed_policies = ["arn:aws:iam::aws:policy/AdministratorAccess"]
    }
    ```
  </Accordion>

  <Accordion title="Developer Access with Custom Policies">
    Scoped access to Secrets Manager with tag-based filtering:

    ```hcl theme={null}
    "DevSecretsAccess" = {
      description      = "Scoped Secrets Manager access for developers"
      relay_state      = "https://console.aws.amazon.com/secretsmanager"
      session_duration = "PT8H"
      inline_policies = [
        {
          name = "secretsManagerAccess"
          statements = [
            {
              sid     = "readwriteSecrets"
              actions = [
                "secretsmanager:GetSecretValue",
                "secretsmanager:DescribeSecret",
                "secretsmanager:PutSecretValue",
                "secretsmanager:UpdateSecret"
              ]
              resources = ["*"]
              conditions = [
                {
                  test     = "StringEquals"
                  variable = "aws:resourceTag/team"
                  values   = ["developers"]
                }
              ]
            },
            {
              sid       = "listSecrets"
              actions   = ["secretsmanager:ListSecrets"]
              resources = ["*"]
            }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Read-Only Access">
    Limited, read-only access for audit and compliance teams:

    ```hcl theme={null}
    "ReadOnly" = {
      description          = "Read-only access for compliance auditing"
      session_duration     = "PT4H"
      aws_managed_policies = ["arn:aws:iam::aws:policy/ReadOnlyAccess"]
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Access Group Examples

<AccordionGroup>
  <Accordion title="Admins — Same permissions everywhere">
    A group with the same permission set across all accounts:

    ```hcl theme={null}
    "InfrastructureAdmins" = {
      description = "Full administrative access to infrastructure"
      assignments = [
        {
          permission_set = "Management"
          accounts = [
            "infrastructure",
            "security-tooling",
            "workload-production",
            "workload-development"
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Developers — Different permissions per environment">
    A group with `PowerUser` on dev/staging but `ReadOnly` on production:

    ```hcl theme={null}
    "Developers" = {
      description = "Development team access"
      assignments = [
        {
          permission_set = "PowerUser"
          accounts       = ["workload-development", "workload-staging"]
        },
        {
          permission_set = "ReadOnly"
          accounts       = ["workload-production"]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Auditors — Read-only everywhere">
    ```hcl theme={null}
    "Auditors" = {
      description = "Read-only access for compliance auditing"
      assignments = [
        {
          permission_set = "ReadOnly"
          accounts = [
            "workload-production",
            "workload-development",
            "security-tooling"
          ]
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Best Practices

<Check>
  * **Define permission sets once, reuse across groups** -- Avoid duplicating policy definitions
  * **Use descriptive names** -- Make it obvious what each permission set and group is for
  * **Follow least privilege** -- Grant only the permissions required
  * **Different permissions per environment** -- Use multiple assignments to give broader access in dev, restricted in production
  * **Adjust session durations by environment** -- Shorter in production, longer in development
  * **Review regularly** -- Periodically audit and remove unused users or groups
</Check>