mydrive-aws-mfa 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6818eb4557e8103bf23574833e74ae03f5ff732a
-  data.tar.gz: 569087a1cc328f298ad6c8fd3f575b68a717135b
+  metadata.gz: 82c386664256afbd3d017a1cad7d07ceb8c659e7
+  data.tar.gz: 4b8a42f0182d40bb5a1f671dc6d17969b5bf1071
 SHA512:
-  metadata.gz: eccbac3e8b5987af89b0022aca505c907c08986f5812b160887e9ca1e9067a57fa4f07358f20c54718f852062dc549634f73b0cc7abf347a1417fa52d558810e
-  data.tar.gz: 5d3dc00f06ba04b546d1fcdb9e67d9573e7255655eb9479efc2b3562967ac613a9bcd57b7f00d872dfb34699fdc3251470e3f72f7f62a30819b1174918cf6b9f
+  metadata.gz: 8d08e64cc735ebccd6151cea768d600c091c5899cc8ad479eb5fb86b58fe3a87de3adc5eeb35063d551cf82edff83b0422301bf8a3e39a996471962bcd9f5f54
+  data.tar.gz: 12fd51ac2a8b7f3d6bb3c75b11df8d35709a223b083d9b31f3c4510192abf32a452ff9b8aa2e008d3d787276a9bc0839bef7a51956f436a7bfea1aa17fd0ad26

data/README.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-This is a fork of the original AWS MFA gem found [here](https://github.com/lonelyplanet/aws-mfa/). The original repository is for a stand-alone shell script.
-
-`mydrive-aws-mfa` can be inserted into a ruby application to prepare the environment for that single instance to interact with AWS SDK tools. It retrieves temporary credentials for assuming an AWS role, by first obtaining an MFA token from the user.
+This is a fork of the original AWS MFA gem found [here](https://github.com/lonelyplanet/aws-mfa/). 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](http://docs.aws.amazon.com/cli/latest/reference/sts/index.html) to get temporary credentials. This is necessary if you have [MFA](https://aws.amazon.com/iam/details/mfa/) enabled on your account. The variables it sets are:
 
@@ -13,11 +11,48 @@ It uses [AWS STS](http://docs.aws.amazon.com/cli/latest/reference/sts/index.html
 * 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](https://aws.amazon.com/cli/) installed (through whatever [method](http://docs.aws.amazon.com/cli/latest/userguide/installing.html) you choose) and configured (through `aws configure`).
 
-## Installation
+## 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"`
@@ -29,17 +64,7 @@ Second, add the following to a script or any code that will be ran once upon exe
  ```
 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.
 
-## Usage
-
-Upon running `AwsMfaClient.new.execute`, the gem will prompt the 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. These credentials are loaded into the environment for duration of that program.
-
-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.
-
-For example, given a program `bin/fake_program` containing `AwsMfaClient.new.execute`, running `AWS_PROFILE=production bin/fake_program` will assume the role specified by the `production` profile. Instead, running `bin/fake_program` will assume the role specified by the `default` profile.
-
-Each profile has it's own cache, so supplying a different `AWS_PROFILE` will prompt the user for the 6-digit token again.
+Upon running `AwsMfaClient.new.execute`, the credentials are loaded into the environment for duration of that program.
 
 ## Release Process
 

data/bin/mydrive-aws-mfa

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path(File.join(__dir__, '../lib')))
+
+require 'aws_mfa'
+
+def execution_output
+  if ARGV.include?('--quiet')
+    :quiet
+  elsif ARGV.empty?
+    :print_env
+  else
+    :set_env_and_execute
+  end
+end
+
+begin
+  aws_mfa = AwsMfa.new
+  aws_mfa.execute(execution_output)
+rescue AwsMfa::Errors::Error => e
+  abort e.message
+end

data/lib/aws_mfa.rb

@@ -1,6 +1,7 @@
 require 'aws-sdk-core/ini_parser'
 require 'fileutils'
 require 'json'
+require_relative 'aws_mfa/credentials_output_executor'
 require_relative 'aws_mfa/credentials_loader'
 require_relative 'aws_mfa/errors'
 require_relative 'aws_mfa/profile_config'
@@ -16,12 +17,11 @@ class AwsMfa
     @mydrive_credentials_cache_dir = set_mydrive_credentials_cache_dir
   end
 
-  def execute
+  def execute(execution_output = :set_env)
     profile = ENV['AWS_PROFILE'] || 'default'
     profile_config = load_profile_config(profile)
     credentials = load_credentials(profile_config)
-    unset_environment
-    export_credentials(credentials)
+    execute_output(execution_output, credentials)
   end
 
   private
@@ -62,17 +62,7 @@ class AwsMfa
     CredentialsLoader.new(mydrive_credentials_cache_dir).load_credentials(profile_config)
   end
 
-  def unset_environment
-    ENV.delete('AWS_SECRET_ACCESS_KEY')
-    ENV.delete('AWS_ACCESS_KEY_ID')
-    ENV.delete('AWS_SESSION_TOKEN')
-    ENV.delete('AWS_SECURITY_TOKEN')
-  end
-
-  def export_credentials(credentials)
-    ENV['AWS_SECRET_ACCESS_KEY'] = credentials['SecretAccessKey']
-    ENV['AWS_ACCESS_KEY_ID'] = credentials['AccessKeyId']
-    ENV['AWS_SESSION_TOKEN'] = credentials['SessionToken']
-    ENV['AWS_SECURITY_TOKEN'] = credentials['SessionToken']
+  def execute_output(execution_output, credentials)
+    CredentialsOutputExecutor.new.execute_output(execution_output, credentials)
   end
 end

data/lib/aws_mfa/credentials_output_executor.rb

@@ -0,0 +1,44 @@
+class CredentialsOutputExecutor
+  def execute_output(execution_output, credentials)
+    case execution_output
+    when :set_env
+      unset_environment
+      export_credentials(credentials)
+    when :quiet
+      nil
+    when :set_env_and_execute
+      unset_environment
+      export_credentials(credentials)
+      execute_command_line_arguments
+    when :print_env
+      print_credentials(credentials)
+    end
+  end
+
+  private
+
+  def unset_environment
+    ENV.delete('AWS_SECRET_ACCESS_KEY')
+    ENV.delete('AWS_ACCESS_KEY_ID')
+    ENV.delete('AWS_SESSION_TOKEN')
+    ENV.delete('AWS_SECURITY_TOKEN')
+  end
+
+  def export_credentials(credentials)
+    ENV['AWS_SECRET_ACCESS_KEY'] = credentials['SecretAccessKey']
+    ENV['AWS_ACCESS_KEY_ID'] = credentials['AccessKeyId']
+    ENV['AWS_SESSION_TOKEN'] = credentials['SessionToken']
+    ENV['AWS_SECURITY_TOKEN'] = credentials['SessionToken']
+  end
+
+  def print_credentials(credentials)
+    puts "export AWS_SECRET_ACCESS_KEY='#{credentials['SecretAccessKey']}'"
+    puts "export AWS_ACCESS_KEY_ID='#{credentials['AccessKeyId']}'"
+    puts "export AWS_SESSION_TOKEN='#{credentials['SessionToken']}'"
+    puts "export AWS_SECURITY_TOKEN='#{credentials['SessionToken']}'"
+  end
+
+  def execute_command_line_arguments
+    exec(*ARGV)
+  end
+end

data/lib/aws_mfa_client.rb

@@ -1,9 +1,9 @@
 require_relative 'aws_mfa'
 
 class AwsMfaClient
-  def execute
+  def execute(execution_output = :set_env)
     return if running_on_aws_ec2_instance?
-    AwsMfa.new.execute
+    AwsMfa.new.execute(execution_output)
   end
 
   def running_on_aws_ec2_instance?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mydrive-aws-mfa
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - MyDrive Solutions Ltd
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-27 00:00:00.000000000 Z
+date: 2017-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-core
@@ -54,14 +54,17 @@ dependencies:
         version: '0.9'
 description: A client to run AWS commands with MFA that can be added into a Ruby project
 email: support@mydrivesolutions.com
-executables: []
+executables:
+- mydrive-aws-mfa
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- bin/mydrive-aws-mfa
 - lib/aws_mfa.rb
 - lib/aws_mfa/credentials_loader.rb
+- lib/aws_mfa/credentials_output_executor.rb
 - lib/aws_mfa/errors.rb
 - lib/aws_mfa/profile_config.rb
 - lib/aws_mfa/shell_command.rb