aws-login

A command line utility to simplify logging into AWS accounts and services.

$ aws-login use
? Please select a profile to use: ›
❯ dev-read
  dev-write

$ echo $AWS_PROFILE
dev-read

$ aws-login use --profile dev-write

$ echo $AWS_PROFILE
dev-write

Table of Contents

• Requirements
  • Development
• Installation
  • macOS
• Usage
  • Configuring Docker to use ECR
  • Configure kubectl to use EKS
  • Log into an AWS account using SSO portal
  • Setting up and activating AWS CLI profiles
    • Working with profile templates
  • Downloading and installing profile templates

Requirements

• AWS CLI v2

Development

• Rust 1.57

Installation

1. Go to the Releases page.
2. Download a release for your OS.
3. Unzip the release.
   • unzip -j aws-login_linux_amd64.zip
4. Make aws-login executable.
   • chmod 755 aws-login
5. Move aws-login to somewhere in your $PATH.
6. Run aws-login shell install -s $SHELL, where $SHELL is your supported shell.
   • See aws-login shell --help for a list of supported shells.
7. Start a new shell session.

macOS

On more recent versions of macOS, Gatekeeper will block your attempt to run the application because it is not signed with an Apple Developer certificate. Please see this guide on how to work around this issue.

Usage

Before we dive into using the application, you need to be aware of how profiles work with the AWS CLI. The official AWS CLI supports the use of profiles so that information such as accounts, roles, and preferences are remembered. This saves you from having to provide that information each time you want to do something.

The aws-login utility attempts to take full advantage of AWS CLI profiles. When "active AWS CLI profile" is mentioned, it means one of two things:

• The value of the AWS_PROFILE environment variable.
• Or "default".

By default, everything you do with aws-login will use the profile found in one of the places mentioned above and in the order they are listed. However, like AWS CLI, you can change the profile you are working with by using the --profile option.

Configuring Docker to use ECR

aws-login ecr

This subcommand will configure Docker to use the Elastic Container Registry in the AWS account for your active AWS CLI profile. If the region for your ECR differs from the default region configured for your profile, remember to specify it with the --region option.

Configure kubectl to use EKS

aws-login eks

This subcommand will prompt you to choose an EKS cluster from a list found in the AWS account for your active AWS CLI profile. Once a selection is made, the configuration for kubectl is updated to support connecting to that EKS cluster. Remember to log in before attempting to do so, fresh credentials may be required.

Log into an RDS Proxy using IAM

aws-login rds $USERNAME

This subcommand will prompt you to choose an RDS Proxy from a list found in the AWS account for your active AWS CLI profile. Once a selection is made, the database authentication token will be generated for you to use in your preferred database client.

It is important to note that generating a token will almost always succeed, even if you do not have permission to access the RDS Proxy endpoint. If authentication fails, you will want to check a few things:

1. Make sure your TLS settings match.
2. Make sure you are using the correct AWS CLI profile.
3. Make sure your role has the IAM rds-db:connect permission.

Log into an AWS account using AWS SSO portal

aws-login sso

This subcommand will use the AWS SSO portal settings in your active AWS CLI profile for authentication. If the required settings are missing, you will be prompted to provide them before authentication can proceed.

Setting up and activating AWS CLI profiles

aws-login use

This subcommand will prompt you to selected from a list of existing AWS CLI profiles and available profile templates. If a profile template is selected and a corresponding AWS CLI profile does not already exist, it will be automatically configured using the template. Once a selection has been made, the shell environment is modified to make it the active AWS CLI profile for the duration of the shell session.

Working with profile templates

The use subcommand does not simply offer you the ability to select existing AWS CLI profiles, but also offers the ability to use profile templates to configure new AWS CLI profiles. These templates are stored in JSON file called templates.json (found in ~/.config/aws-login/ or %APPDATA\Roaming\AWS Login\).

This is what a collection of profile templates looks like:

{
    "base": {
        "enabled": false,
        "settings": {
            "output": "json",
            "region": "us-east-1",
            "sso_region": "us-east-1",
            "sso_start_url": "https://my-sso-portal.awsapps.com/start"
        }
    },
    "dev-read": {
        "extends": "base",
        "settings": {
            "sso_account_id": 123456789012,
            "sso_role_name": "ReadOnly"
        }
    },
    "dev-write": {
        "extends": "dev-read",
        "settings": {
            "sso_role_name": "Developer"
        }
    }
}

The base profile template serves as the foundation for other templates to build upon. It provides some common settings such as where the SSO portal is located. Because this is not a fully configured profile, and is intended to be used by other templates, enabled is set to false so that it is not listed as an option to select from when aws-login use is run.

The dev-read profile template uses the base template by specifying it under the extends key, and adds its own SSO settings that make it ready to be used for authentication. If dev-read provided its own region, it would override the region set by the base profile.

The dev-write profile template demonstrates that your profile dependency tree can go as deep as you need. In this template, we re-use all of the settings from dev-read (and consequently, base) but override the sso_role_name we want to use.

Okay, but why?

Here is an example scenario:

You are a new hire at a company that hosts all of their services in AWS. As part of the onboarding process, you work on setting up your workstation so that you can use AWS CLI to interact with the cloud environment. Instead of asking around, searching Confluence/Sharepoint/etc, or figuring it out on your own, you install aws-login and run the pull subcommand with a URL you were provided.

You now have immediate access to various AWS accounts and services.

Downloading and installing profile templates

You may want to familiarize yourself with this first: Setting up and activating AWS CLI profiles

aws-login pull https://www.example.com/path/to/templates.json

This subcommand will download a remote profile templates file and store a copy for later use. If a local templates file already exists, you will be asked if you would like to merge with the existing file or replace it.