Skip to content
/ gcreds Public

Automated generation and management of Amazon STS temporary IAM credentials

License

Notifications You must be signed in to change notification settings

fstab50/gcreds

Repository files navigation


gcreds


Summary

gcreds (pronounced "gee-creds" for generate credentials) is a utility for creation and managment of IAM temporary access credentials using Amazon's Security Token Service (STS). Temporary credentials are used to access AWS resources when assuming a role identity.

For more information on the above terms and functions, see an explanation of IAM roles in the Amazon Web Services documentation.

Version: 2.4.6


Contents

--

back to the top


Purpose

gcreds requests temporary credentials from Amazon's Security Token Service (STS) for roles that normally require multi-factor credentials in order to authenticate.

A primary use case for gcreds is generating a temporary set of AWS access credentials for programmatic use by automation tools running on your local machine.

gcreds manages temporary credentials it generates to prevent corruption of your local awscli config. When generating new temporary credentials, gcreds will automatically clear expired credentials from your local awscli config to block the presence of duplicate sets of credentials.

Previous Releases

--

back to the top


Dependencies

gcreds requires the following:

  • Python version 3.6+
  • Installation Amazon CLI tools (awscli, see Installation section)
  • jq, a json parser generally available from your distribution repo
  • bash (4.x)
  • Standard linux utilities:
    • grep
    • awk
    • sed
    • cat
    • hostname

--

back to the top


Program Options

To display the gcreds help menu:

    $ gcreds --help

--

back to the top


Build options

GNU Make Targets. Type the following to display the available make targets from the root of the project:

    $  make help

--

back to the top


Configuration

Configure gcreds runtime options by entering the configuration menu:

    $ gcreds --configure

cinfugyre2 

--

If the same IAM user will be utilised to generate role credentials, set the default gcreds IAM user here to avoid entering "--profile " every time gcreds is called to generate credentials for your local awscli configuration:

option a

--

Choose a default color scheme for gcreds accent highlighting via the next menu:

configure3 

--

configure4

--

back to the top


Installation


Ubuntu, Linux Mint, Debian variants (Python 3.6+)

The easiest way to install gcreds on debian-based Linux distributions is via the debian-tools package repository:

  1. Open a command line terminal.

    deb-install0

  2. Download and install the repository definition file

    $ sudo apt install wget
    
    $ wget http://awscloud.center/deb/debian-tools.list
    

    deb-install1

    $ sudo chown 0:0 debian-tools.list && sudo mv debian-tools.list /etc/apt/sources.list.d/
    
  3. Install the package repository public key on your local machine

    $ wget -qO - http://awscloud.center/keys/public.key | sudo apt-key add -
    

    deb-install2

  4. Update the local package repository cache

    $ sudo apt update
    
  5. Install gcreds os package

    $ sudo apt install gcreds
    

    Answer "y":

    deb-install3

  6. Verify Installation

    $ apt show gcreds
    

    apt-show

back to the top


Redhat, CentOS (Python 3.6+)

The easiest way to install gcreds on redhat-based Linux distributions is via the developer-tools package repository:

  1. Open a command line terminal.

    rpm-install0

  2. Install the official epel package repository

    $ sudo yum install epel-release
    
  3. Download and install the repo definition file

    $ sudo yum install wget
    

    rpm-install1

    $ wget http://awscloud.center/rpm/developer-tools.repo
    

    rpm-install2

    $ sudo chown 0:0 developer-tools.repo && sudo mv developer-tools.repo /etc/yum.repos.d/
    

    rpm-install2b

  4. Delete the local repository cache, then Update the cache with new package references

    $ sudo rm -fr /var/cache/yum
    $ sudo yum update -y
    
  5. Install the gcreds os package

    $ sudo yum install gcreds
    

    rpm-install3

    Answer "y":

    rpm-install4

  6. Verify Installation

    $ yum info gcreds
    

    rpm-install5

back to the top


Amazon Linux 2 / Fedora (Python 3.7+)

Redhat Package Manager (RPM) format used by Amazon Linux under development. Check amzn2.awscloud.center page for updates.

--

back to the top


Generating STS Credentials

Output when generating credentials

    $ gcreds --profile <iam_user> --accounts list.accounts --refresh-hours 4

Modifications to local awscli configuration (account ids have been obscured):

    $ less ./aws/credentials

Example Use of profiles created by greds:

Log File

Coloration courtesy of source-highlight.

    $ cat /var/log/gcreds.log


Auto Refresh Mode

Automatic regeneration of temporary credentials

    $ gcreds --profile <iam_user> --accounts list.accounts --refresh-hours 4

Output during generation of credentials:

Authentication Status

Runtime statistics displayed while authenitcation is active. Alternatively, the command below displays same information anytime.

    $ gcreds  --show

back to the top


Screenshots

Green Accent Scheme

    $ gcreds  --help

back to the top


Blue Accent Scheme (green terminal)

back to the top


Author & Copyright

All works contained herein copyrighted via below author unless work is explicitly noted by an alternate author.

  • Copyright Blake Huber, All Rights Reserved.

back to the top


License

  • Software contained in this repo is licensed under the license agreement. You may display the license and copyright information by issuing the following command:
$ gcreds --version

help

back to the top


Disclaimer

Code is provided "as is". No liability is assumed by either the code's originating author nor this repo's owner for their use at AWS or any other facility. Furthermore, running function code at AWS may incur monetary charges; in some cases, charges may be substantial. Charges are the sole responsibility of the account holder executing code obtained from this library.

Additional terms may be found in the complete license agreement.

back to the top