Skip to main content

​
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.
If you’d like to explore the interactive method, check out the AWS CLI SSO Configuration Guide.
1

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:
# 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
2

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)
3

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):
[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:
[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>

...
✅ 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.
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.
4

Save and Verify the File

After saving your changes, verify that everything looks correct:
# 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.

​
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: 
# Standard user: delegated admin via Infrastructure account
[profile <project>-user-management]
sso_session = <project>
sso_account_id = <infrastructure-account-id>
sso_role_name = <role-name>
region = <aws-region>

# Super admin: operates in the Org Management account
[profile <project>-user-management]
sso_session = <project>
sso_account_id = <organization-management-account-id>
sso_role_name = <role-name>
region = <aws-region>

​
Test Your Configuration

Once your profiles are set up, let’s test them to make sure everything works.
This example uses the <project>-workload-development profile, but you can replace it with the profile you need to test.
1

Log In with SSO

Use the profile you just created to log in:
aws sso login --profile <project>-workload-development
This will open your browser for authentication.
2

Verify Identity

Run this command to confirm you’re authenticated:
aws sts get-caller-identity --profile <project>-workload-development
Expected output:
{
  "UserId": "AIDAIOSFODNN7EXAMPLE",
  "Account": "123456789012",
  "Arn": "arn:aws:sts::123456789012:assumed-role/RoleExample/[email protected]"
}
3

Test AWS Services

If your role allows it and the resources exist, you can try listing resources to confirm access:
# Example: List S3 buckets
aws s3 ls --profile <project>-workload-development

# Example: List EC2 instances
aws ec2 describe-instances --profile <project>-workload-development
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