g5_authenticatable_api 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cd9ed6f231034a1d906d81e1fc66b0787fc7596e
+  data.tar.gz: bed5680f12d4d43a28b7aff5f2b55773ce8d7dd5
+SHA512:
+  metadata.gz: f77007e0fdeb669211365aa53a19bc011ab73c1297b9a6ae23155f7cc3a798f944517cbe1e72746c50cc430be45fecb9a6a2575e2e60981d816d30bbc6ac69a6
+  data.tar.gz: 8f425de57b86817df5528822b914030892292b622c9af9382a946270d66c91752de9188bb57884e70aba10909cef315da293acf3b00d38fdd75d69246931aa01

data/.gitignore

@@ -0,0 +1,24 @@
+.DS_Store
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.env.*
+spec/dummy/db/*.sqlite3
+spec/dummy/log/*.log
+spec/dummy/tmp/
+spec/dummy/.sass-cache
+spec/dummy/config/database.yml

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+## v0.2.0 (2014-03-12)
+
+* First open source release to [RubyGems](https://rubygems.org)
+
+## v0.1.1 (2014-03-07)
+
+* Bug fix: ignore any configured resource owner password credentials during
+  token validation.
+
+## v0.1.0 (2014-02-26)
+
+* Implement Rails API helpers
+* Renamed `G5AuthenticatableApi::GrapeHelpers` to
+  `G5AuthenticatableApi::Helpers::Grape`
+
+## v0.0.1 (2014-02-20)
+
+* Initial release with Grape API helpers

data/Gemfile

@@ -0,0 +1,38 @@
+source 'https://rubygems.org'
+
+# Declare your gem's dependencies in g5_authenticatable_api.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec
+
+# Gems used by the dummy application
+gem 'rails', '~> 4.0.2'
+gem 'jquery-rails'
+gem 'pg'
+gem 'grape'
+gem 'devise'
+gem 'devise_g5_authenticatable'
+
+group :test, :development do
+  gem 'rspec-rails', '~> 2.14'
+  gem 'pry'
+end
+
+group :test do
+  gem 'capybara'
+  gem 'factory_girl_rails', '~> 4.3', require: false
+  gem 'simplecov', require: false
+  gem 'codeclimate-test-reporter', require: false
+  gem 'webmock'
+  gem 'shoulda-matchers'
+  gem 'rspec-http', require: false
+end
+
+# Declare any dependencies that are still in development here instead of in
+# your gemspec. These might include edge Rails or gems from your path or
+# Git. Remember to move these dependencies to your gemspec before releasing
+# your gem to rubygems.org.
+# gem 'g5_authentication_client', git: 'git@github.com:G5/g5_authentication_client.git', branch: 'master'
+
+# To use debugger
+# gem 'debugger'

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 maeve
+
+MIT License
+
+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,286 @@
+# G5 Authenticatable API
+
+A set of helpers for securing Rails or Grape APIs using G5 Auth.
+
+The helpers can be used in conjunction with
+[devise_g5_authenticatable](https://github.com/G5/devise_g5_authenticatable)
+to protect an API for a website, or they may be used to protect a stand-alone
+service using token-based authentication.
+
+## Current Version
+
+0.2.0
+
+## Requirements
+
+* [rails](http://rubyonrails.org/) >= 3.2
+
+**OR**
+
+* [grape](https://github.com/intridea/grape)
+
+## Installation
+
+1. Add this line to your application's Gemfile:
+
+   ```ruby
+   gem 'g5_authenticatable_api'
+   ```
+
+2. And then execute:
+
+   ```console
+   bundle
+   ```
+
+## Configuration
+
+The API helpers need to know the endpoint for the G5 auth server to use when
+validating tokens. This may be configured in one of several ways:
+
+* Set the `G5_AUTH_ENDPOINT` environment variable (typically to either
+   https://dev-auth.g5search.com or https://auth.g5search.com).
+
+**OR**
+
+* Configure the `G5AuthenticationClient` module directly, perhaps in an
+  initializer:
+
+  ```ruby
+  G5AuthenticationClient.configure do |config|
+    config.endpoint = 'https://dev-auth.g5search.com'
+  end
+  ```
+
+## Usage
+
+### Rails
+
+To require authentication for all API actions:
+
+```ruby
+class MyResourceController < ApplicationController
+  before_filter :authenticate_api_user!
+
+  respond_to :json
+
+  # ...
+end
+```
+
+To require authentication for some API actions:
+
+```ruby
+class MyResourceController < ApplicationController
+  before_filter :authenticate_api_user!, only: [:create, :update]
+
+  respond_to :json
+
+  # ...
+end
+```
+
+### Grape
+
+To require authentication for all endpoints exposed by your API:
+
+```ruby
+class MyApi < Grape::API
+  helpers G5AuthenticatableApi::Helpers::Grape
+
+  before { authenticate_user! }
+
+  # ...
+end
+```
+
+To selectively require authentication for some endpoints but not
+others:
+
+```ruby
+class MyApi < Grape::API
+  helpers G5AuthenticatableApi::Helpers::Grape
+
+  get :secure do
+    authenticate_user!
+    { secure: 'data' }
+  end
+
+  get :open do
+    { hello: 'world' }
+  end
+end
+```
+
+### Submitting a token
+
+Authenticated requests follow the requirements described by
+[OAuth 2.0 Bearer Token specification](http://tools.ietf.org/html/rfc6750#section-2).
+If you are relying on token-based authentication for your API, there are three
+ways that an OAuth access token may be submitted as part of a request:
+
+* In the `Authorization` HTTP header, with the format "Bearer \<access_token\>"
+
+  ```http
+  GET /resource HTTP/1.1
+  Host: server.example.com
+  Authorization: Bearer mF_9.B5f-4.1JqM
+  ```
+
+* As the value of the `access_token` form-encoded body parameter:
+
+  ```http
+  POST /resource HTTP/1.1
+  Host: server.example.com
+  Content-Type: application/x-www-form-urlencoded
+
+  access_token=mF_9.B5f-4.1JqM
+  ```
+
+* As the value of the `access_token` query URI parameter:
+
+  ```http
+  GET /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1
+  Host: server.example.com
+  ```
+
+### Unauthorized response
+
+If there is no logged in user and token authentication fails, secure API methods
+will return a response with an HTTP status of 401. More detailed information will
+be available in the `WWW-Authenticate` response header, as described in the
+[OAuth 2.0 Bearer Token specification](http://tools.ietf.org/html/rfc6750#section-3).
+
+In brief, `WWW-Authenticate` header will contain one of the following error codes
+when token validation fails against G5 Auth:
+
+* `invalid_request` (the default)
+* `invalid_token`
+* `insufficent_scope`
+
+The header may also have an error description if one is available. For
+example:
+
+```http
+HTTP/1.1 401 Unauthorized
+     WWW-Authenticate: Bearer realm="example",
+                       error="invalid_token",
+                       error_description="The access token expired"
+```
+
+## Examples
+
+### Securing an Ember application backed by a Grape API
+
+Use devise to protect the controller action that serves your ember
+application:
+
+```ruby
+class WelcomeController < ApplicationController
+  before_filter :authenticate_user!
+
+  def index
+  end
+end
+```
+
+Then protect the API that ember talks to:
+
+```ruby
+class MyApi < Grape::API
+  helpers G5AuthenticatableApi::Helpers::Grape
+
+  before { authenticate_user! }
+
+  # Your API endpoints ...
+end
+```
+
+That's it! No client-side changes are necessary.
+
+### Token-based authentication for a Rails API
+
+Protect your API actions in your controller:
+
+```ruby
+class Api::MyResourcesController < ApplicationController
+  before_filter :authenticate_api_user!
+
+  respond_to :json
+
+  def show
+    # ...
+  end
+end
+```
+
+To include the token in the authorization header:
+
+```console
+curl --header "Authorization: Bearer this-is-where-my-token-goes" https://myhost/api/my_resources/42
+```
+
+To include the token as a param:
+
+```console
+curl https://myhost/api/my_resources/42?access_token=this-is-where-my-token-goes
+```
+
+## Authors
+
+* Maeve Revels / [@maeve](https://github.com/maeve)
+* Rob Revels / [@sleverbor](https://github.com/sleverbor)
+
+## Contributing
+
+1. [Fork it](https://github.com/G5/g5_authenticatable_api/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Write your code and **specs**
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create a new Pull Request
+
+If you find bugs, have feature requests or questions, please
+[file an issue](https://github.com/G5/g5_authenticatable_api/issues).
+
+### Specs
+
+Before running the specs for the first time, you will need to initialize the
+database for the test Rails application.
+
+```console
+$ cp spec/dummy/config/database.yml.sample spec/dummy/config/database.yml
+$ (cd spec/dummy; RAILS_ENV=test bundle exec rake db:setup)
+```
+
+To execute the entire test suite:
+
+```console
+$ bundle exec rspec spec
+```
+
+## License
+
+Copyright (c) 2014 G5
+
+MIT License
+
+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/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/circle.yml

@@ -0,0 +1,4 @@
+database:
+  override:
+    - cp spec/dummy/config/database.yml.ci spec/dummy/config/database.yml
+    - (cd spec/dummy; RAILS_ENV=test rake db:drop db:setup)

data/g5_authenticatable_api.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'g5_authenticatable_api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'g5_authenticatable_api'
+  spec.version       = G5AuthenticatableApi::VERSION
+  spec.authors       = ['Maeve Revels']
+  spec.email         = ['maeve.revels@getg5.com']
+  spec.summary       = 'Helpers for securing APIs with G5'
+  spec.description   = 'Helpers for securing APIs with G5'
+  spec.homepage      = 'https://github.com/G5/g5_authenticatable_api'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'rack'
+  spec.add_dependency 'g5_authentication_client', '~> 0.2'
+end

data/lib/g5_authenticatable_api/helpers/grape.rb

@@ -0,0 +1,27 @@
+require 'g5_authenticatable_api/token_validator'
+
+module G5AuthenticatableApi
+  module Helpers
+    module Grape
+      def authenticate_user!
+        raise_auth_error if !(warden.try(:authenticated?) || token_validator.valid?)
+      end
+
+      def warden
+        env['warden']
+      end
+
+      private
+      def token_validator
+        request = Rack::Request.new(env)
+        @token_validator ||= TokenValidator.new(request.params, headers)
+      end
+
+      def raise_auth_error
+        throw :error, message: 'Unauthorized',
+                      status: 401,
+                      headers: {'WWW-Authenticate' => token_validator.auth_response_header}
+      end
+    end
+  end
+end

data/lib/g5_authenticatable_api/helpers/rails.rb

@@ -0,0 +1,26 @@
+require 'g5_authenticatable_api/token_validator'
+
+module G5AuthenticatableApi
+  module Helpers
+    module Rails
+      def authenticate_api_user!
+        raise_auth_error if !(warden.try(:authenticated?) || token_validator.valid?)
+      end
+
+      def warden
+        request.env['warden']
+      end
+
+      private
+      def token_validator
+        @token_validator ||= TokenValidator.new(request.params, request.headers)
+      end
+
+      def raise_auth_error
+        response.headers['WWW-Authenticate'] = token_validator.auth_response_header
+        render json: {error: 'Unauthorized'},
+               status: :unauthorized
+      end
+    end
+  end
+end

data/lib/g5_authenticatable_api/railtie.rb

@@ -0,0 +1,11 @@
+require 'g5_authenticatable_api/helpers/rails'
+
+module G5AuthenticatableApi
+  class Railtie < Rails::Railtie
+    initializer 'g5_authenticatable.helpers' do
+      ActiveSupport.on_load(:action_controller) do
+        include G5AuthenticatableApi::Helpers::Rails
+      end
+    end
+  end
+end

data/lib/g5_authenticatable_api/token_validator.rb

@@ -0,0 +1,65 @@
+module G5AuthenticatableApi
+  class TokenValidator
+    attr_reader :error
+
+    def initialize(params={},headers={})
+      @params = params || {}
+      @headers = headers || {}
+    end
+
+    def validate!
+      begin
+        auth_client.token_info
+      rescue StandardError => @error
+        raise error
+      end
+    end
+
+    def valid?
+      begin
+        validate!
+        true
+      rescue StandardError => e
+        false
+      end
+    end
+
+    def access_token
+      @access_token ||= if @headers['Authorization']
+        parts = @headers['Authorization'].match(/Bearer (?<access_token>\S+)/)
+        parts['access_token']
+      else
+        @params['access_token']
+      end
+    end
+
+    def auth_response_header
+      if error
+        auth_header = "Bearer"
+
+        if access_token
+          auth_header << " error=\"#{error_code}\""
+          auth_header << ",error_description=\"#{error_description}\"" if error_description
+        end
+
+        auth_header
+      end
+    end
+
+    def auth_client
+      @auth_client ||= G5AuthenticationClient::Client.new(allow_password_credentials: 'false',
+                                                          access_token: access_token)
+    end
+
+    private
+    def error_code
+      error_code = error.code if error.respond_to?(:code)
+      error_code || 'invalid_request'
+    end
+
+    def error_description
+      error_description = error.description if error.respond_to?(:description)
+      error_description
+    end
+  end
+end

data/lib/g5_authenticatable_api/version.rb

@@ -0,0 +1,3 @@
+module G5AuthenticatableApi
+  VERSION = '0.2.0'
+end

data/lib/g5_authenticatable_api.rb

@@ -0,0 +1,9 @@
+require 'g5_authenticatable_api/version'
+require 'g5_authenticatable_api/helpers/grape'
+require 'g5_authenticatable_api/railtie' if defined?(Rails)
+
+require 'g5_authentication_client'
+
+module G5AuthenticatableApi
+  # Your code goes here...
+end

data/spec/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.

data/spec/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/spec/dummy/app/api/hello_api.rb

@@ -0,0 +1,13 @@
+class HelloAPI < Grape::API
+  helpers G5AuthenticatableApi::Helpers::Grape
+
+  before { authenticate_user! }
+
+  get :hello do
+    { hello: 'get world' }
+  end
+
+  post :hello do
+    { hello: 'post world' }
+  end
+end

data/spec/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,16 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require jquery
+//= require jquery_ujs
+//= require turbolinks
+//= require_tree .

data/spec/dummy/app/assets/javascripts/articles.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/spec/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/spec/dummy/app/assets/stylesheets/articles.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/spec/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,5 @@
+class ApplicationController < ActionController::Base
+  # Prevent CSRF attacks by raising an exception.
+  # For APIs, you may want to use :null_session instead.
+  protect_from_forgery with: :exception
+end