Home
Awskeyring is a small tool to manage AWS account keys in the macOS Keychain. It has grown to incorporate a lot of features.
Running the awskeyring command without arguments will display a list of commands available.
To install you will need Xcode CLI tools. This is because Ruby needs to compile native bindings to connect to the Keychain. if you don't already have Xcode install the cli tools can be installed with the following command.
$ xcode-select --install
If you are running with an ARM based (M1 Mac) you will also need to run the FFI install with an extra parameter:
$ gem install ffi --user-install -- --enable-libffi-alloc
Then to install with a binstub in your home directory add ~/bin to your PATH variable and run the following.
$ gem install awskeyring --user-install --bindir ~/bin
First step is to create your macOS Keychain to store your AWS Access Keys into.
$ awskeyring initialise
You can specify the keychain name as an argument (see help), otherwise it will prompt you and then fall back to a default of "awskeyring". The keyring is accessible in the "Keychain Access" Utility. It will also auto-lock after 5 minutes.
Next you need to add Keys to the keychain.
$ awskeyring add ACCOUNT
You can script adding keys by providing them with arguments but the interactive prompt will catch them too.
Adding roles allows you to assume roles including across account too.
$ awskeyring add-role ROLE
If you already had credentials saved to the .aws/credentials file, you can import them one at a time by name.
$ awskeyring import ACCOUNT
The basic way of using credentials is to take the output of the "env" command and use that to set your environment. A quick way is to run the following to do this in a single command.
$ eval "$(awskeyring env my-aws-account)"
This will set the environment variables allowing a variety of tools to access AWS APIs.
Alternatively you can run a single command with the environment variables set. After the command exits the environment variables will no longer exist.
$ awskeyring exec my-aws-account aws sts get-caller-identity
To assume a role, use an MFA or both you need to run the "token" command to generate a time limited token (that will be saved into the keychain until it expires) before running the "env" command.
$ awskeyring token ACCOUNT [ROLE] [CODE]
To just open up the AWS Console (web page) with your default browser simply run...
$ awskeyring console ACCOUNT
It requires permissions to run getFederationToken and getSigninToken and will try to use the session token if you have one.
For more details on a command you can ask the built in help function.
$ awskeyring help token