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

# Configure External Authentication

> Understand how external identity providers integrate with AWS IAM Identity Center (formerly AWS SSO), what SCIM means, and how this affects user and group management

<Note>
  If you are looking for information about how to set up external IdPs, check our [Resources](#resources) section
</Note>

# Overview

There are two main ways your organization might manage authentication in AWS IAM Identity Center:

* **External Identity Provider (IdP):** Authentication is delegated to an external provider (e.g., Okta, Azure AD, Google Workspace):
  * SCIM enabled – Users and groups are automatically synchronized from the external IdP into AWS. Permissions to groups are assigned in AWS using Fast Foundation.
  * SCIM disabled – IdP acts as an authenticator only. Users must exist both in the external IdP and in AWS Identity Center. Access Groups and Attachments are managed in AWS using Fast Foundation.

* **No External Identity Provider (IdP):** All users and groups are created and managed directly in AWS IAM Identity Center, without external synchronization.

We will focus here on the first group.

***

## SCIM Enabled Organizations

When **SCIM (System for Cross-domain Identity Management)** is enabled:

<Note>
  Users and Groups are created in your external provider, and synchronized with AWS IAM Identity Center. Permission management still needs to be managed by AWS.
</Note>

### User Management Flow

<Steps>
  <Step title="Create Users in External Provider">
    Add users in your main IdP (Entra ID, Google Workspace, Okta, etc.).
  </Step>

  <Step title="Create Groups in External Provider">
    Define groups that align with AWS access needs, for example:

    * `AWS-Development-Team`
    * `AWS-Production-ReadOnly`
    * `AWS-Infrastructure-Admins`
  </Step>

  <Step title="Assign Users to Groups">
    Manage memberships in the external provider only.
  </Step>

  <Step title="Verify Synchronization">
    Check AWS Identity Center to confirm users and groups appear as expected.
  </Step>

  <Step title="Reference Groups in Terraform">
    In Terraform, reference external groups rather than creating them manually:

    ```hcl theme={null}
    users = [
      # No users defined - managed externally via SCIM
    ]

    management_mode      = "external"
    scim_identity_source = "Okta" # For tagging/reference only

    permission_sets = {
      "PowerUser" = {
        description          = "Power user access"
        session_duration     = "PT8H"
        aws_managed_policies = ["arn:aws:iam::aws:policy/PowerUserAccess"]
      }
    }

    external_groups = {
      "AWS-Development-Team" = {  # Must match external group name
        description = "Synchronized from external IdP"
        assignments = [
          {
            permission_set = "PowerUser"
            accounts       = ["workload-development"]
          }
        ]
      }
    }
    ```
  </Step>
</Steps>

### Important Considerations

<Warning>
  * **Group names must match exactly** between the external provider and Terraform configuration
  * **Do not define users in Terraform** — they must exist in the IdP first
  * **Membership changes must be made externally** — they will not take effect if changed in Terraform
</Warning>

***

## SCIM Disabled Organizations

If SCIM is disabled but an external provider is used:

<Note>
  Users authenticate via the external IdP, but **groups and permissions are managed inside AWS IAM Identity Center**. Users must exist both in the external IdP and AWS.
</Note>

### User Management Process

<Steps>
  <Step title="Create Users in External Provider">
    Ensure users exist in the external provider so they can authenticate.
  </Step>

  <Step title="Create Users in AWS Identity Center and Assign Them to Groups">
    Manage groups in Terraform as usual:

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

***

## No External Provider

When using AWS Identity Center's internal directory only:

<Steps>
  <Step title="Manage Everything in AWS Identity Center">
    Both users and groups are defined in Terraform and stored in Identity Center:

    ```hcl theme={null}
    users = [
      {
        display_name = "Jane Smith"
        email        = "jane.smith@company.com"
        given_name   = "Jane"
        family_name  = "Smith"
        groups       = ["DevelopmentTeam"]
      }
    ]

    access_groups = [
      {
        name = "DevelopmentTeam"
        description = "Development team access"
        aws_managed_policies = ["arn:aws:iam::aws:policy/PowerUserAccess"]
        accounts_names = ["<development_workload_account>"]
      }
    ]
    ```
  </Step>

  <Step title="Complete User Setup in Console">
    After Terraform applies changes:

    1. Send verification emails from the AWS Identity Center console
    2. Reset temporary passwords
    3. Users configure MFA during their first login
  </Step>
</Steps>

***

## Resources

* [Okta: How to Setup Okta as an Identity Provider in AWS IAM Identity Center](https://www.youtube.com/watch?v=V6VrC5gO6oU)
* [EntraID: Federate your Existing IAM Identity Center instance with Microsoft Entra ID](https://www.youtube.com/watch?v=iSCuTJNeN6c)

***

## Troubleshooting External Authentication

<AccordionGroup>
  <Accordion title="Users can't access AWS Identity Center">
    **Possible causes:**

    * User doesn't exist in external IdP
    * IdP integration is misconfigured
    * User not assigned to AWS SSO application in IdP

    **Solutions:**

    1. Verify user exists in IdP
    2. Check application assignments in IdP
    3. Test SAML/SCIM connectivity
  </Accordion>

  <Accordion title="Groups not synchronizing (SCIM)">
    **Possible causes:**

    * SCIM misconfiguration
    * Group name mismatch
    * Provisioning scope limitations

    **Solutions:**

    1. Review SCIM logs in IdP
    2. Ensure group names match exactly
    3. Check provisioning scope
  </Accordion>

  <Accordion title="Permission changes not taking effect">
    **Possible causes:**

    * Terraform references groups that don't exist
    * Membership updates made in the wrong system
    * Synchronization delays

    **Solutions:**

    1. Confirm group exists in IdP (SCIM enabled)
    2. Apply membership changes in correct system
    3. Wait 15–30 minutes for sync
  </Accordion>
</AccordionGroup>

***

## Best Practices

<Check>
  **External Authentication Best Practices**

  * Understand your setup – know whether SCIM is enabled or authentication-only
  * Use consistent naming conventions for groups (e.g., prefix with `AWS-`)
  * Document your provider configuration and processes
  * Test changes in a non-production environment first
  * Monitor synchronization status regularly
  * Coordinate team changes — ensure everyone knows which system to use
</Check>