mauth-client 4.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f27f6dad85f629877f36f460275190d895e44721
+  data.tar.gz: 8364f1553ceac1fc4597ef129f4d79519b91377e
+SHA512:
+  metadata.gz: c1aef4d031f1b021cba88e85620cca6d5678acc5362fe6aa1b145f1b42c0b820ae41dd0bc7a7823c0f183cc0b615c7f9c6ac6cadeb64570ee4be0ad004144940
+  data.tar.gz: 83d8c5ae60b118c66c795e98986ef86565ed0b07ccd3ec3aa808fb77b7faa8e17ebc6e88fbd4a14b23167336fdca85f9105e3293da87265c6cf49cc63f818bd1

data/.gitignore

@@ -0,0 +1,8 @@
+.bundle
+.yardoc
+
+/coverage
+/yardoc
+/log
+
+/Gemfile.lock

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+cache: bundler
+sudo: false
+
+rvm:
+  - 2.1.10
+  - 2.2.5
+  - 2.3.1
+
+env:
+  - MAUTH_CONFIG_YML=`pwd`/spec/config_root/config/mauth.yml
+
+script: "bundle exec rspec"

data/.yardopts

@@ -0,0 +1,4 @@
+--main README.md
+--files doc/**/*.md
+lib/**/*.rb
+--output-dir ./yardoc

data/CHANGELOG.md

@@ -0,0 +1,119 @@
+# MAuth-Client History
+
+## v4.0.1
+- Open source and publish this gem on rubygems.org, no functionality changes
+
+## v4.0.0
+- *yanked*
+
+## v3.1.4
+- Use String#bytesize method instead of Rack::Utils' one, which was removed in Rack 2.0
+
+## v3.1.3
+- Increased the default timeout when fetching keys from MAuth from 1 second to 10 seconds
+- Properly honor faraday_options: timeout in mauth.yml for faraday < 0.9
+
+## v3.1.2
+- Fixed bug in Faraday call, not to raise exception when adding authenticate information to response.
+
+## v3.1.1
+- Properly require version file. Solves exception with the Faraday middleware.
+
+## v3.1.0
+- Updated `mauth.rb.dice` template to use `MAuth::Client.default_config` method and store the config in `MAUTH_CONF` constant
+
+## v3.0.2
+- Always pass a private key to the `ensure_is_private_key` method
+
+## v3.0.1
+- Use `ensure_is_private_key` in the `mauth_key` template
+
+## v3.0.0
+- Drop support for ruby 1.x
+
+## v2.9.0
+- Add a dice template for mauth initializer
+
+## 2-8-stable
+- Added an ssl_certs_path option to support JRuby applications
+- Updated dice templates to ensure `rake config` raises an error in production env if required variables are missing.
+
+## v2.7.2
+- Added logging of mauth app_uuid of requester and requestee on each request
+
+## v2.7.0
+- Ability to pass custom headers into mauth-client and mauth-proxy
+- Upgraded to use newest version of Faraday Middleware
+- Faraday_options now only get merged to the request (previously got merged into everything)
+- Syntax highlighting in hale+json output
+
+## v2.6.4
+- Less restrictive rack versioning to allow for more consumers.
+- Allow verification even if intermediate web servers unescape URLs.
+
+## v2.6.3
+- Fixed bug where nil Rails.logger prevented a logger from being built.
+
+## v2.6.2
+- Added templates for dice_bag, now rake config:generate_all will create mauth config files when you include this gem.
+
+## v2.6.1
+- Imported documentation from Medinet into the project's doc directory
+- Add Shamus
+
+## v2.6.0
+- CLI option --no-ssl-verify disables SSL verification
+- Syntax highlighting with CodeRay colorizes request and response bodies of recognized media types
+- MAuth::Proxy class now lives in lib, in mauth/proxy, and may be used as a rack application
+- mauth-proxy executable recognizes --no-authenticate option for responses
+- MAuth::Proxy bugfix usage of REQUEST_URI; use Rack::Request#fullpath instead
+
+## v2.5.0
+- MAuth::Rack::RequestAuthenticator middleware responds with json (instead of text/plain) for inauthentic requests and requests which it is unable to authenticate
+- Added MAuth::Client.default_config method
+- Added mauth-proxy executable
+- Faraday middlewares are registered with Faraday
+- Rack middleware correctly handles Content-Length with HEAD requests
+- MAuth::Client raises MAuth::Client::ConfigurationError instead of ArgumentError or RuntimeError as appropriate
+
+## v2.4.0
+- Colorized output from the mauth-client CLI
+- Add --content-type option to CLI
+- CLI rescues and prints MAuth errors instead of them bubbling up to the interpreter
+- Improved method documentation
+- Fix default null logger on windows where /dev/null is not available
+- Improve error logging
+
+## v2.3.0
+- When authentication headers are missing, the previous message ("No x-mws-time present") is replaced by the somewhat more informative "Authentication Failed. No mAuth signature present; X-MWS-Authentication header is blank."
+- More informative help messages from mauth-client CLI
+- CLI sets a user-agent
+- Handling timeout errors is fixed (previously only handled connection errors)
+- Middleware MAuth::Rack::RequestAuthenticationFaker for testing
+- More and better specs
+
+## v2.2.0
+- Fixes an issue where requests which have a body and are not PUT or POST were not being correctly signed in rack middleware
+- Improves the CLI, adding command-line options --[no-]authenticate to decide whether to authenticate responses, and --[no-]verbose to decide whether to dump the entire request and response, or just the response body. and --help to
+  Remind you.
+- Fixes mauth-client CLI being registered as an executable in the gemspec - now it should be possible to just `bundle exec mauth-client` if you have the gem bundle installed (or just `mauth-client` if you have it installed as a regular gem, but that's less straightforward)
+- New middleware MAuth::Rack::RequestAuthenticatorNoAppStatus - same as MAuth::Rack::RequestAuthenticator, but does not authenticate /app_status. this will be the most commonly used case, so made it its own middleware.
+- Middleware responds to HEAD requests correctly in error conditions, not including a response body
+- Drops backports dependency (Ben has found some issues with this gem, and it was easier to drop the depedency entirely than figure out whether these issues affected mauth-client and if it could be fixed)
+- Fix issue with remote authentication against the currently-deployed mauth service with a request signed by a nonexistent app_uuid
+
+## v2.1.1
+- Fix an issue in a case where the rack.input is not rewound before mauth-client attempts to read it
+
+## v2.1.0
+- MAuth::Client handles the :private_key_file, so you can remove from your application the bit that does that - this bit can be deleted:
+```
+if mauth_conf['private_key_file']
+  mauth_conf['private_key'] = File.read(mauth_conf['private_key_file'])
+end
+```
+
+- Autoloads are in place so that once you require 'mauth/client', you should not need to require mauth/rack, mauth/faraday, or mauth/request_and_response.
+
+## v2.0.0
+- Rewrite combining the mauth_signer and rack-mauth gems

data/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing
+
+## General Information
+
+* Check out the latest develop 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.
+
+## Running Tests
+
+To run tests, first run `bundle install`.
+
+Next, run the tests with an appropriate mauth config file, typically this is done by passing the provided one using an environment variable:
+
+```
+MAUTH_CONFIG_YML=`pwd`/spec/config_root/config/mauth.yml bundle exec rspec
+```

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mauth-client.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2016 Medidata Solutions Worldwide
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,235 @@
+# MAuth Client
+[![Build Status](https://travis-ci.org/mdsol/mauth-client-ruby.svg)](https://travis-ci.org/mdsol/mauth-client-ruby)
+
+This gem consists of MAuth::Client, a class to manage the information needed to both sign and authenticate requests
+and responses, and middlewares for Rack and Faraday which leverage the client's capabilities.
+
+MAuth Client exists in a variety of languages (.Net, Go, R etc.), see the [implementations list](doc/implementations.md) for more info.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mauth-client'
+```
+
+And then execute:
+```
+$ bundle
+```
+
+Or install it yourself as:
+```
+$ gem install mauth-client
+```
+
+
+## Configuration
+
+MAuth is typically configured by a yaml file, [mauth.yml](doc/mauth.yml.md) - see its page for more documentation.
+This is simply loaded and passed to either middleware or directly to a MAuth::Client instance.
+See the documentation for [MAuth::Client#initialize](lib/mauth/client.rb) for more details of what it accepts. Usually you will want:
+
+```ruby
+mauth_config = MAuth::Client.default_config
+```
+
+The `.default_config` method takes a number of options to tweak its expectations regarding defaults. See the
+documentation for [MAuth::Client.default_config](lib/mauth/client.rb) for details.
+
+The `private_key` and `app_uuid` (which go in mauth.yml) enable local authentication (see section [Local Authentication](#local-authentication) below).
+They’ll only work if the `app_uuid` has been stored in MAuth with a public key corresponding to the `private_key` in mauth.yml.
+
+If you do not have an `app_uuid` and keypair registered with the mauth service, you can use mauth's remote request authentication by omitting those fields.
+MAuth-Client will make a call to MAuth for every request in order to authenticate remotely.
+Remote authentication therefore requires more time than local authentication.
+You will not be able to sign your responses without an `app_uuid` and a private key, so `MAuth::Rack::ResponseSigner` cannot be used.
+
+The `mauth_baseurl` and `mauth_api_version` are required in mauth.yml.
+These tell the MAuth Client where and how to communicate with the MAuth service.
+
+
+## Rack Middleware Usage
+
+MAuth Client provides a middleware for request authentication and response verification in mauth/rack.
+
+```ruby
+require 'mauth/rack'
+```
+
+If you are using other rack middlewares, the MAuth middleware MUST come FIRST in the stack of middlewares.
+This means it is closest to the HTTP layer, furthest from the application.
+If any other middlewares which modify the incoming request or outgoing response lie between the HTTP layer and the MAuth middleware, incoming requests will probably fail to authenticate and outgoing response signatures will be invalid (and fail when the requester tries to authenticate them).
+
+Using these middlewares in rails consists of calls to `config.middleware.use` in the appropriate place (see [the Rails Guides](http://guides.rubyonrails.org/rails_on_rack.html) for more info).
+
+Using the `MAuth::Rack::ResponseSigner` middleware is optional, but highly recommended.
+If used, this should come before the `MAuth::Rack::RequestAuthenticator` middleware.
+The ResponseSigner can be used ONLY if you have an `app_uuid` and `private_key` specified in your mauth configuration.
+
+```ruby
+config.middleware.use MAuth::Rack::ResponseSigner, mauth_config
+```
+
+Then request authentication:
+
+```ruby
+config.middleware.use MAuth::Rack::RequestAuthenticator, mauth_config
+```
+
+However, assuming you have a route `/app_status`, you probably want to skip request authentication for that.
+There is a middleware (`RequestAuthenticatorNoAppStatus`) to make that easier:
+
+```ruby
+config.middleware.use MAuth::Rack::RequestAuthenticatorNoAppStatus, mauth_config
+```
+
+You may want to configure other conditions in which to bypass MAuth authentication.
+The middleware takes an option on the `:should_authenticate_check` key, which is a ruby proc that is passed to the request's rack env and must result in a boolean.
+If the result is true(ish), the middleware will authenticate the incoming request; if false, it will not.
+The `:should_authenticate_check` parameter is OPTIONAL.
+If omitted, all incoming requests will be authenticated.
+
+Here are a few example `:should_authenticate_check` procs:
+
+```ruby
+mauth_config[:should_authenticate_check] = proc do |env|
+  env['REQUEST_METHOD'] == 'GET'
+end
+config.middleware.use MAuth::Rack::RequestAuthenticator, mauth_config
+```
+
+Above, env is a hash of request parameters; this hash is generated by Rack.
+The above proc will force the middleware to authenticate only GET requests.
+
+
+Another example:
+
+```ruby
+mauth_config[:should_authenticate_check] = proc do |env|
+  env['PATH_INFO'] == '/studies.json'
+end
+config.middleware.use MAuth::Rack::RequestAuthenticator, mauth_config
+```
+
+The above proc will force the rack middleware to authenticate only requests to the "/studies.json" path.
+To authenticate a group of related URIs, considered matching `env['PATH_INFO']` with one or more regular expressions.
+
+The configuration passed to the middlewares in the above examples (`mauth_config`) is used create a new instance of `MAuth::Client`.
+If you are managing an MAuth::Client of your own for some reason, you can pass that in on the key `:mauth_client => your_client`, and omit any other MAuth::Client configuration.
+`:should_authenticate_check` is handled by the middleware and should still be specified alongside `:mauth_client`, if you are using it.
+
+When the request authentication middleware determines that a request is inauthentic, it will not call the application and will respond with a 401 status code along with an error, expressed in JSON
+(Content-Type: application/json) with the following value:
+```
+{ "errors": { "mauth": ["Unauthorized"] } }
+```
+Successfully authenticated requests will be passed to the application, as will requests for which the `:should_authenticate_check` condition is false.
+
+If the middleware is unable to authenticate the request because MAuth is unavailable and so cannot serve public keys, it responds with a 500 status code and an error expressed in JSON with the value:
+```
+{ "errors": { "mauth": ["Could not determine request authenticity"] } }
+```
+
+## Examples
+
+Putting all this together, here are typical examples (in rails you would put that code in an initializer):
+
+```ruby
+mauth_config = MAuth::Client.default_config
+require 'mauth/rack'
+config.middleware.use MAuth::Rack::ResponseSigner, mauth_config
+config.middleware.use MAuth::Rack:: RequestAuthenticatorNoAppStatus, mauth_config
+```
+
+With `:should_authenticate_check`:
+
+```ruby
+mauth_config = MAuth::Client.default_config
+require 'mauth/rack'
+config.middleware.use MAuth::Rack::ResponseSigner, mauth_config
+# authenticate all requests which pass the some_condition_of check and aren't /app_status with MAuth
+mauth_config[:should_authenticate_check] = proc do |env|
+  some_condition_of(env)
+end
+config.middleware.use MAuth::Rack:: RequestAuthenticatorNoAppStatus, mauth_config
+```
+
+## Fake middleware
+
+For testing purposes, you may wish to use middleware which does not perform actual authentication.
+MAuth provides this, as `MAuth::Rack::RequestAuthenticationFaker`.
+Requests are still checked for the presence of an MAuth signature - this is necessary as many applications rely on the `app_uuid` identified in the signature, so it cannot be ignored entirely.
+However, the validity of the public key is not checked in the MAuth service, and the authenticity of the request is not verified by its signature.
+
+This example code may augment the above examples to disable authentication in test mode:
+
+```ruby
+require 'mauth/fake/rack'
+authenticator = Rails.env != 'test' ? MAuth::Rack::RequestAuthenticator : MAuth::Rack::RequestAuthenticationFaker
+config.middleware.use authenticator, mauth_config
+```
+
+## Faraday Middleware Usage
+
+If you are making outgoing HTTP requests using Faraday, adding MAuth Faraday middleware is much the same as adding rack middleware.
+Building your connection will look like:
+
+```ruby
+Faraday.new(some_args) do |builder|
+  builder.use MAuth::Faraday::RequestSigner, mauth_config
+  builder.use MAuth::Faraday::ResponseAuthenticator, mauth_config
+  builder.adapter Faraday.default_adapter
+end
+```
+
+The Faraday middleware MUST come LAST in the stack of middleware.
+As with the rack middleware, this means it will be right next to the HTTP adapter.
+
+Only use the `MAuth::Faraday::ResponseAuthenticator` middleware if you are expecting the service you are communicating with to sign its responses (all services which are aware of MAuth _should_ be doing this).
+
+`mauth_config` is the same as in Rack middleware, and as with the Rack middleware is used to initialize a `MAuth::Client` instance.
+Also as with the Rack middleware, you can pass in a `MAuth::Client` instance you are using yourself on the `:mauth_client` key, and omit any other configuration.
+
+Behavior is likewise similar to rack: if a `private_key` and `app_uuid` are specified, then ResponseAuthenticator will authenticate locally (see [Local Authentication](#local-authentication) below); if not, then it will go to the
+mauth service to authenticate.
+`MAuth::Faraday::RequestSigner` cannot be used without a `private_key` and `app_uuid`.
+
+If a response which does not appear to be authentic is received by the `MAuth::Faraday::ResponseAuthenticator` middleware, a `MAuth::InauthenticError` will be raised.
+
+If the MAuth service cannot be reached, and therefore the authenticity of a response cannot be verified by ResponseAuthenticator, then a `MAuth::UnableToAuthenticateError` will be raised.
+
+## Other Request and Response signing
+
+If you are not using Faraday, you will need to sign your own requests.
+
+Instantiate a `MAuth::Client` with the same configuration as the middlewares, as documented on [MAuth::Client#initialize](lib/mauth/client.rb).
+We'll call this `mauth_client`.
+
+`mauth_client` has a method `#signed_headers` which takes either a `MAuth::Request` or `MAuth::Response` object, and generates HTTP headers which can be added to the request or response to indicate authenticity.
+Create a `MAuth::Request` object from the information in your HTTP request, whatever its form:
+
+```ruby
+require 'mauth/request_and_response'
+request = MAuth::Request.new(verb: my_verb, request_url: my_request_url, body: my_body)
+```
+`mauth_client.signed_headers(request)` will then return mauth headers which you can apply to your request.
+
+## Local Authentication
+
+When doing local authentication, the mauth client will periodically fetch and cache public keys from MAuth.
+Each public key will be cached locally for 60 seconds.
+Applications which connect frequently to the app will benefit most from this caching strategy.
+When fetching public keys from MAuth, the following rules apply:
+
+1. If MAuth returns the public key for a given `app_uuid`, MAuth-Client will refresh its local cache with this new public key.
+2. If MAuth cannot find the public key for a given `app_uuid` (i.e. returns a 404 status code), MAuth-Client will remove the corresponding public key from its local cache and authentication of any message from the application with this public key will fail as a consequence.
+3. If the request to MAuth times out or MAuth returns a 500 status code, the requested public key will not be removed from local MAuth-Client cache (if it exists there in the first place).
+   The cached version will continue to be used for local authentication until MAuth::Client is able to again communicate with MAuth.
+
+## Warning
+
+During development classes are typically not cached in Rails applications.
+If this is the case, be aware that the MAuth-Client middleware object will be instantiated anew for each request;
+this will cause applications performing local authentication to fetch public keys before each request is authenticated.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'kender/tasks'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/doc/implementations.md

@@ -0,0 +1,6 @@
+# MAuth-Client implementations
+
+- .Net: [mauth-client-dotnet](https://github.com/mdsol/mauth-client-dotnet)
+- Go (golang): [go-mauth-client](https://github.com/mdsol/go-mauth-client)
+- R: [RMauthClient](https://github.com/mdsol/RMauthClient)
+- Ruby: [mauth-client-ruby](https://github.com/mdsol/mauth-client-ruby)

data/doc/mauth-client_CLI.md

@@ -0,0 +1,59 @@
+# MAuth-Client CLI Tool
+
+MAuth-Client provides a Command Line Interface (CLI) tool to make MAuth-signed requests and verify MAuth-signed responses.
+
+## Installation
+
+The MAuth-Client CLI is part of the MAuth Client gem, refer to [the README](../README.md#installation) for installation instructions.
+
+## Configuration
+
+The CLI is configured with a [mauth.yml](./mauth.yml.md) file - see its page for instructions.
+
+The MAuth-Client CLI tool looks for the configuration file in several places:
+
+- if an environment variable `MAUTH_CONFIG_YML` points to an existing file, mauth-client will use that file if it exists.
+- if you have a file `~/.mauth_config.yml` then it will use that. This is useful if you have your own mauth key.
+- if you are in a directory relative to which a config/mauth.yml exists, it will use that. This is useful if you are working in a project which uses mauth and has a key configured.
+- if you are in a directory in which a file mauth.yml exists, it will use that.
+
+mauth.yml is expected to contain, at the top level, an environment key or keys.
+mauth-client checks environment variables `RAILS_ENV` and `RACK_ENV` to determine the environment, and defaults to 'development' if none of these are set.
+
+## Usage
+
+The mauth-client executable should be available with `bundle exec`, once it has been installed in your Gemfile.
+If you installed the gem manually, you may not need to run `bundle exec`.
+
+```
+$ bundle exec mauth-client --help
+Usage: mauth-client [options] <verb> <url> [body]
+    -v, --[no-]verbose               Run verbosely - output is like curl -v (this is the default)
+    -q                               Run quietly - only outputs the response body (same as --no-verbose)
+        --[no-]authenticate          Authenticate the response received
+        --[no-]color                 Color the output (defaults to color if the output device is a TTY)
+    -t, --content-type CONTENT-TYPE  Sets the Content-Type header of the request
+    -H, --header LINE                accepts a json string of additional headers to included. IE 'cache-expirey: 10, other: value
+        --no-ssl-verify              Disables SSL verification - use cautiously!
+```
+
+Examples:
+
+```
+bundle exec mauth-client GET https://eureka-innovate.imedidata.com/v1/apis
+```
+
+```
+bundle exec mauth-client GET https://eureka-innovate.imedidata.com/v1/deployments
+```
+
+```
+bundle exec mauth-client POST https://eureka-innovate.imedidata.com/v1/deployments '{"baseURI": "https://cupcakes.imedidata.com", "stage": "production", "apis": [{"name": "cupcakes", "version": "v1.0.0"}]}'
+```
+
+## Output
+
+MAuth-Client CLI's default output is designed to look like the output of `curl -v`.
+It includes all headers, body, and other components of the http request.
+This can be suppressed with the `-q` (quiet) option, in which case only the response body will be output.
+The normal output (not the quiet version) is colorized by default if connected to a tty device (e.g. a terminal).

data/doc/mauth-proxy.md

@@ -0,0 +1,71 @@
+# mauth-proxy executable
+
+## Overview
+
+mauth-proxy is a command-line tool to forward requests to a service, signing each one with a MAuth signature and verifying responses from the service.
+
+mauth-proxy wraps a Rack server, which listens on localhost (external connections are not allowed, for security).
+mauth-proxy takes each request, signs it with a specified MAuth configuration, and makes a request to the given service.
+The response from the service is authenticated with MAuth, and is returned as the response to the original request.
+
+The intent is to allow users to point any HTTP or REST client they care to use at a service which authenticates with MAuth, without the client needing to know how to generate MAuth signatures or authenticate MAuth-signed responses.
+
+The proxy has two modes: single-target and browser proxy mode. In browser proxy mode, it can be configured as a HTTP proxy in a browser and will direct the requests to any URL in the request while signing requests to URLs that are listed in the command line.
+In single-target mode, all requests will be directed to the server specified in the command line.
+
+## Usage
+
+Single target mode:
+```
+$ bundle exec mauth-proxy -p 3452 https://eureka.imedidata.com/
+```
+
+This will launch a rack server, listening on port 3452.
+When a request is made to this server on a particular path - say `http://localhost:3452/v1/apis`, then mauth-proxy will make a mauth-signed request to `https://eureka.imedidata.com/v1/apis`, then authenticate the response and return that response to the original request.
+
+Browser proxy mode:
+```
+$ bundle exec mauth-proxy -p 3452 --browser_proxy http://localhost:3000 http://localhost:9292
+```
+
+For this mode, add localhost:3452 in your browser's proxy configuration and access the service you want to use.
+If the beginning of the requested URL matches one of the URLs you specified, it will be signed and authenticated.
+
+
+## Options
+
+The location of the mauth configuration can be specified or infered automatically, see the [MAuth-Client CLI Tool doc](./mauth-client_CLI.md#configuration) for more details.
+
+The last command-line argument MUST be a target URI to which requests will be forwarded.
+
+The `--no-authenticate` option disables response authentication from the target service.
+
+The `--browser_proxy` option switches to browser proxy mode and is intended to be used when the proxy is used in conjunction with a web browser that is set to use this proxy.
+
+The `--header` Accepts a [key]:[value] header definition to include, e.g. -h "Accept:application/json". It can be used multiple times for multiple headers.
+
+All other options are passed along to rack.
+Available options can be viewed by running rackup -h, and are also listed below:
+
+```
+Ruby options:
+  -e, --eval LINE          evaluate a LINE of code
+  -d, --debug              set debugging flags (set $DEBUG to true)
+  -w, --warn               turn warnings on for your script
+  -I, --include PATH       specify $LOAD_PATH (may be used more than once)
+  -r, --require LIBRARY    require the library, before executing your script
+
+Rack options:
+  -s, --server SERVER      serve using SERVER (webrick/mongrel)
+  -o, --host HOST          listen on HOST (default: 0.0.0.0)
+  -p, --port PORT          use PORT (default: 9292)
+  -O NAME[=VALUE],         pass VALUE to the server as option NAME. If no VALUE, sets it to true. Run 'rackup -s SERVER -h' to get a list of options for SERVER
+      --option
+  -E, --env ENVIRONMENT    use ENVIRONMENT for defaults (default: development)
+  -D, --daemonize          run daemonized in the background
+  -P, --pid FILE           file to store PID (default: rack.pid)
+
+Common options:
+  -h, -?, --help           Show this message
+      --version            Show version
+```

data/doc/mauth.yml.md

@@ -0,0 +1,73 @@
+# mauth.yml
+
+The conventional way to configure MAuth-Client for your project is through a YAML file which lives in your project at `config/mauth.yml`.
+It is keyed on environment, and for the most part its contents are passed directly to instantiate an MAuth::Client.
+See the documentation for [MAuth::Client#initialize](../lib/mauth/client.rb) for more details of what it accepts.
+
+## Generating keys
+
+To generate a private key (`mauth_key`) and its public counterpart (`mauth_key.pub`) run:
+
+```
+openssl genrsa -out mauth_key 2048
+openssl rsa -in mauth_key -pubout -out mauth_key.pub
+```
+
+## Format
+
+```yaml
+common: &common
+  mauth_baseurl: https://mauth-innovate.imedidata.com
+  mauth_api_version: v1
+  app_uuid: 123we997-0333-44d8-8fCf-5dd555c5bd51
+  private_key: |
+    -----BEGIN RSA PRIVATE KEY-----
+    AIIEowIBAAKCAQEAwLYWYcKrCAl7uWVlkwzBcBXRiRREqGYLXEnRGgDrlqbY+lDg
+    gwMNga3ylckui/rTUZhtefx1MLtxgnTGiil45eleoJgjdfsOO5yXzUA46KW0cuL4
+    ...
+    oEKe4QKBgFNbVJp3Zut83MzpN4Zu7/wZ/+q9ds9WMMxWb4hUugKQTPjsgj+8tCqa
+    SIY2exfsy7Y8NoOnBPlGiXKhgaF21T8kqV9C7R6OAuP0U6CgMJnINx/UjozvBENH
+    Ux45QdvRd6vai8nHp7AgV7rr55SxXAZVgATll84uBUpfpmC6YK/j
+    -----END RSA PRIVATE KEY-----
+
+production:
+  <<: *common
+development:
+  <<: *common
+test:
+  <<: *common
+```
+
+Optionally you can load the private key from a file:
+
+```yaml
+common: &common
+  mauth_baseurl: https://mauth-innovate.imedidata.com
+  mauth_api_version: v1
+  app_uuid: 123we997-0333-44d8-8fCf-5dd555c5bd51
+  private_key_file: config/my_mauth_private.key
+
+production:
+  <<: *common
+development:
+  <<: *common
+test:
+  <<: *common
+```
+
+## Configuration options
+
+- `private_key` - Required for signing and for authenticating responses. May be omitted if only remote authentication of requests is being performed.
+- `private_key_file` - May be used instead of `private_key`, mauth-client will load the file instead.
+- `app_uuid` - Required in the same circumstances where a `private_key` is required.
+- `mauth_baseurl` - Required for authentication but not for signing. Needed for local authentication to retrieve public keys and for remote authentication. Usually this is `https://mauth.imedidata.com` for production.
+- `mauth_api_version` - Required for authentication but not for signing. only `v1` exists as of this writing.
+
+## Usage in your application
+
+Load mauth.yml, merge in any other configuration that is needed for your usage, and pass the config along to instantiate a `MAuth::Client` or a middleware.
+See the [README](../README.md) for more detail.
+
+## Usage in MAuth-Client executables (mauth-client, mauth-proxy)
+
+See the [MAuth-Client CLI Tool doc](./mauth-client_CLI.md#configuration).

data/examples/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem 'faraday', '~> 0.9.0'
+gem 'mauth-client', path: '..'