zsh-aws-vault

oh-my-zsh plugin for aws-vault

Installation

oh-my-zsh

This plugin is intended to be used with oh-my-zsh

1. cd ~/.oh-my-zsh/custom/plugins (you may have to create the folder)
2. git clone https://github.com/blimmer/zsh-aws-vault.git
3. In your .zshrc, add zsh-aws-vault to your oh-my-zsh plugins:

plugins=(
  zsh-aws-vault
)

zgen

1. add zgen load blimmer/zsh-aws-vault to your '!saved/save' block
2. zgen update

Upgrading

Some releases might have breaking changes to behaviors. Before upgrading, please review the Releases page to understand the changes. This package follows Semantic Versioning best-practices.

An upgrade guide for major versions is available in UPGRADING.md.

Features

This plugin provides a comprehensive set of tools for working with aws-vault:

• Aliases for common aws-vault commands:

  • av - aws-vault
  • avs - aws-vault server
  • avl - aws-vault login
  • avll - aws-vault login -s (prints the login URL to the screen without opening your browser)
  • ave - aws-vault exec

• Convenience Functions:

  • avsh - Open a new shell with AWS credentials
  • avli - Login to AWS console in your default browser with profile isolation
  • avr - Refresh in-context AWS_* environment variables
  • avp - List all configured AWS profiles with their types (IAM Keys or Roles)

avli

Login in an isolated browser profile.

ℹ️ This function is currently only supported in MacOS and Linux.

This function will create a sandboxed browser profile after getting the temporary login URL for your AWS profile. This allows opening multiple profiles simultaneously in different browser profiles. This differs from using incognito mode, which shares the same profile across all incognito windows.

Specifying a Browser

You can specify a browser to use for avli by setting the AWS_VAULT_PL_BROWSER environment variable to the appropriate browser.

In MacOS, we use the default browser set at the system level. You can override using these values:

Browser	AWS_VAULT_PL_BROWSER value (MacOS)
Firefox	org.mozilla.firefox
Firefox Developer Edition	org.mozilla.firefoxdeveloperedition
Chrome	com.google.chrome
Edge	com.microsoft.edgemac
Edge Developer Edition	com.microsoft.edgemac.dev
Brave	com.brave.Browser
Vivaldi	com.vivaldi.browser

On Linux, we use xdg-settings to find the default. You can set the AWS_VAULT_PL_BROWSER environment variable to your browser's binary (e.g., chromium or /usr/bin/chromium).

Passing Additional Browser Launch Options

You can pass arbitrary parameters when launching your browser by setting the optional AWS_VAULT_PL_BROWSER_LAUNCH_OPTS environment variable. For example, if you wanted to start new avli browser windows maximized, you can set AWS_VAULT_PL_BROWSER_LAUNCH_OPTS="--start-maximized". Refer to your browser documentation for possible options.

Reusing Sandboxed Profiles

By default, each time you run avli, a new, isolated browser profile is created. If you would like to reuse the same browser profile between calls to avli, set the AWS_VAULT_PL_PERSIST_PROFILE environment variable to true.

This allows you to install extensions/addons, create bookmarks, retain history, etc. in the sandboxed browser.

By default, the profiles are stored in ~/.config/zsh-aws-vault/avli-profiles/<browser-name>/<profile-name>. You can customize the path portion of this (~/.config/zsh-aws-vault/avli-profiles) by setting the AWS_VAULT_PL_PERSIST_PROFILE_PATH environment variable.

avsh

Create a shell for a given profile. For example, this command replaces the relevant AWS_* environment variables for the default profile in a new shell session:

avsh default

This is a powerful tool that allows only placing AWS credentials in your shell session when needed.

avr

Refresh your credentials without exiting the existing subshell. Requires aws-vault v7 or newer.

Prompt Segment

This prompt segment echos out the current aws-vault profile you're logged into. I use this for adding a segment into my custom agnoster theme.

For instance, this code:

prompt_aws_vault() {
  local vault_segment
  vault_segment="`prompt_aws_vault_segment`"
  [[ $vault_segment != '' ]] && prompt_segment cyan black "$vault_segment"
}

Produces this segment in my prompt:

The instructions to customize the prompt vary based on the theme you use. In some cases, you'll need to create a copy of the theme file and edit it to include the prompt segment. You can check out my custom agnoster theme to see how I updated the prompt.

Prompt Customization

You can customize the prompt segment behavior by overriding these variables:

Variable Name	Default	Description
AWS_VAULT_PL_CHAR	☁	The character to display when logged into an aws-vault profile
AWS_VAULT_PL_DEFAULT_PROFILE	default	Only show the character when logged into this profile, not the profile name

Multi Factor Authentication (MFA)

You can override the default MFA prompt by adding the AWS_VAULT_PL_MFA environment variable.

AWS_VAULT_PL_MFA value	Description	Example
inline	Enter your MFA token as an additional argument to the command.	avsh default 123456 avli default 123456
yubikey	Generate an MFA token from your Yubikey. See the docs for more information.	avsh default avsh default my-yubikey-profile avli default avli default my-yubikey-profile