capcoauth-gem

Ruby Gem for integrating a Rails project with CapcOAuth

Currently, this only supports session-based authentication, but can easily be adapted to accept bearer tokens if needed.

1. Add to your gemfile:

gem 'capcoauth'

2. Run the following from your console to install the gem:

bundle install

3. Run the following from your console to install the initializer in config/initializers/capcoauth.rb:

rails generate capcoauth:install

You'll need to obtain an OAuth client ID and client secret for your application, which can then be entered into your initializer in config/initializers/capcoauth.rb.

In your controllers, just call the helper method verify_authorized! for all protected resources. This is easiest done by adding it as a before_action:

class ApplicationController < ActionController::Base
  before_action :verify_authorized!
end

You may exclude/include for specific actions:

class ApplicationController < ActionController::Base
  before_action :verify_authorized!, only: [:my_super_secret_action], except: [:my_publicly_accessible_action]
end

Or even skip it entirely for specific controllers:

class PublicStuffController < ApplicationController
  skip_before_action :verify_authorized!
end

The installation script will add use_capcoauth to your routes.rb file, which creates these routes for you:

       Prefix Verb URI Pattern              Controller#Action
   auth_login GET  /auth/login(.:format)    capcoauth/login#show
  auth_logout GET  /auth/logout(.:format)   capcoauth/logout#show
auth_callback GET  /auth/callback(.:format) capcoauth/callback#show

These are very important, as they implement the core functionality of this gem. The login route will generate a CapcOAuth authorization URL appropriate for your application, and redirect the user to it. Upon successful login and authorization of your application, they will be redirected to the callback route, which will exchange their code with an access token, and will store that and the user's ID in the session.

Verification of the access token happens when verify_authorized! is executed, which caches the success response for whatever TTL value you set in your initializer. This saves time by preventing every request from calling home to CapcOAuth for approval. This can be increased or decreased at your discretion, but should be kept to a relatively low value.

Simply remove use_capcoauth from routes.rb, or don't add it if you created your own initializer.

By default, this gem assumes you're using a normal Rails application, and thus adds use_capcoauth to your routes.rb file. When use_capcoauth is used, it signals the gem to allow redirects and session variables whenever an HTML request type is detected. For API-only applications, it will only parse the access_token query param and Authorization headers.

Email me or submit via issue/pull request.