Need help with aws-sso-util?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

315 Stars 17 Forks Apache License 2.0 116 Commits 13 Opened issues


Smooth out the rough edges of AWS SSO (temporarily, until AWS makes it better).

Services available


Need anything else?

Contributors list

# 72,371
105 commits
# 124,023
Amazon ...
1 commit


Making life with AWS SSO a little easier

AWS SSO has some rough edges, and

is here to smooth them out, hopefully temporarily until AWS makes it better.

You can read a primer on AWS SSO here.

contains utilities for the following: * Configuring
* Logging in/out * AWS SDK support * Looking up identifiers * CloudFormation

, which is still available in its original form here. Read the updated docs for
aws-sso-util credential-process

Programmatic interaction with AWS SSO

provides command-line utilities. The underlying Python library for AWS SSO authentication is
, which has useful functions like interactive login, creating a boto3 session for specific a account and role, and the programmatic versions of the
functions in
. See the documentation here.


  1. It's a good idea to install the AWS CLI v2 (which has AWS SSO support).

  2. I recommend you install

    , which installs the tool in an isolated virtualenv while linking the script you need.

Mac and Linux:

brew install pipx
pipx ensurepath


python3 -m pip install --user pipx
python3 -m pipx ensurepath
  1. Install

    pipx install aws-sso-util
  2. Learn

    aws-sso-util --help
  3. Autocomplete

uses click, which supports autocompletion. The details of enabling shell completion with click vary by shell (instructions here), but here is an example for bash that updates the completion in the background.
if which aws-sso-util > /dev/null; then
  ({ _AWS_SSO_UTIL_COMPLETE=source_bash aws-sso-util > $_AWS_SSO_UTIL_COMPLETE_SCRIPT.tmp ;
  if [ -f $_AWS_SSO_UTIL_COMPLETE_SCRIPT ]; then


Read the full docs for

aws-sso-util configure
aws-sso-util roles

The AWS CLI and most AWS SDKs support AWS SSO configuration in

; each profile specifies the account and SSO role to use. A profile configured for AWS SSO looks like this:
[profile my-sso-profile]
sso_start_url =
sso_region = us-east-1 # the region AWS SSO is configured in
sso_account_id = 123456789012
sso_role_name = MyRoleName
region = us-east-2 # the region to use for AWS API calls

You can view the roles you have available to you with

aws-sso-util roles
, which you can use to configure your profiles in
, or you can use
aws configure sso
in the AWS CLI v2, but
also provides functionality to directly configure profiles for you.

aws-sso-util configure
has two subcommands,
aws-sso-util configure profile
for configuring a single profile, and
aws-sso-util configure populate
to add all your permissions as profiles, in whatever region(s) you want (with highly configurable profile names).

You probably want to set the environment variables

, which will inform these commands of your start url and SSO region (that is, the region that you've configured AWS SSO in), so that you don't have to pass them in as parameters every time.

aws-sso-util configure profile
takes a profile name and prompts you with the accounts and roles you have access to, to configure that profile.

aws-sso-util configure populate
takes one or more regions, and generates a profile for each account+role+region combination. The profile names are completely customizable.

Logging in and out

Read the full docs for

aws-sso-util login
aws-sso-util logout

A problem with

aws sso login
is that it's required to operate on a profile, that is, you have to tell it to log in to AWS SSO plus some account and role. But the whole point of AWS SSO is that you log in once for many accounts and roles. You could have a particular account and role set up in your default profile, but I prefer not to have a default profile so that I'm always explicitly selecting a profile and never accidentally end up in the default by mistake.

aws-sso-util login
solves this problem by letting you just log in without having to think about where you'll be using those credentials.

Debugging issues

Read the full docs for

aws-sso-util check

aws-sso-util check
helps diagnose configuration and access issues. It can be used to help administrators debug user issues, or as validation in shell scripting. It validates that
can find an AWS SSO instance configuration, and additionally whether the user has access to a particular account and/or role.

Adding AWS SSO support to AWS SDKs

The credential process is added automatically (by default) by the

aws-sso-util configure
commands; you only need to read this section if you're not using that or want to understand it more fully. Read the full docs for
aws-sso-util credential-process

Not all AWS SDKs have support for AWS SSO (which will change eventually). However, they all have support for

, which allows an external process to provide credentials.
aws-sso-util credential-process
uses this to allow these SDKs to get credentials from AWS SSO.

NOTE: if you test it out with your favorite script or application and get something like

NoCredentialProviders: no valid providers in chain.
, you may need to set the environment variable

Administrators: Looking up identifiers and assignments

Read the full docs for

aws-sso-util admin lookup
aws-sso-util admin assignments

When you're creating assignments through the API or CloudFormation, you're required to use identifiers like the instance ARN, the principal ID, etc. These identifiers aren't readily available through the console, and the principal IDs are not the IDs you're familiar with.

aws-sso-util admin lookup
allows you to get these identifers, even en masse.

There is no simple API for retrieving all assignments or even a decent subset. The current best you can do is list all the users with a particular PermissionSet on a particular account.

aws-sso-util admin assignments
takes the effort out of looping over the necessary APIs.

Administrators: CloudFormation support

You'll want to read the full docs here.

AWS SSO's CloudFormation support currently only includes

, which means for every combination of principal (group or user), permission set, and target (AWS account), you need a separate CloudFormation resource. Additionally, AWS SSO does not support OUs as targets, so you need to specify every account separately.

Obviously, this gets verbose, and even an organization of moderate size is likely to have tens of thousands of assignments.

aws-sso-util admin cfn
provides two mechanisms to make this concise.

I look forward to discarding this part of the tool once there are two prerequisites: 1. OUs as targets for assignments 2. An

resource that allows specifications of multiple principals, permission sets, and targets, and performs the combinatorics directly.

CloudFormation Macro

defines a resource format for an AssignmentGroup that is a combination of multiple principals, permission sets, and targets, and provides a CloudFormation Macro you can deploy that lets you use this resource in your templates.

Client-side generation

I am against client-side generation of CloudFormation templates, but if you don't want to trust this 3rd party macro, you can generate the CloudFormation templates directly.

aws-sso-util admin cfn
takes one or more input files, and for each input file, generates a CloudFormation template and potentially one or more child templates. These templates can then be packaged and uploaded using
aws cloudformation package
or the SAM CLI, for example.

The input files can either be templates using the Macro (using the

flag), or somewhat simpler configuration files using a different syntax. These configuration files can define permission sets inline, have references that turn into template parameters, and you can provide a base template that the resulting resources are layered on top of.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.