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 │ └── 📄 common.tfvars ...
Three values will govern the behavior of SSO:
# AWS SSO sso_enabled = true sso_start_url = "https://myexample.awsapps.com/start" sso_region = "us-east-1"
sso_enableddetermines whether leverage will attempt to use credentials obtained via SSO to authenticate against AWS
sso_regionare 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 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.