DEV Community

John Ajera
John Ajera

Posted on

Getting Started with AWS SSO Using `aws configure sso`

#aws #sso #cli #iam

📘 Introduction

This guide shows how to configure and use AWS SSO (IAM Identity Center) from your CLI using the aws configure sso command. It includes step-by-step setup, login, validation, and cleanup.

✅ Prerequisites

Before you begin, make sure:

  • You have AWS IAM Identity Center (formerly AWS SSO) set up in your AWS Organization.
  • You have permission to access an assigned AWS account and permission set.
  • You’ve installed the AWS CLI v2.

❗ aws configure sso only works with AWS CLI v2 and above.

⚙️ Step 1: Configure AWS SSO

Run the following command:

aws configure sso
Enter fullscreen mode Exit fullscreen mode

You'll be prompted for:

  • SSO Start URL: The URL to your AWS SSO portal (e.g., https://your-sso-portal.awsapps.com/start)
  • SSO Region: The region where SSO is configured (e.g., ap-southeast-2)

📝 You may see SSO registration scopes [sso:account:access] — this is expected and grants access to your assigned accounts.

A browser window will open showing:

A prompt asking to allow botocore-client-... access to your data will appear — this is expected and part of the AWS SSO login process.

Click Allow access to continue.

If you only have access to one account and role, the CLI will auto-select them:

The only AWS account available to you is: 123456789012
Using the account ID 123456789012
The only role available to you is: AdministratorAccess
Using the role name "AdministratorAccess"
Enter fullscreen mode Exit fullscreen mode

Then you'll be prompted to enter:

Default client Region [None]: ap-southeast-2
CLI default output format (json if not specified) [None]:
Profile name [AdministratorAccess-123456789012]: dev-sso
Enter fullscreen mode Exit fullscreen mode

What each means:

  1. Region – Match your SSO region.
  2. Output format – Press Enter to accept json.
  3. Profile name – Use a short name like dev-sso.

🔐 Step 2: Log in via AWS SSO

To authenticate:

aws sso login --profile dev-sso
Enter fullscreen mode Exit fullscreen mode

This command starts the login process and caches credentials. A browser may briefly open and complete authentication without further input. Once done, you're ready to use the CLI.

🧪 Step 3: Test the Profile

Run this to confirm setup:

aws sts get-caller-identity --profile dev-sso
Enter fullscreen mode Exit fullscreen mode

This returns your AWS identity and confirms the profile is working.

🗘️ Optional: Set the Profile as Default

To make it default:

export AWS_PROFILE=dev-sso
Enter fullscreen mode Exit fullscreen mode

Or add it to your shell config.

🔄 Re-login Before Expiry

Sessions expire after 8–12 hours. To re-login:

aws sso login --profile dev-sso
Enter fullscreen mode Exit fullscreen mode

To check when your SSO credentials expire:

jq -r 'select(.startUrl | contains("dev-sso")) | .expiresAt' ~/.aws/sso/cache/*.json
Enter fullscreen mode Exit fullscreen mode

This prints a timestamp like:

2025-05-26T10:42:21UTC
Enter fullscreen mode Exit fullscreen mode

🧼 To Remove a Profile

To fully delete a profile:

  1. Open your AWS config files:

    nano ~/.aws/config
nano ~/.aws/credentials

  2. Remove the sections related to [profile dev-sso].

There is no direct CLI command to delete a profile — editing the files manually is the correct way.

✅ Summary

With aws configure sso, you can:

  • Avoid long-lived keys
  • Log in securely to AWS accounts
  • Use profiles easily from the CLI

Top comments (0)