> ## 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 with External Identity Provider (IdP)

> Learn how to manage users and groups in Fast Foundation with External IdP

# 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, including the administration of external users and groups provisioned
through identity providers such as Okta. 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.

## Scenario 1: External IdP with SCIM

An external identity provider (IdP) is a service such as Okta or Azure AD that manages users and groups outside of AWS.
When integrated with AWS IAM Identity Center, the SCIM (System for Cross-domain Identity Management) standard is used to automatically
provision and synchronize users and groups from the external IdP into AWS.

### Creating Access Groups for externally created Groups

<Steps>
  <Step title="Add access group definition">
    To create a new access group, add an object inside the `external_groups` key of the `inputs.hcl` file.

    <Warning>
      The `name` MUST match the name of the group created in the External Identity Provider.
    </Warning>

    <CodeGroup>
      ```hcl inputs.hcl theme={null}
      locals {
        management_mode  = "external"
        scim_identity_source  = "Okta"

        external_groups = [
          {
            name                    = "FastFoundation - Devs"
            description             = "Administrator Access for External Fast Foundation Devs Team"
            session_duration        = "PT4H"
            customer_managed_policies = []
            
            inline_policies = []
            
            aws_managed_policies = [
              "arn:aws:iam::aws:policy/AdministratorAccess"
            ]
            
            accounts_names = [
              "workload-development",
              "workload-production"
            ]
          }
        ]
      }
      ```
    </CodeGroup>

    This particular Access Group will give Administrator Access to all the users inside the "FastFoundation - Devs" group to the `workload-development`
    and `workload-production` accounts.
  </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>

## Scenario 2: External IdP without SCIM

When an external identity provider (IdP) is integrated with AWS without SCIM, only authentication (sign-in) is handled by the IdP through SAML or OIDC.
Users and groups are not automatically provisioned into AWS. This means administrators must manually create and manage users and groups
in AWS IAM Identity Center (or IAM), and keep them synchronized with the external IdP.

### Creating an Access Group

To create an access group when using an External IdP without SCIM, follow [these instructions](/workshops/3-user-management#creating-an-access-group).

<Note>
  Bear in mind that a group with the same name must exist in the External IdP.
</Note>

### Creating a User

To create a user when using an External IdP without SCIM, follow [these instructions](/workshops/3-user-management#creating-a-user).

<Note>
  Bear in mind that a user with the same name must exist in the External IdP.
</Note>

## 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-production"
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

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

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