Configuring the AWS Command Line Interface (CLI) for SSO
Introduction
AWS SSO lets you manage access to multiple AWS accounts from a single, unified place. It’s great in the browser console, but not so great when you’re working from the CLI. Luckily, there’s a way we can make that better. All the clickity-clickity, mousin’ around in the console is fine, but there’s nothing quite like the clackity-clackity efficiency of the keyboard and CLI to do the next-level stuff. Plus, not storing static, long-lasting keys and secrets on your machine is a much more secure configuration.
Let’s explore how to set that up.
Prep Steps
In order to take advantage of SSO at the CLI, you’ll first need to gather some information and get your workspace configured.
What you’ll need:
- Install the AWS CLI
- Your SSO sign-in URL
- The region for your SSO env (usually us-east-1)
- (Optional) The role you want to use for this profile - you may have more than one role assigned to your account (like read and admin), and you’ll need to figure out which one you want to use with the AWS CLIfor your given task
- (Optional) Your favorite cookie recipe. To be clear, this isn’t a requirement for SSO; I just really like cookies.
Note: The above assumes you are operating in an AWS Organization that has SSO enabled and configured. If that’s not the case, and you find yourself constantly switching roles between multiple accounts, maybe schedule a lunch with your AWS administrator so you can take them out for pizza and talk about how great it could be to centrally manage your users and groups. It doesn’t have to be pizza. It could be tacos. Or a pizza-taco.
Setting Up Your Config
The Gandalf Way (Guided Setup)
Because it’s dangerous to go alone, the good folks in the AWS CLI dev department figured we could use a little help. They were fresh out of wooden swords, so instead, they gave us some automation to assist in the setup process. This section describes how that works.
Running the Config
Once you have all your prep information and the AWS CLI installed, you can start the configuration process. Let’s start by opening a terminal and running:
aws configure sso
That will prompt you for some of the information you gathered in the Prep Steps. Like this:
SSO start URL [None]: https://d-1234567cc.awsapps.com/start
SSO Region [None]: us-east-1
Once you hit enter there, it should open a browser and ask you to enter a code/verify your device. Just follow the in-browser instructions, and it should send you back to your command prompt, at which point it will show you a list of the AWS accounts to which you have access. Like this:
There are 15 AWS accounts available to you.
> Testing, testing@domain.com (123456789012)
Staging, staging@domain.com (123456789012)
Sandbox, sandbox@domain.com (123456789012)
Arrow key down to the one you want to use, and hit enter. If you have more than one role assigned, it will ask you for the role to use, as described in the Prep Steps. Choose the appropriate one for your task, and then set the region (us-east-1), output format (you can just leave this blank, unless you have a particular proclivity), and name the profile to something meaningful for that account. Like this:
Using the role name "AdministratorAccess"
CLI default client Region [us-east-1]:
CLI default output format [None]:
CLI profile name [AdministratorAccess-123456789012]: sandbox-sso
If all went well, you should see a message similar to this:
To use this profile, specify the profile name using --profile, as shown:
aws s3 ls --profile testing-sso
Go ahead and give that command a try, and it should (if you’re using the example above) give you a list of your S3 buckets. How’s that for a slice of fried gold?
The “Ain’t Nobody Got Time For That” Way (Manual Config)
The steps above are just an automated way to build or add to an AWS config file in your local profile. If you don’t have the time or the inclination to rely on wizards (or 35+-year-old Zelda references), you can skip all of the prompts above by adding the proper information directly to the config file. This section describes how to do that.
Editing the File
In your favorite text editor or IDE, start by opening the .aws/config file located in your home directory (on Mac/Linux, that would be ~/.aws/config, and on Windows that’s %USERPROFILE%\.aws\config) and adding a block that looks like this:
[profile sandbox-sso]
sso_start_url = https://d-1234567cc.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = superawesomerolename
region = us-east-1
output = json
In fact, if you’ve already run the wizard once, you should see that a similar block exists in that file. You can copy, paste, and repeat (the non-medicinal CPR) for each account to which you have access through SSO (this can be seen by logging into the portal and expanding the account list). Just make sure you update the pertinent details accordingly, and you’ll have access to all of them via the CLI. After you add them to that file, you can log in using the steps below.
Logging in Later (A Classic L-I-L)
Remember: for best-practices security reasons and as a subtle reminder to us all that the passage of time is relentless and inevitable, the creds SSO issues are temporary. So, you’ll need to refresh those bad boys every so often.
To do that, from your command prompt, run this command:
aws sso login --profile sandbox-sso
That will open a browser, ask you to log in to your SSO account, and click an approval button for verification. Once you’ve done that, you should be all set. Running that command once will cache credentials for all of the AWS accounts tied to that SSO login. That means you’ll have access to multiple environments at once from the command line without having to log in again every time you want to work on a different account.
If you’re already using named profiles in your digital toolset, then there won’t be much (if anything) you’ll need to change here. Everything should work the way it always has. If you aren’t using named profiles, well… you should be. Even if you aren’t using SSO. But, unsolicited opinions aside, you can see it in action by logging in as described above, and then running AWS CLI commands against different accounts by adding --profile <profile_name> to them. If you change the profile name, you’ll see the returned results change as well.
Conclusion
And there you have it. Using SSO at the CLI allows you to leverage the benefits of centralized user and group management, and also means better security, since you’re not storing secrets locally. Plus, if you’re already familiar with the AWS CLI and/or named profiles, this is functionally very similar. The main practical difference (outside of the initial configuration) is the addition of the initial authentication command. After that, you can continue to use your AWS profile-integrated tools the same way you always have. What’s that? You’d like to know more about what tools are available? Well, you’re in luck. Because, my friend, there are tools o’plenty. So, grab your favorites, configure those SSO-enabled named profiles, and get building!
