Configuring the AWS CLI for SSO

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:

1. Install the AWS CLI
2. Your SSO sign-in URL
3. The region for your SSO env (usually us-east-1)
4. (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
5. (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!

FAQ

How do you handle multiple AWS accounts with SSO configuration in the AWS CLI?

Managing multiple AWS accounts with Single Sign-On (SSO) through the AWS Command Line Interface (CLI) is a common requirement for larger organizations that operate across different business units or projects. The AWS CLI facilitates this by allowing users to configure SSO for each account and role they need access to. However, the intricacies of efficiently switching between these accounts are not straightforward. The process involves specifying different profile names for each account and role combination in the AWS CLI configuration. This allows users to switch between accounts by specifying the appropriate profile name when executing CLI commands. This method requires careful planning and organization to ensure that profile names are descriptive and consistently used, thereby reducing complexity and potential confusion when managing access across multiple accounts.

What are the best practices for managing credentials and permissions when using AWS CLI with SSO?

Security best practices play a crucial role when it comes to managing credentials and permissions with AWS CLI using SSO. The primary concern is to ensure that users are granted only the necessary permissions for their role, adhering to the principle of least privilege. This minimizes the risk of unauthorized access or accidental changes to critical resources. Additionally, it's important to review permissions regularly and audit them, making adjustments as roles evolve or as personnel change within the organization. Implementing strong password policies for AWS SSO and multi-factor authentication (MFA) adds an additional layer of security, protecting against unauthorized access attempts. Organizations should also consider using AWS CloudTrail to log and monitor CLI activities, enabling them to track usage patterns and promptly detect potential security incidents.

Can you automate the AWS CLI SSO login process for scripting or CI/CD pipelines?

Automating the login process for AWS CLI with SSO in scripting or CI/CD pipelines introduces a challenge, as the SSO login typically requires interactive authentication via a web browser. To address this, AWS provides several automation options, including using short-term credentials obtained through the SSO portal. These credentials can be programmatically retrieved and used in automated workflows, allowing scripts or CI/CD pipelines to authenticate with AWS services without manual intervention. However, it's important to note that this approach requires a secure handling mechanism for the temporary credentials, ensuring they are stored and transmitted securely and are only accessible to authorized entities within the automation workflow. By integrating these practices, organizations can leverage AWS CLI with SSO in automated environments, maintaining security and efficiency.