> ## 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.

# User Management

> Learn how to manage users and groups in Fast Foundation

# What you'll learn

This workshop provides a comprehensive introduction to managing users and access controls within your Fast Foundation environment.
You will learn how to create and manage users and groups. The workshop will also cover best practices for assigning inline policies, applying AWS
managed policies, and managing group access across AWS accounts within the Fast Foundation multi-account architecture.

## Prerequisites

Before starting this workshop, ensure you have:

* [User management profile configured in your AWS config file](/aws-sso/3-set-up-aws-sso-locally#special-case%3A-user-management-profile)
* AWS SSO signed in: `aws sso login --profile <your-project-name>-user-management`
* Understanding of [AWS IAM concepts and group management](/user-management/2-manage-aws-users-and-groups)

## Getting Started

Let's begin by locating the file where user management is accomplished inside the project. In your infrastructure repository,
navigate to:

```
Infrastructure/
└── infrastructure/
    └── production/
        └── <your-region>/
            └── permissions/
                └── sso/
                    └── main/
                        ├── terragrunt.hcl
                        └── inputs.hcl
```

The `inputs.hcl` file contains the configuration for the user management module.

## Creating an Access Group

<Steps>
  <Step title="Add access group definition">
    To create a new access group, add it to the `access_groups` list of the `inputs.hcl` file.

    <CodeGroup>
      ```hcl inputs.hcl theme={null}
      locals {
        management_mode  = "internal"

        access_groups = [
          {
            name         = "Developers"
            description  = "Development team access"
            session_duration = "PT8H"
            accounts_names = [
              "workload-development",
              "workload-production"
            ]
            
            aws_managed_policies = [
              "arn:aws:iam::aws:policy/PowerUserAccess"
            ]
          }
        ]
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Understand the parameters">
    **Required fields:**

    * `name` – Unique identifier for the group
    * `description` – What the group is for
    * `accounts_names` – Which AWS accounts members can access

    **Optional fields:**

    * `session_duration` – How long access tokens remain valid (default: PT1H)
    * `relay_state` – URL to redirect users after login
    * `aws_managed_policies` – AWS-provided policies (by ARN)
    * `inline_policies` – Custom policies attached to this group
    * `customer_managed_policies` – ARNs of existing policies in target accounts
  </Step>

  <Step title="Apply changes">
    Save your file and apply:

    ```bash theme={null}
    # Open a terminal in the directory you are working on

    # Review planned changes
    terragrunt plan

    # Apply changes
    terragrunt apply
    ```
  </Step>
</Steps>

### Add inline policies to access groups

Optionally, you can attach an inline policy to an Access Group. An inline policy is a block of text formatted as an IAM policy
that you add directly to your Access Group.

<Steps>
  <Step title="Add inline policy definition">
    <CodeGroup>
      ```hcl inputs.hcl theme={null}
      locals {
        management_mode  = "internal"

        access_groups = [
          {
            name         = "Developers"
            description  = "Development team access"
            session_duration = "PT8H"
            accounts_names = [
              "workload-development",
              "workload-production"
            ]

            inline_policies = [
              {
                "name": "ListAllMyBuckets",
                "statements": [
                  {
                    "sid": "ListAllMyBuckets",
                    "effect": "Allow",
                    "actions": ["s3:ListAllMyBuckets"],
                    "resources": ["*"]
                  }
                ]
              }
            ]
          }
        ]
      }
      ```
    </CodeGroup>

    This access group would allow all the users inside the "Developers" group to list the S3 Buckets in the `workload-development`
    and `workload-production` accounts.
  </Step>

  <Step title="Apply changes">
    Save your file and apply:

    ```bash theme={null}
    # Open a terminal in the directory you are working on

    # Review planned changes
    terragrunt plan

    # Apply changes
    terragrunt apply
    ```
  </Step>
</Steps>

### Common Access Group Patterns

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

    ```hcl theme={null}
    {
      name                 = "InfrastructureAdmins"
      description          = "Full administrative access to infrastructure"
      session_duration     = "PT2H"
      aws_managed_policies = ["arn:aws:iam::aws:policy/AdministratorAccess"]
      accounts_names       = ["infrastructure"]
    }
    ```
  </Accordion>

  <Accordion title="Development Team">
    Developer access with custom EKS (Elastic Kubernetes Service) permissions:

    ```hcl theme={null}
    {
      name             = "DEV-Developers"
      description      = "Developers Access to DEV accounts."
      relay_state      = "https://console.aws.amazon.com/secretsmanager"
      session_duration = "PT8H"
      
      customer_managed_policies = []
      
      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 = ["*"]
            }
          ]
        },
      ]
      
      aws_managed_policies = []
      
      accounts_names = [
        "workload-development"
      ]
    }
    ```
  </Accordion>

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

    ```hcl theme={null}
    {
      name                 = "Auditors"
      description          = "Read-only access for compliance auditing"
      session_duration     = "PT4H"
      aws_managed_policies = ["arn:aws:iam::aws:policy/ReadOnlyAccess"]
      accounts_names       = [
        "workload-production",
        "workload-development",
        "security-tooling"
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Creating a User

<Steps>
  <Step title="Add user definition">
    To create a new user (and assign it to an existing access group), add it to the `users` list of the `inputs.hcl` file.

    <CodeGroup>
      ```hcl inputs.hcl theme={null}
      locals {
        management_mode  = "internal"

        access_groups = [
          {
            name         = "Developers"
            description  = "Development team access"
            session_duration = "PT8H"
            accounts_names = [
              "workload-development",
              "workload-production"
            ]
            
            aws_managed_policies = [
              "arn:aws:iam::aws:policy/PowerUserAccess"
            ]
          }
        ]

        users = [
          {
            username     = "john.doe"
            display_name = "John Doe"
            email        = "john.doe@company.com"
            given_name   = "John"
            family_name  = "Doe"
            groups       = ["Developers"] # group(s) the user will be assigned to
          }
        ]
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Apply changes">
    Save your file and apply:

    ```bash theme={null}
    # Open a terminal in the directory you are working on

    # Review planned changes
    terragrunt plan

    # Apply changes
    terragrunt apply
    ```
  </Step>

  <Step title="Complete User Setup">
    After Terraform creates the user, complete setup in AWS SSO:

    1. Log in to the **Infrastructure account**
    2. Go to **AWS Identity Center** → **Users**
    3. Select the new user
    4. Click **Send email verification link**
    5. Click **Reset password**

    The user will then receive emails to verify their account, set a password, and configure MFA (Multi-Factor Authentication).
  </Step>
</Steps>

## Assign Groups to AWS applications

To grant access to a customer-managed application in AWS IAM Identity Center, you can assign groups to the application.
All users who are members of that group will automatically inherit access to the application,
simplifying access management and ensuring consistent permission handling.

In the **Infrastructure AWS account**:

1. Go to **AWS Identity Center** → **Applications** → **Customer managed**
2. Find and open the application
3. Click **Assign users and groups**
4. Switch to the **Groups** tab
5. Select the access groups that need access
6. Click **Assign**

Some applications require extra configuration steps before the users can interact with them.
For example, the Cloud Connexa VPN Application requires [this extra configuration steps](/user-management/4-cloud-connexa-vpn-access#configure-sso-access).