Boss way to authenticate AWS CLI with SSO for multi-account orgs

7 min readJan 4, 2024

I’ve worked in many companies where AWS organizations are used and I see the same thing over and over again. Engineers don’t know how to take advantage of single-sign on capabilities of the AWS CLI. It’s one of these things that annoys you just a little bit every day, and you wish there was a better way but never have time to really research. Today I’m going make your days a little brighter with a simple setup, and you’ll impress your friends and colleagues when screen-sharing.

Quick Context

Your company is using AWS organizations and they give you a sign-in URL that might look something like https://d-xxxxxx.awsapps.com/start/#/

You follow the prompts and land on a page with one or more accounts, for example like that:

Then you can pick a AWS account and a role, and choose to go to the Web UI or click the Command line link for instructions.

The hard way

When clicking on the Command line link, this window opens:

Most people familiar with AWS will immediately recognize the familiar environment variables and go to Option 1, cause it says Option 1, and paste that in their terminal and voila, access granted.

A few hours later, they realize the credentials have expired, go back to that screen, copy the new set of keys and move on.

The next day, they need to run some commands in another account. A lot of engineers will just go back to that screen, copy the new set of keys and so on and so forth, day after day.

One thing is for certain, nobody likes doing that…

Level 1

Let me direct your attention to the top part of the previous screen capture. Where it says “AWS IAM Identity blah blah blah (…) (Recommended)”. Why doesn’t it say Option 1 or Option 0, I’m not sure, or why they don’t put “recommended” first and in bold, cause the actual Options 1, 2, 3 suuuc… are not the best. Though they all specify “Short-term credentials”, devs pattern-recognition neural nets are drawn to the familiar keys.

Then in bold but in the middle of the second line, the golden nugget:

aws configure sso

(cue heavenly music…)

Go to your favorite terminal and follow the prompt but do it right!

Type in a easy to remember SSO session name. What is a session name you might ask? This is a label for the AWS organization essentially, like a domain in Windows world. For example: myorg. Some companies will use multiple organizations but we’ll get back to that.
Pick a AWS account, not at random, but the one you’re likely to use first.
Pick a role if you have the option. Sometimes, you only have a single role for that account, so the CLI will pick it for you.
Type in the default region for that account.
Type in the default output format for the CLI, json or yaml, json by default.
Now that’s the important part. DO NOT CHOOSE THE DEFAULT NAME FOR THE PROFILE. Cause you’ll have to switch between profiles later and you don’t want to have to look it up in the config file every time. Pick an easy to remember name like sandbox-admin if you have potentially multiple roles for the sandbox account. Or just sandbox (in most cases just one role that you care about).

C:\>aws configure sso
SSO session name (Recommended): thynkbetter
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:

https://device.sso.us-east-1.amazonaws.com/

Then enter the code:

JCBR-LFGN
There are 5 AWS accounts available to you.
Using the account ID 614342655623
The only role available to you is: AdministratorAccess
Using the role name "AdministratorAccess"
CLI default client Region [None]: us-east-1
CLI default output format [None]: json
CLI profile name [AdministratorAccess-614342655623]: sandbox

To use this profile, specify the profile name using --profile, as shown:

aws s3 ls --profile sandbox

In case you didn’t catch that

A CLI Profile (aka named profile) is a combination of a single account and a single role which can have a default region, format and other properties.

Now, for the love of AI, do not use this as it suggests in the prompt

aws s3 ls --profile sandbox

Do you really seriously want to type this profile thing for every single command? Your time is precious, instead use

export AWS_PROFILE=sandbox (linux/mac)
set AWS_PROFILE=sandbox (windows)

Then

aws s3 ls
aws ec2 blah blah
aws ...
aws ...
and so on

If you’re not sure who you are anymore, at least in the terminal, try

C:\>aws sts get-caller-identity
{
    "UserId": "AROAY6F3C6VHUEBNCH6AY:matt@thebossway.com",
    "Account": "614342655623",
    "Arn": "arn:aws:sts::614342655623:assumed-role/AWSReservedSSO_AdministratorAccess_3058ad89sd0625/matt@thebossway.com"
}

Hey, I’m matt@thebossway.com with SSO Role AdministratorAccess. Awesome!

Miracle #1

After a while you get logged out, cause… security. Or you shut down your machine and come back the next day. What is a boss engineer to do?

aws sso login
set AWS_PROFILE=sandbox
aws s3 ls

That’s it! Done!

No more cut and paste. Get logged out again, aws sso login, all day long! But wait… there’s more, so much more…

Since you only have one org right now, no need to specify the session name or “domain”, you just get logged in to the default one.

Make sure you do set a AWS_PROFILE or face the confusing error message:

C:\>aws s3 ls

Unable to locate credentials. You can configure credentials by running "aws configure".

What do you mean? I already configured this. This should say instead “aws profile not specified, run this or that to select an existing profile”. Or even better, show a list of profiles to choose from. Free advice, AWS.

Level 2

I don’t want to have to set my environment variable profile every morning or every time I start a terminal cause I’m lazy and time is money.

Option 0 (skip! sigh)

During aws configure sso, select “yes” when asked “is this the default profile”. This option doesn’t exist though, sad… AWS, please add this.

Option 1

Set AWS_PROFILE as a global environment variable. You know how…

Option 2

aws configure set default.sso_session = myorg
aws configure set default.sso_account_id = 614342655623
aws configure set default.sso_role_name = AdministratorAccess
aws configure set default.region = us-east-1
aws configure set default.output = json

Option 3

Edit ~/.aws/config

Copy your favorite profile section, for example

[profile sandbox]
sso_session = myorg
sso_account_id = 614342655623
sso_role_name = AdministratorAccess
region = us-east-1
output = json

and paste as

[default]
sso_session = myorg
sso_account_id = 614342655623
sso_role_name = AdministratorAccess
region = us-east-1
output = json

NOT [profile default], just [default]

Now close the terminal, re-open, and just:

aws s3 ls

If you have multiple profiles, some recommend to not specify a default. Cause tomorrow you might forget to set the profile for your session and delete something in the wrong account. Often though, we might only have read access anyways, or a single account. Know thyself, pick what’s right for you.
And also… don’t delete stuff with CLI. Use some kind of gitops, terraform and such.

Level 3 — Boss Level

What if you want to use another account in the same organization, or the same account with a different role. This aws configure feature is not really well documented, only the chosen once know about it. Sure you can edit the ~/.aws/config file and copy paste the profile and make changes but that’s not boss.

aws configure sso existing session autocomplete

aws configure sso exsiting session details

Pick your existing session, then follow the prompt again. Remember to pick a good profile name. Then try:

C:\>aws configure list-profiles
qa
sandbox

Now you got at least 2 profiles. How do you switch between the 2 profiles? Not by doing aws sso login again. That’d kind of defeat the “Single” in “Single Sign-On”. You’re already signed in to the ORG.

Miracle #2

set AWS_PROFILE=qa

aws s3 ls

set AWS_PROFILE=sandbox

aws s3 ls

set AWS_PROFILE=qa (again)

You get the idea…

Recap

Wake up
Drink coffee
Open terminal

aws sso login
aws sts get-caller-identity
aws s3 ls
set AWS_PROFILE=qa
aws s3 ls
set AWS_PROFILE=sandbox
aws s3 ls
set AWS_PROFILE=whatever
aws s3 ls
...

Bask in reflected glory…

And cringe when you peers copy-and-paste keys during presentations.

Conclusion

In general with engineering, if something feels awkward to you, don’t just take it. Look for a better way, it’s out there. Seek to improve. Share the knowledge.

God Level

Multiple organizations is not very common but if you’re in that situation, there is a simple solution.

aws configure sso

Just like before but then

aws sso login --sso-session myotherorg

If there is a way to simply switch between sessions, I don’t know about it, but if you know, please share!