Skip to content


Before deploying your AWS SSO definition in the project, it will first have to be manually enabled in the AWS Management Console.

After that, choosing and configuring an Identity Provider (IdP) is the next step. For this, we will make use of JumpCloud, as described in the how it works section. These resources point to all requirements and procedures to have your JumpCloud account setup and synched with AWS SSO:

Once this is set up, the SSO layer can be safely deployed.

Preparing the project to use AWS SSO

To implement SSO authentication in your IaC definition, some configuration values need to be present in your project.

Global configuration

In the global configuration file, or common.tfvars, found in the root of the project, under the config directory

├── 📂 config
│   └── 📄 common.tfvars

Three values will govern the behavior of SSO:

sso_enabled   = true
sso_start_url = ""
sso_region    = "us-east-1"

  • sso_enabled determines whether leverage will attempt to use credentials obtained via SSO to authenticate against AWS
  • sso_start_url and sso_region are necessary to configure AWS CLI correctly in order to be able to get the credentials

When configuring AWS CLI, a default profile is created containing region and output default settings. The region value is obtained from the previously mentioned sso_region, however, you can override this behavior by configuring a region_primary value in the same global configuration file, as so:

region_primary = "us-west-2"

Account configuration

In every account configuration file, namely account.tfvars, found in the config directory under the account's folder

├── 📂 account
|   ├── 📂 config
|   │   ├── 📄 account.tfvars
|   │   └── 📄 backend.tfvars

The role to be assumed via SSO is configured:

sso_role = "DevOps"

This is the role for which credentials will be obtained via SSO when operating in the current layer.

Authentication via SSO

1. Configuring AWS SSO

Once the project has been set up to use SSO, the profiles that AWS CLI will use to authenticate against the service need to be created.

To do this, simply run leverage aws configure sso.

This step needs to be performed every time the user works in a new account that assumes a different role than the one that they are currently using. For example, if the user is working in the security account, assuming the DevOps role, but needs to operate on a layer of the management account which requires assuming an Administrator role, then SSO needs to be reconfigured.


This step simply writes over the credentials files for AWS CLI without asking for confirmation from the user. So it's recommended to backup/wipe old credentials before executing this step in order to avoid loss of credentials or conflicts with profiles having similar names to the ones generated by Leverage.

2. Logging in

This step is executed as part of the previous one. So if the user has just configured SSO, this step is not required.

Having SSO configured, the user will proceed to log in.

This is achieved by running leverage aws sso login.

In this step, the user is prompted to manually authorize the log in process via a web console.

When logging in, Leverage obtains a token from SSO. This token is later used to obtain the credentials needed for the layer the user is working on. This token has a relatively short life span to strike a balance between security and convenience for the user.

3. Working on a layer

When SSO is enabled in the project, Leverage will automatically figure out the required credentials for the current layer, and attempt to get them from AWS every time the user executes a command on it.

These credentials are short lived (30 minutes) for security reasons, and will be refreshed automatically whenever they expire.

4. Logging out

When the user has finished working, running leverage sso logout wipes out all remaining valid credentials and voids the token obtained from logging in.