AWS-MFA

Introduction

This is a fork of the original AWS MFA gem found here. The original repository is for a stand-alone shell script to prepare the environment to interact with AWS SDK tools. mydrive-aws-mfa is both a stand-alone shell script and can also be inserted into a ruby application to prepare the environment for a single instance. It retrieves temporary credentials for assuming an AWS role, by first obtaining an MFA token from the user.

It uses AWS STS to get temporary credentials. This is necessary if you have MFA enabled on your account. The variables it sets are:

AWS_SECRET_ACCESS_KEY
AWS_ACCESS_KEY_ID
AWS_SESSION_TOKEN
AWS_SECURITY_TOKEN

The gem can assume different roles specified by AWS profiles.

Prerequisites

Before using mydrive-aws-mfa, you must have the AWS CLI installed (through whatever method you choose) and configured (through aws configure).

General usage

Upon running the gem, the user will be prompted user for the 6-digit token from their MFA device. This will retrieve AWS MFA credentials that are valid for one hour and cache them. Within the following hour, any program using the gem can be executed without requiring the user to input their MFA token and will instead retrieve the credentials from the cache.

If user's AWS configuration is set up for different profiles, the user can change the AWS role they assume by passing in the profile as the AWS_PROFILE environment variable. By default, the role specified by the default profile will be assumed. Each profile has it's own cache, so supplying a different AWS_PROFILE will prompt the user for the 6-digit token again.

For example, in the stand alone usage, running AWS_PROFILE=production mydrive-aws-mfa aws would run the AWS cli whilst assuming the role specified by the production profile. Running mydrive-aws-mfa aws run the AWS cli but instead will assume the role specified by the default profile.

Stand alone usage

As a stand alone script, the gem can be used in three different ways.

Eval

The first is to use the gem to alter the environment of your current shell. To do this, run eval $(mydrive-aws-mfa). Now any command that uses the standard AWS environment variables should work. However, if the AWS MFA credentials have expired, the user will be unable to enter their credentials because of how $() works. So it is recommended the Eval usage be used in conjunction with the Quiet usage.

Wrapper

The second is to use the gem to alter the environment of a single invocation of a program. mydrive-aws-mfa tries to execute its arguments. mydrive-aws-mfa aws would run the aws cli, mydrive-aws-mfa kitchen would run test-kitchen, and so on. You can safely setup an alias with alias aws=mydrive-aws-mfa aws. With the alias, if you had set up autcompletion for aws it will still work.

Quiet

Passing --quiet as an argument to mydrive-aws-mfa, as mydrive-aws-mfa --quiet, will ignore the other arguments. This will still prompt the user for their MFA token, but not print the ENV to the shell.

This has been added, to be used in conjunction with the Eval usage, to ask a user for their token and set the shell environment, without printing the ENV to the shell:

mydrive-aws-mfa --quiet
eval $(mydrive-aws-mfa)

Ruby application usage

The following are the steps required to run the mydrive-aws-mfa gem inside a ruby application.

Installation

First, add the Gem into a project's Gemfile: gem "mydrive-aws-mfa" Second, add the following to a script or any code that will be ran once upon execution:

 require "aws_mfa_client"

 AwsMfaClient.new.execute

The gem will require the user to input their MFA token if it hasn't been ran in a while, so it is best to place the AwsMfaClient such that it will be ran once upon initial execution of the program.

Upon running AwsMfaClient.new.execute, the credentials are loaded into the environment for duration of that program.

Release Process

Maintainers should use the standard process below when releasing a new version. The text can be copied into a GitHub issue or PR to serve as a checklist.

- [ ] test the gem locally
  - [ ] test using the existing suite
  - [ ] test any changes in this release
- [ ] update `s.version` in `mydrive-aws-mfa.gemspec`
- [ ] build the gem locally: `gem build mydrive-aws-mfa.gemspec`
- [ ] publish to rubygems: `gem push mydrive-aws-mfa-x.x.x.gem`
- [ ] create a release on GitHub https://github.com/mydrive/mydrive-aws-mfa/releases
  - [ ] create a tag for the release