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

# Set Up AWS SSO Locally

> Configure AWS Single Sign-On (SSO) on your local machine so you can use your AWS accounts directly from the command line.

## Introduction

After signing in to the **AWS Access Portal**, the next step is to make your credentials available on your local machine. This setup enables you to access AWS services from the command line or within your development tools—without needing to log in through the browser each time or rely on long-lived access keys.

You’ll accomplish this by creating **AWS SSO profiles**, which instruct the AWS Command Line Interface (CLI) on how to connect to the correct account and role.

***

## Configure Your AWS SSO Profiles

There are two ways to configure your SSO profiles:

* **Manual method**: Best for experienced users who prefer editing the AWS config file directly (covered in this guide).
* **Interactive method**: Recommended for beginners. Runs `aws configure sso` and walks you through each step.

<Note>
  If you'd like to explore the interactive method, check out the [AWS CLI SSO Configuration Guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html).
</Note>

***

<Steps>
  <Step title="Locate Your AWS Config File">
    The configuration file is where AWS stores profile information. Its location depends on your operating system:

    * **Linux / macOS**: `~/.aws/config`
    * **Windows**: `%USERPROFILE%\.aws\config`

    If the file doesn't exist yet, create it:

    ```bash theme={null}
    # Linux/macOS
    mkdir -p ~/.aws
    touch ~/.aws/config

    # Windows (PowerShell)
    New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.aws
    New-Item -ItemType File -Force -Path $env:USERPROFILE\.aws\config
    ```
  </Step>

  <Step title="Gather the Required Information">
    From your **AWS Access Portal**, collect:

    * **SSO start URL** → Typically `https://<company>.awsapps.com/start`
    * **Region** → The AWS region where Identity Center is configured (e.g. `us-west-2`)
    * **Account ID** → The 12-digit AWS account number
    * **Role name** → The role you'll assume (e.g. `Developer`, `ReadOnlyAccess`, `Management`)
  </Step>

  <Step title="Add Your Session and Profile Configuration">
    Open `~/.aws/config` in a text editor and add your profiles. Replace the placeholders with your own information.

    **Example (single profile):**

    ```ini theme={null}
    [sso-session <project>]
    sso_start_url = https://<project>.awsapps.com/start
    sso_region = <aws-region>
    sso_registration_scopes = sso:account:access

    [profile <project>-<accountName>]
    sso_session = <project>
    sso_account_id = 123456789012
    sso_role_name = <role-name>
    region = us-west-2
    ```

    **Template for multiple profiles:**

    ```ini theme={null}
    [sso-session <project>]
    sso_start_url = https://<project>.awsapps.com/start
    sso_region = <aws-region>
    sso_registration_scopes = sso:account:access

    [profile <project>-organization-management]
    sso_session = <project>
    sso_account_id = <organization-account-id>
    sso_role_name = <role-name>
    region = <aws-region>

    [profile <project>-infrastructure]
    sso_session = <project>
    sso_account_id = <infrastructure-account-id>
    sso_role_name = <role-name>
    region = <aws-region>

    ...
    ```

    <Note>
      ✅ Always use the **SSO start URL** provided by your administrator.\
      ✅ Only include the accounts and roles you actually have access to.\
      ✅ Follow the suggested profile naming conventions to avoid confusion.
    </Note>

    <Warning>
      **Verify Credentials File:**\
      Check your `~/.aws/credentials` file. To avoid conflict, verify there are not pre-existing profiles with the same name as those being created.
    </Warning>
  </Step>

  <Step title="Save and Verify the File">
    After saving your changes, verify that everything looks correct:

    ```bash theme={null}
    # Confirm the file has content
    cat ~/.aws/config

    # Check that AWS recognizes your profiles
    aws configure list-profiles
    ```

    You should see your newly added profile(s) listed.
  </Step>
</Steps>

### Special Case: User Management Profile

In our setup, there's a dedicated profile called **`<project>-user-management`**.\
This profile is used when you need to manage **users or access groups** in **AWS IAM Identity Center**.

Here's how it works:

* IAM Identity Center is **delegated to the Infrastructure account**.
* **For most users (non–super admins):** Use the **Infrastructure credentials** with the `<project>-user-management` profile.
* **For super admins:** You'll need to use the **Organization Management (org mgmt) credentials**, since some operations (like changing Access Groups or Users that **affect organization-management account**) require access at the organization level.

**Configuration Example:**

Choose the configuration that matches your role — you only need one:

<Tabs>
  <Tab title="Standard User (most users)">
    ```ini theme={null}
    [profile <project>-user-management]
    sso_session = <project>
    sso_account_id = <infrastructure-account-id>
    sso_role_name = <role-name>
    region = <aws-region>
    ```
  </Tab>

  <Tab title="Super Admin">
    ```ini theme={null}
    [profile <project>-user-management]
    sso_session = <project>
    sso_account_id = <organization-management-account-id>
    sso_role_name = <role-name>
    region = <aws-region>
    ```
  </Tab>
</Tabs>

***

## Test Your Configuration

Once your profiles are set up, let's test them to make sure everything works.

<Note>
  This example uses the `<project>-workload-development` profile, but you can replace it with the profile you need to test.
</Note>

<Steps>
  <Step title="Log In with SSO">
    Use the profile you just created to log in:

    ```bash theme={null}
    aws sso login --profile <project>-workload-development
    ```

    This will open your browser for authentication.
  </Step>

  <Step title="Verify Identity">
    Run this command to confirm you're authenticated:

    ```bash theme={null}
    aws sts get-caller-identity --profile <project>-workload-development
    ```

    Expected output:

    ```json theme={null}
    {
      "UserId": "AIDAIOSFODNN7EXAMPLE",
      "Account": "123456789012",
      "Arn": "arn:aws:sts::123456789012:assumed-role/RoleExample/user@example.com"
    }
    ```
  </Step>

  <Step title="Test AWS Services">
    If your role allows it and the resources exist, you can try listing resources to confirm access:

    ```bash theme={null}
    # Example: List S3 buckets
    aws s3 ls --profile <project>-workload-development

    # Example: List EC2 instances
    aws ec2 describe-instances --profile <project>-workload-development
    ```
  </Step>
</Steps>

***

<Note>
  **Helpful Reminders:**

  * Bookmark your AWS Access Portal URL: `https://<company>.awsapps.com/start/`
  * Keep your MFA device secure and accessible
  * SSO sessions expire (often after 8 hours). Re-authenticate running `aws sso login --profile <project>-workload-development`
</Note>