lambda_vault_auth 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b709606a9982fe1e6f8248acbb72436217e231f3d20bd6f808f963faf366a472
+  data.tar.gz: a1d035fc195ee1a0c62ea2e901687b71c954c013053f8199e7ecc73a985d6cd4
+SHA512:
+  metadata.gz: bd519447ef2828f5720af18996a84dd7a9365c64c20168b2220f2cfcc31d7f072df196581c9e37daa007e0ad8277a0419288b82750e28b1cbbeb15c1f7366c8b
+  data.tar.gz: bf6e89e32c382c60b6b216ba5d31901af1043c757ed99e1233bc2728a50061a8a87148c51043128f3f6d34fa083e8e6800a85533b413b51196d4177096a87fa0

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in lambda_vault_auth.gemspec
+gemspec
+
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"

data/LICENSE

@@ -0,0 +1,13 @@
+This work is dedicated to the public domain. No rights reserved.
+
+I, the copyright holder of this work, hereby release it into the public
+domain. This applies worldwide.
+
+I grant any entity the right to use this work for any purpose, without
+any conditions, unless such conditions are required by law.
+
+If you require a fuller legal statement, please refer to the Creative
+Commons Zero license:
+
+http://creativecommons.org/publicdomain/zero/1.0/
+

data/README.md

@@ -0,0 +1,99 @@
+# lambda_vault_auth
+
+`lambda_vault_auth` provides a streamlined way to authenticate your Ruby AWS Lambda
+function to [Hashicorp Vault](https://www.vaultproject.io).
+
+## Usage Example
+
+```ruby
+    require 'lambda_vault_auth'
+
+    def handler(context:, event:)
+      vault = LambdaVaultAuth.vault()
+
+      secrets := vault.logical.read('secrets/are/found/here')
+      puts "Your password is: '#{secrets.data[:password]}'"
+    end
+```
+
+
+## Setup
+
+First, you'll need Vault up and running somewhere network-accessible to your
+Lambda function. That's out of scope for this README, but please see the
+[Vault documentation](https://www.vaultproject.io/docs/install/index.html)
+for more.
+
+Then you'll need to set up an AWS authentication provider. You may already have
+one configured. If so, you can use that one or you can set up a new one just for
+this purpose. You don't need to worry about backend credentials for this
+authentication method. It works without any AWS credentials needing to be loaded
+into Vault. Or if you do have credentials loaded they don't need to have access
+to the AWS account your Lambda is running in.
+
+To establish a new AWS authentication provider, run:
+
+    $ vault auth enable -path lambda -description "IAM auth for Lambdas" aws
+    Success! Enabled aws auth method at: lambda/
+
+You will also need to set the `iam_server_id_header_value` if you wish to use
+the extra layer of security (as described below):
+
+    $ vault write auth/lambda/config/client \
+          iam_server_id_header_value=vault.example.com
+
+Next, you'll need to establish whatever Vault policies your Lambda will need.
+See the [Vault Policies](https://www.vaultproject.io/docs/concepts/policies.html)
+documentation for details.
+
+Now you'll need to know the ARN of your Lambda execution role. You can create it
+with the Lambda web console or by hand. Either way it should look something like:
+
+    arn:aws:iam::987654321098:role/service-role/MyLambdaRole
+
+*IMPORTANT*: You must remove any non-essential path from the role ARN unless you
+have configured your AWS auth provider with IAM permissions to look up roles. In
+this example, `service-role/` is the path segment. So the principal ARN you will
+be specifying to Vault in the next step will be:
+
+    arn:aws:iam::987654321098:role/MyLambdaRole
+
+Now it's time to create the Vault authentication role. It can be named anything
+you wish. In this case, we'll call it `my-vault-role` and make it periodic since
+`lambda_vault_auth` will handle renewal automatically:
+
+    $ vault write auth/lambda/role/my-vault-role \
+          auth_type=iam \
+          period=14400 \
+          policies=list-of,vault-policies,separated-by-commas \
+          resolve_aws_unique_ids=false \
+          bound_iam_principal_arn=arn:aws:iam::987654321098:role/MyLambdaRole
+
+Now you are ready to configure your Lambda.
+
+## Configuration
+
+All configuration is done with environment variables:
+
+* `VAULT_ADDR` (Required) The URL of the Vault instance, eg `https://myvault.example.com`.
+* `VAULT_AUTH_PROVIDER` (Required) The relative path of the AWS authentication provider, eg `lambda` for `auth/lambda` in the example above.
+* `VAULT_AUTH_ROLE` (Required) The name of the Vault role to authenticate to, eg `my-vault-role` in the example above.
+* `VAULT_AUTH_HEADER` (Optional, but recommended) The value of the `X-Vault-AWS-IAM-Server-ID` HTTP header to be included in the signed STS request this code uses to authenticate. This value is often set to the URL or DNS name of the Vault server to prevent potential replay attacks.
+
+That should be all that is required to get up and running.
+
+## Contributing to lambda_vault_auth
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+
+## License
+
+This software is public domain. No rights are reserved. See LICENSE for more
+information.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = Dir.glob('spec/**/*_spec.rb')
+  t.rspec_opts = '--format documentation'
+end
+
+task default: :spec

data/VERSION

@@ -0,0 +1 @@
+0.0.0

data/lib/lambda_vault_auth.rb

@@ -0,0 +1,107 @@
+require 'aws-sdk-core'
+require 'vault'
+
+# TODO: support the advanced vault header in the signature, since it gives us better security
+# VAULT_AUTH_HEADER_NAME = "X-Vault-AWS-IAM-Server-ID".freeze
+
+# LambdaVaultAuth
+class LambdaVaultAuth
+  # Internal class for Vault interactions
+  class Vaulter
+    attr_reader :auth_provider,
+                :auth_role,
+                :auth_token,
+                :client,
+                :expiration,
+                :expiration_window,
+                :renewal_window,
+                :ttl
+
+    def initialize(sts = Aws::STS::Client.new, env = ENV)
+      @sts = sts
+      @client = new_client_from_environment(env)
+
+      # TODO: Make the following configurable
+      # Lifecycle of each token
+      @expiration_window = 10 # seconds
+
+      # should be at least the length of the lambda runtime
+      @renewal_window = 300 # seconds
+    end
+
+    def expired?
+      expiration.nil? ? true : expiration > Time.now + expiration_window
+    end
+
+    def should_renew?
+      expiration.nil? ? true : Time.now + renewal_window > expiration
+    end
+
+    def renewable?
+      auth_token&.renewable
+    end
+
+    def renew!
+      handle_token(auth_token.renew_self(ttl))
+    end
+
+    def new_client_from_environment(env)
+      addr = env.fetch('VAULT_ADDR')
+      # @auth_header = env.fetch('VAULT_AUTH_HEADER')
+      @auth_provider = env.fetch('VAULT_AUTH_PROVIDER')
+      @auth_role = env.fetch('VAULT_AUTH_ROLE')
+
+      Vault::Client.new(
+        address: addr
+      )
+    end
+
+    def authenticate!
+      req = @sts.get_caller_identity.context.http_request
+
+      data = {
+        'iam_http_request_method': req.http_method,
+        'iam_request_body': Base64.strict_encode64(req.body.read),
+        'iam_request_headers': Base64.strict_encode64(req.headers.to_h.to_json),
+        'iam_request_url': Base64.strict_encode64(req.endpoint.to_s),
+        'role': @auth_role
+      }
+
+      secret = client.logical.write("auth/#{@auth_provider}/login", data)
+
+      warn secret.warnings unless secret.warnings.empty?
+
+      handle_token(secret)
+
+      # create the required data to renew/validate
+      # populate the token on the client and hand that to the user
+    end
+
+    def handle_token(secret)
+      @auth_token = secret.auth
+      @ttl = secret.lease_duration
+      @expiration = Time.now + ttl
+      @client.token = @auth_token.client_token
+    end
+  end
+
+  # LambdaVaultAuth.vault returns a wrapped vault which contains a few convenience accessors/helpers
+  # to help manage the lifecycle of a vault and access the credentials
+  def self.vault
+    @vault ||= Vaulter.new
+    @sts ||= Aws::STS::Client.new
+
+    return @vault.client unless @vault.expired?
+
+    if @vault.renewable? && @vault.should_renew?
+      @vault.renew!
+      return @vault.client
+    end
+
+    # Otherwise, authenticate
+    @vault.authenticate!
+
+    # return the vault client directly
+    @vault.client
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: lambda_vault_auth
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Ryan Taylor
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: vault
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+description: A library for authenticating a lambda function against Hashicorp Vault
+  via AWS as an authentication provider.
+email: rtaylor@instructure.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- lib/lambda_vault_auth.rb
+homepage: http://github.com/instructure/lambda_vault_auth
+licenses:
+- CC0-1.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Simplify authentication between an AWS lambda function and Hashicorp Vault
+  via the AWS authentication provider.
+test_files: []