Skip to content

Configuration

Authentication

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

📚 Prerequisites

📚 Enable AWS SSO

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:

📚 AWS JumpCloud support guide

📚 JumpCloud guide on how to configure as IdP for 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: 

# AWS SSO
sso_enabled   = true
sso_start_url = "https://myexample.awsapps.com/start"
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
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.

Attention

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.

Additional Steps

Further steps are required before you can safely start onboarding users and allowing them to sign in.

Important: most of the following steps need to be applied manually because the Terraform AWS provider does not support them yet.

Configuring MFA

Enabling and requiring MFA is highly recommended. We typically choose these following guidelines:

  • Prompt users for MFA: Only when their sign-in context changes (context-aware).
  • Users can authenticate with these MFA types: we allow security keys, built-in authenticators (such as fingerprint or retina/face scans), and authenticator apps.
  • If a user does not yet have a registered MFA device: require them to register an MFA device at sign in.
  • Who can manage MFA devices: users and administrators can add and manage MFA devices.

Refer to the official documentation for more details.

Configure session settings

By default, the SSO session is set to last 12 hours. This is a good default but we still prefer to share this decision making with the Client -- e.g. focal point, dev/qa team, data science teams. They might factor in considerations such as security/compliance, UX/DevEx, operational needs, technical constraints, administration overheads, cost considerations, and more.