g5_authenticatable 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7a62091f31bef8d7d3b0dbd2b57aa2e3dc627ebc
+  data.tar.gz: e74855a8c9bf2e5e89edf97d40cb4d11ba004427
+SHA512:
+  metadata.gz: b815696a057a7e20ff3a0d6e67fe831ac69c8f17663a8419039b501e76da81fef1ab7cd3122fdbbe6166504f46ad943df072be16ed89d80945a24a908c568194
+  data.tar.gz: 077e3c67efa60753a0333cb6a749c0e7066a07605737a9148af854a819a532781a32effc1f7f9c51ee81920fef946136552e1765a84845d36bc6854d3d4837ef

data/.env

@@ -0,0 +1 @@
+DEVISE_SECRET_KEY='generate-this-value-using-rake-secret'

data/.gitignore

@@ -0,0 +1,25 @@
+.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
+log/*.log
+spec/dummy/db/*.sqlite3
+spec/dummy/log/*.log
+spec/dummy/tmp/
+spec/dummy/.sass-cache
+spec/dummy/config/database.yml
+.env.*

data/.rspec

@@ -0,0 +1 @@
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.1.0

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+## v0.3.0 (2014-03-13)
+
+* First open source release to [RubyGems](https://rubygems.org)
+
+## v0.2.0 (2014-03-11)
+
+* Controller test helpers
+
+## v0.1.4 (2014-03-07)
+
+* Update dependency on [g5_authenticatable_api](https://github.com/G5/g5_authenticatable_api)
+  for bug fix to ignore password credential configuration during token validation.
+
+## v0.1.3 (2014-03-06)
+
+* Remove auth client defaults in favor of env variables
+
+## v0.1.2 (2014-03-05)
+
+* Set G5_AUTH_USERNAME and G5_AUTH_PASSWORD on auth client defaults
+
+## v0.1.0 (2014-02-26)
+
+* Update dependency on [g5_authenticatable_api](https://github.com/G5/g5_authenticatable_api)
+  to include new Rails API helpers.
+* Fix shared test helpers for client applications that do not mixin the FactoryGirl syntax methods
+  in their RSpec config.
+
+## v0.0.4 (2014-02-20)
+
+* Integrate [g5_authenticatable_api](https://github.com/G5/g5_authenticatable_api)
+  for securing API methods.
+
+## v0.0.3 (2014-02-13)
+
+* Test helpers and shared context for integration tests in client applications.
+
+## v0.0.2 (2014-02-10)
+
+* Bump version for [devise_g5_authenticatable](https://github.com/G5/devise_g5_authenticatable)
+  to pick up PostgreSQL fix.
+
+## v0.0.1 (2014-02-07)
+
+* Initial release

data/Gemfile

@@ -0,0 +1,37 @@
+source 'https://rubygems.org'
+
+# Declare your gem's dependencies in g5_authenticatable.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'
+
+group :test, :development do
+  gem 'rspec-rails', '~> 2.14'
+  gem 'pry'
+  gem 'dotenv-rails'
+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 'generator_spec'
+  gem 'rspec-http', require: 'rspec/http'
+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.
+
+# To use debugger
+# gem 'debugger'

data/LICENSE

@@ -0,0 +1,22 @@
+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/README.md

@@ -0,0 +1,519 @@
+# G5 Authenticatable
+
+G5 Authenticatable provides a default authentication solution for G5
+Rails applications. This gem configures and mounts 
+[Devise](https://github.com/plataformatec/devise) with a default User
+model, using [OmniAuth](https://github.com/intridea/omniauth) to authenticate
+to the G5 Auth server. Helpers are also provided to secure your API methods.
+
+If you are already using Devise with your own model, this is not the
+library you are looking for. Consider using the
+[devise_g5_authenticatable](https://github.com/G5/devise_g5_authenticatable)
+extension directly.
+
+If you have a stand-alone service without a UI, you may not need Devise at
+all. Consider using the
+[g5_authenticatable_api](https://github.com/G5/g5_authenticatable_api)
+library in isolation.
+
+## Current Version
+
+0.3.0
+
+## Requirements
+
+* [rails](https://github.com/rails/rails) >= 3.2
+
+## Installation
+
+1. Set the environment variable `DEVISE_SECRET_KEY` to the value
+   generated by:
+
+   ```console
+   rake secret
+   ```
+
+2. Add this line to your application's Gemfile:
+
+   ```ruby
+   gem 'g5_authenticatable'
+   ```
+
+3. And then execute:
+
+   ```console
+   bundle
+   ```
+
+4. Run the generator:
+
+   ```console
+   rails g g5_authenticatable:install
+   ```
+
+   This creates a migration for the new g5_authenticatable_users
+   table, and mounts the engine at `/g5_auth`.
+
+5. Update your database:
+
+   ```console
+   rake db:migrate db:test:prepare
+   ```
+
+## Configuration
+
+### Root route
+
+Devise requires you to define a root route in your application's
+`config/routes.rb`. For example:
+
+```ruby
+root :to => 'home#index'
+```
+
+### Registering your OAuth application
+
+1. Visit the auth server admin console and login:
+  * For development, visit https://dev-auth.g5search.com/admin
+  * For production, visit https://auth.g5search.com/admin
+2. Click "New Application"
+3. Enter a name that recognizably identifies your application.
+4. Enter the redirect URI where the auth server should redirect
+   after the user successfully authenticates. It will be
+   of the form `http://<your_host>/g5_auth/users/auth/g5/callback`.
+
+   For non-production environments, this redirect URI does not have to
+   be publicly accessible, but it must be accessible from the browser
+   where you will be testing (so using something like
+   http://localhost:3000/users/auth/g5/callback is fine if your browser
+   and client application server are both local).
+
+   If you are using the production G5 Auth server, the redirect URI **MUST**
+   use HTTPS.
+5. For a trusted G5 application, check the "Auto-authorize?" checkbox. This
+   skips the OAuth authorization step where the user is prompted to explicitly
+   authorize the client application to access the user's data.
+6. Click "Submit" to obtain the client application's credentials.
+
+### Environment variables
+
+Once you have your OAuth 2.0 credentials, you'll need to set the following
+environment variables for your client application:
+
+* `G5_AUTH_CLIENT_ID` - the OAuth 2.0 application ID from the auth server
+* `G5_AUTH_CLIENT_SECRET` - the OAuth 2.0 application secret from the auth server
+* `G5_AUTH_REDIRECT_URI` - the OAuth 2.0 redirect URI registered with the auth server
+* `G5_AUTH_ENDPOINT` - the endpoint URL for the G5 auth server
+
+You can also set up a default user's credentials with:
+
+* `G5_AUTH_USERNAME` - the G5 auth server user name
+* `G5_AUTH_PASSWORD` - the G5 auth server user's password
+
+## Usage
+
+### Controller filters and helpers
+
+G5 Authenticatable installs all of the usual devise controllers and helpers.
+To set up a controller that requires authentication, use this before_filter:
+
+```ruby
+before_filter :authenticate_user!
+```
+
+To verify if a user is signed in, use the following helper:
+
+```ruby
+user_signed_in?
+```
+
+To access the model instance for the currently signed-in user:
+
+```ruby
+current_user
+```
+
+To access scoped session storage:
+
+```ruby
+user_session
+```
+
+### Route helpers
+
+There are several generic helper methods for session and omniauth
+URLs. To sign in:
+
+```ruby
+new_session_path(:user)
+```
+
+To sign out:
+
+```ruby
+destroy_session_path(:user)
+```
+
+There are also generic helpers for the OmniAuth paths, though you
+are unlikely to ever use these directly. The OmniAuth entry point
+is mounted at:
+
+```ruby
+g5_authorize_path(:user)
+```
+
+And the OmniAuth callback is:
+
+```ruby
+g5_callback_path(:user)
+```
+
+You may be more familiar with Devise's generated scoped URL helpers.
+These are still available, but are isolated to the engine's namespace.
+For example:
+
+```ruby
+g5_authenticatable.new_user_session_path
+g5_authenticatable.destroy_user_session_path
+```
+
+### Access token ###
+
+When a user authenticates, their OAuth access token will be stored on
+the local user:
+
+```ruby
+current_user.g5_access_token
+```
+
+This is to support server-to-server API calls with G5 services that are
+protected by OAuth.
+
+### Securing an API ###
+
+#### Grape ####
+
+If you include `G5AuthenticatableApi::Helpers::Grape`, you can use the
+`authenticate_user!` method to protect your API actions:
+
+```ruby
+class MyApi < Grape::API
+  helpers G5AuthenticatableApi::GrapeHelpers
+
+  before { authenticate_user! }
+
+  # ...
+end
+```
+
+#### Rails ####
+
+You can secure API actions that respond to json using the `authenticate_api_user!`
+method:
+
+```ruby
+class MyResourcesController < ApplicationController
+  respond_to :json
+
+  before_filter :authenticate_api_user!
+
+  def get
+    @resource = MyResource.find(params[:id])
+    respond_with(@resource)
+  end
+end
+```
+
+#### Secure Clients ####
+
+If you have an ember application, no client-side changes are necessary to use a
+secure API method, as long as the action that serves your ember app requires
+users to authenticate with G5 via devise.
+
+Any non-browser clients must use token-based authentication. In contexts where
+a valid OAuth 2.0 access token is not already available, you may request a new
+token from the G5 Auth server using
+[g5_authentication_client](https://github.com/G5/g5_authentication_client).
+Clients may pass the token to secure API actions either in the HTTP
+Authorization header, or in a request parameter named `access_token`.
+
+For more details, see the documentation for
+[g5_authenticatable_api](https://github.com/G5/g5_authenticatable_api).
+
+### Test Helpers ###
+
+G5 Authenticatable currently only supports [rspec-rails](https://github.com/rspec/rspec-rails).
+Helpers and shared contexts are provided for integration testing secure pages
+and API methods.
+
+#### Installation ####
+
+To automatically mix in helpers to your feature and request specs, include the
+following line in your `spec/spec_helper.rb`:
+
+```ruby
+require 'g5_authenticatable/rspec'
+```
+
+#### Feature Specs ####
+
+The easiest way to use g5_authenticatable in feature specs is through
+the shared auth context. This context creates a user (available via
+`let(:user)`) and then authenticates as that user. To use the shared
+context, simply include `:auth` in the RSpec metadata for your example
+or group:
+
+```ruby
+context 'my secure context', :auth do
+  it 'can access some resource' do
+    visit('the place')
+    expect(page).to ...
+  end
+end
+```
+
+If you prefer, you can use the helper methods from
+`G5Authenticatable::Test::FeatureHelpers` instead of relying on the shared
+context. For example:
+
+```ruby
+describe 'my page' do
+  context 'with valid user credentials' do
+    let(:my_user) { create(:g5_authenticatable_user, email: 'my.email@test.host') }
+    before { stub_g5_omniauth(my_user) }
+
+    it 'should display the secure page' do
+      visit('the page')
+      expect(page).to ...
+    end
+  end
+
+  context 'with invalid OAuth credentials' do
+    before { stub_g5_invalid_credentials }
+
+    it 'should display an error' do
+      visit('the page')
+      expect(page). to ...
+    end
+  end
+
+  context 'when user has previously authenticated' do
+    let(:my_user) { create(:g5_authenticatable_user, email: 'my.email@test.host') }
+    before { visit_path_and_login_with('some other path', my_user) }
+
+    it 'should display the thing I expect' do
+      visit('the page')
+      expect(page).to ...
+    end
+  end
+end
+```
+
+#### Request Specs ####
+
+You can test API methods that have been secured with g5_authenticatable by
+using the auth request shared context. This context creates a user (available
+via `let(:user)`) and then automatically authenticates as that user. To use the
+shared context, simply tag your example group with the `:auth_request` RSpec
+metadata:
+
+```ruby
+describe 'my secure API', :auth_request do
+  it 'can access some resource' do
+    get '/api/v1/resource'
+    expect(response).to ...
+  end
+end
+```
+
+Alternatively, you may wish to use the helper methods from
+`G5Authenticatable::Test::RequestHelpers` directly:
+
+```ruby
+describe 'my secure API' do
+  context 'when user is authenticated' do
+    before { login_user }
+
+    it 'can access some resource' do
+      get '/api/v1/resource'
+      expect(response).to be_success
+    end
+  end
+
+  context 'when there is no authenticated user' do
+    before { logout_user }
+
+    it 'cannot access the resource' do
+      get '/api/v1/resource'
+      expect(response.status).to eq(401)
+    end
+  end
+end
+```
+
+#### Controller Specs ####
+
+You can test controller specs that have been secured with g5_authenticatable
+by using the controller spec shared context.  This context creates a user
+available via `let(:user)` and then automatically authenticates as that user.
+To use the shared context, tag your example group with the `:auth_controller`
+Rspec metadata:
+
+```ruby
+describe 'my secure action', :auth_controller do
+  context 'when the user is authenticated' do
+	it 'can access some secure path' do
+	  get :my_action
+	  expect(response). to be_success
+	end
+  end
+
+  context 'whent there is no authenticated user' do
+	it 'cannot access the secure path' do
+	  get :my_action
+	  expect(reponse).to be_redirect
+	end
+  end
+end
+```
+
+## Examples
+
+### Protecting a particular Rails controller action
+
+You can use all of the usual options to `before_filter` for more fine-grained
+control over where authentication is required. For example, to require
+authentication only to edit a resource while leaving all other actions
+unsecured:
+
+```ruby
+class MyResourcesController < ApplicationController
+  before_filter :authenticate_user!, only: [:edit, :update]
+
+  # ...
+end
+```
+
+### Adding a link to sign in
+
+In your view template, add the following:
+
+```html+erb
+<%= link_to('Login', new_session_path(:user)) %>
+```
+
+### Adding a link to sign out
+
+In order to sign out, the link must not only have the correct path,
+but must also use the DELETE HTTP method:
+
+```html+erb
+<%= link_to('Logout', destroy_session_path(:user), :method => :delete) %>
+```
+
+### Selectively securing Grape API methods
+
+To selectively secure an individual API method:
+
+```ruby
+class MyApi < Grape::API
+  get :my_secure_action do
+    authenticate_user!
+    {message: 'secure action'}
+  end
+
+  get :anonymous_action do
+    {message: 'hello world'}
+  end
+end
+```
+
+### Securing a Rails controller that mixes API and website methods
+
+Within a Rails controller, the `authenticate_api_user!` looks for a token
+in the request and returns a 401 when a user cannot be authenticated.
+In contrast, devise's `authenticate_user!` filter assumes that client is a
+web browser, and redirects to the auth server sign in page when there is
+no authenticated user.
+
+Most of the time, there is a clear delineation between controllers
+that service API requests and controllers that service website requests,
+but not always. If you have a mixture of API and website actions in
+your controller, you can selectively apply the auth filters based on
+the request format:
+
+```ruby
+class MyMixedUpController < ApplicationController
+  before_filter :authenticate_api_user!, unless: :is_navigational_format?
+  before_filter :authenticate_user!, if: :is_navigational_format?
+
+  respond_to :html, :json
+
+  def show
+    resource = MyResource.find(params[:id])
+    respond_with(resource)
+  end
+end
+```
+
+In the code above, we assume that HTML requests come from a client that
+can display the auth server's sign in page to the end user, while all other
+formats are assumed to be API requests.
+
+## 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/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/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
+$ RAILS_ENV=test bundle exec rake app: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.