rails_api_auth 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b165743edc12371fd7870892ad34aacf10bfe984
-  data.tar.gz: ced13aee635701bb2385267b33b952237602217a
+  metadata.gz: af65e9fe685271c6e68587e74a3e2c33f35dc12c
+  data.tar.gz: 2e55c5fb7ca6be0c2362769e744df99a8a5d9f11
 SHA512:
-  metadata.gz: 70632344b8bdec1043b8f5899e98166426301af14aaddd5dcea1322454a53e00e8f28a43f4c115ec00ec17fa1a396c8ded1393abcc98a0c6a00e1f05bea36649
-  data.tar.gz: 2bc812bf057509fe0df986881be6446fe2fe9430c6268dbfca3d7e7ea2589be3fa695d2a055abb0112558bed86446c3b163f18781070d0783d9f5d52dc755d64
+  metadata.gz: 50e2055e18d2f4ab5c28b0735446113a567d9f65a0a4877f5ebd09a9d210f45f96a0b76aa5b675108d40fef6e04f57e98ab6cd16e3c4c54631d2717f54099636
+  data.tar.gz: 83f495155e33db882ca560daeaa0db2b21c00fdda8a6e5b838a93fd93b7cbb280ac3d90680c29b228214799ca87c32f4fdf06c1432b1ce23741d4dbc55dfd06f

data/README.md

@@ -1,3 +1,160 @@
-= RailsApiAuth
+# RailsApiAuth
 
-This project rocks and uses MIT-LICENSE.
+[![Build Status](https://travis-ci.org/simplabs/rails_api_auth.svg)](https://travis-ci.org/simplabs/rails_api_auth)
+
+Rails API Auth is a lightweight Rails Engine that __implements the _"Resource
+Owner Password Credentials Grant"_ OAuth 2.0 flow
+([RFC 6749](http://tools.ietf.org/html/rfc6749#section-4.3)) as well as
+Facebook authentication for API projects__.
+
+It uses __Bearer tokens__ ([RFC 6750](http://tools.ietf.org/html/rfc6750)) to
+authorize requests coming in from clients.
+
+## Installation
+
+To install the engine simply add
+
+```ruby
+gem 'rails_auth_api'
+```
+
+to the application's `Gemfile` and run `bundle install`.
+
+__Rails API Auth also adds a migration__ to the application so run
+
+```bash
+rake db:migrate
+```
+
+as well to migrate the database.
+
+## Usage
+
+__Rails API Auth stores a user's credentials as well as the tokens in a `Login`
+model__ so that this data remains separated from the application's `User` model
+(or `Account` or whatever the application chose to store profile data in).
+
+After installing the engine you can add the relation from your user model to
+the `Login` model:
+
+```ruby
+class User < ActiveRecord::Base
+
+  has_one :login # this could be has_many as well of course
+
+end
+```
+
+When creating a new `User` in the host application, make sure to create a
+related `Login` as well, e.g.:
+
+```ruby
+class UsersController < ApplicationController
+
+  def create
+    user = User.new(user_params)
+    if user.save && user.create_login(login_params)
+      head 201
+    else
+      head 422 # you'd actually want to return validation errors here
+    end
+  end
+
+  private
+
+    def user_params
+      params.require(:user).permit(:first_name, :last_name)
+    end
+
+    def login_params
+      params.require(:user).permit(:identification, :password, :password_confirmation)
+    end
+
+end
+```
+
+__The engine adds 2 routes to the application__ that implement the endpoints
+for acquiring and revoking Bearer tokens:
+
+```
+token  POST /token(.:format)  oauth2#create
+revoke POST /revoke(.:format) oauth2#destroy
+```
+
+These endpoints are fully implemented in the engine and will issue or revoke
+Bearer tokens.
+
+In order to authorize incoming requests the engine provides the
+__`authenticate!` helper that can be used in controllers__ to make sure the
+request includes a valid Bearer token in the `Authorization` header (e.g.
+`Authorization: Bearer d5086ac8457b9db02a13`):
+
+```ruby
+class AuthenticatedController < ApplicationController
+
+  include RailsApiAuth::Authentication
+
+  before_action :authenticate!
+
+  def index
+    render json: { success: true }
+  end
+
+end
+
+```
+
+If no valid Bearer token is provided the client will see a 401 response.
+
+The engine also provides the `current_login` helper method that will return the
+`Login` model authorized with the sent Bearer token.
+
+You can also invoke `authenticate!` with a block to perform additional checks
+on the current login, e.g. making sure the login's associated account has a
+certain role:
+
+```ruby
+class AuthenticatedController < ApplicationController
+
+  include RailsApiAuth::Authentication
+
+  before_action :authenticate_admin!
+
+  def index
+    render json: { success: true }
+  end
+
+  private
+
+    def authenticate_admin!
+      authenticate! do
+        current_login.account.admin?
+      end
+    end
+
+end
+
+```
+
+## Configuration
+
+The Engine can be configured by simply setting some attributes on its main
+module:
+
+```ruby
+RailsApiAuth.tap do |raa|
+  raa.user_model_relation = :account # this will set up the belongs_to relation from the Login model to the Account model automatically (of course if your application uses a User model this would be :user)
+
+  raa.facebook_app_id       = '<your Facebook app id>'
+  raa.facebook_app_secret   = '<your Facebook app secret>'
+  raa.facebook_graph_url    = 'https://graph.facebook.com'
+  raa.facebook_redirect_uri = '<your Facebook app redirect uri>'
+end
+
+```
+
+## License
+
+Rails API Auth is developed by and &copy;
+[simplabs GmbH](http://simplabs.com) and contributors. It is released under the
+[MIT License](https://github.com/simplabs/ember-simple-auth/blob/master/LICENSE).

data/app/controllers/oauth2_controller.rb

@@ -1,7 +1,8 @@
 require 'login_not_found'
 
-class FacebookApiError < StandardError; end
-
+# The controller that implements the engine's endpoints.
+#
+# @!visibility private
 class Oauth2Controller < ApplicationController
 
   def create
@@ -18,7 +19,7 @@ class Oauth2Controller < ApplicationController
   def destroy
     oauth2_error('unsupported_token_type') && return unless params[:token_type_hint] == 'access_token'
 
-    login = Login.find_by(oauth2_token: params[:token]) || LoginNotFound.new
+    login = Login.where(oauth2_token: params[:token]).first || LoginNotFound.new
     login.refresh_oauth2_token!
 
     head 200
@@ -26,8 +27,8 @@ class Oauth2Controller < ApplicationController
 
   private
 
-    def authenticate_with_credentials(email, password)
-      login = Login.find_by(email: email) || LoginNotFound.new
+    def authenticate_with_credentials(identification, password)
+      login = Login.where(identification: identification).first || LoginNotFound.new
 
       if login.authenticate(password)
         render json: { access_token: login.oauth2_token }
@@ -39,12 +40,11 @@ class Oauth2Controller < ApplicationController
     def authenticate_with_facebook(auth_code)
       oauth2_error('no_authorization_code') && return unless auth_code.present?
 
-      login = FacebookAuthenticator.new(auth_code).authenticate
+      login = FacebookAuthenticator.new(auth_code).authenticate!
 
       render json: { access_token: login.oauth2_token }
-
-    rescue FacebookApiError
-      render nothing: true, status: 500
+    rescue FacebookAuthenticator::ApiError
+      render nothing: true, status: 502
     end
 
     def oauth2_error(error)

data/app/lib/login_not_found.rb

@@ -1,3 +1,6 @@
+# Null Object that is used when no login is found for a Bearer token.
+#
+# @!visibility private
 class LoginNotFound
 
   def authenticate(_)

data/app/models/login.rb

@@ -1,32 +1,79 @@
-require 'email_validator'
-
+# The `Login` __model encapsulates login credentials and the associated Bearer
+# tokens__. Rails API Auth uses this separate model so that login data and
+# user/profile data doesn't get mixed up and the Engine remains clearly
+# separeated from the code of the host application.
+#
+# The __`Login` model has `identification` and `password` attributes__ (in fact
+# it uses Rails'
+# [`has_secure_password`](http://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html#method-i-has_secure_password))
+# __as well as a `facebook_uid`__ (if it represents a Facebook login)
+# attribute. As opposed to the standard `has_secure_password` behavior it
+# doesn't validate that the password must be present but instead validates that
+# __either__ the `password` or the `facebook_uid` are present as no password is
+# required in the case that Facebook is used for authentication.
+#
+# The `Login` model also stores the Bearer token in the `oauth2_token`
+# attribute. The model also stores an additional Bearer token, the
+# `single_use_oauth2_token`, that can be used for implementing thinks like
+# password reset where you need to make sure that the provided token can only
+# be used once.
 class Login < ActiveRecord::Base
 
-  class AlreadyVerifiedError < StandardError; end
-  class InvalidSingleUseOAuth2Token < StandardError; end
+  # This is raised when an invalid token or a token that has already been
+  # consumed is consumed.
+  class InvalidOAuth2Token < StandardError; end
+
+  if RailsApiAuth.user_model_relation
+    belongs_to RailsApiAuth.user_model_relation, foreign_key: :user_id
+  end
 
-  has_secure_password validations: false
+  if Rails::VERSION::MAJOR >= 4
+    has_secure_password validations: false
+  else
+    has_secure_password
+  end
 
-  validates :email, presence: true, email: true
+  validates :identification, presence: true
   validates :oauth2_token, presence: true
   validates :single_use_oauth2_token, presence: true
-  validates :password, length: { maximum: ActiveModel::SecurePassword::MAX_PASSWORD_LENGTH_ALLOWED }, confirmation: true
+  validates :password, length: { maximum: 72 }, confirmation: true
   validate :password_or_facebook_uid_present
 
   before_validation :ensure_oauth2_token
   before_validation :refresh_single_use_oauth2_token
 
+  # Refreshes the Bearer token. This will effectively log out all clients that
+  # possess the previous token.
+  #
+  # @raise [ActiveRecord::RecordInvalid] if the model is invalid
   def refresh_oauth2_token!
     ensure_oauth2_token(true)
     save!
   end
 
+  # This validates the passed single use Bearer token and assigns a new one. It
+  # will raise an exception if the token is not valid or has already been
+  # consumed.
+  #
+  # @param token [String] the single use token to consume
+  # @raise [InvalidOAuth2Token] if the token is not valid or has already been
+  #   consumed
+  # @raise [ActiveRecord::RecordInvalid] if the model is invalid
   def consume_single_use_oauth2_token!(token)
-    raise InvalidSingleUseOAuth2Token.new if token != single_use_oauth2_token
+    raise InvalidOAuth2Token.new if token != single_use_oauth2_token
     refresh_single_use_oauth2_token
     save!
   end
 
+  if Rails::VERSION::MAJOR == 3
+    # @!visibility private
+    def errors
+      super.tap do |errors|
+        errors.delete(:password_digest)
+      end
+    end
+  end
+
   private
 
     def password_or_facebook_uid_present

data/app/services/facebook_authenticator.rb

@@ -1,12 +1,17 @@
 require 'httparty'
 
+# Handles Facebook authentication
+#
+# @!visibility private
 class FacebookAuthenticator
 
+  class ApiError < StandardError; end
+
   def initialize(auth_code)
     @auth_code = auth_code
   end
 
-  def authenticate
+  def authenticate!
     if login.present?
       connect_login_to_fb_account
     else
@@ -19,7 +24,7 @@ class FacebookAuthenticator
   private
 
     def login
-      @login ||= Login.find_by(email: facebook_user[:email])
+      @login ||= Login.where(identification: facebook_user[:email]).first
     end
 
     def connect_login_to_fb_account
@@ -28,8 +33,8 @@ class FacebookAuthenticator
 
     def create_login_from_fb_account
       login_attributes = {
-        email: facebook_user[:email],
-        facebook_uid: facebook_user[:id]
+        identification: facebook_user[:email],
+        facebook_uid:   facebook_user[:id]
       }
 
       @login = Login.create!(login_attributes)
@@ -44,21 +49,21 @@ class FacebookAuthenticator
 
     def facebook_request(url)
       response = HTTParty.get(url)
-      raise FacebookApiError.new if response.code != 200
+      raise ApiError.new if response.code != 200
       response
     end
 
     def fb_token_url
-      "#{Rails.application.config.x.facebook.graph_url}/oauth/access_token".tap do |url|
-        url << "?client_id=#{Rails.application.config.x.facebook.app_id}"
-        url << "&redirect_uri=#{Rails.application.config.x.facebook.redirect_uri}"
-        url << "&client_secret=#{Rails.application.config.x.facebook.app_secret}"
+      "#{RailsApiAuth.facebook_graph_url}/oauth/access_token".tap do |url|
+        url << "?client_id=#{RailsApiAuth.facebook_app_id}"
+        url << "&redirect_uri=#{RailsApiAuth.facebook_redirect_uri}"
+        url << "&client_secret=#{RailsApiAuth.facebook_app_secret}"
         url << "&code=#{@auth_code}"
       end
     end
 
     def fb_user_url(access_token)
-      "#{Rails.application.config.x.facebook.graph_url}/me?access_token=#{access_token}"
+      "#{RailsApiAuth.facebook_graph_url}/me?access_token=#{access_token}"
     end
 
 end

data/db/migrate/20150709221755_create_logins.rb

@@ -2,11 +2,12 @@ class CreateLogins < ActiveRecord::Migration
 
   def change
     create_table :logins do |t|
-      t.string :email,           null: false
+      t.string :identification,  null: false
       t.string :password_digest, null: true
       t.string :oauth2_token,    null: false
       t.string :facebook_uid
       t.string :single_use_oauth2_token
+
       t.references :user
 
       t.timestamps

data/lib/rails_api_auth.rb

@@ -1,5 +1,31 @@
 require 'rails_api_auth/engine'
 
+# The engine's main module.
 module RailsApiAuth
 
+  # @!attribute [rw] user_model_relation
+  # Defines the `Login` model's `belongs_to` relation to the host application's
+  # `User` model (or `Account` or whatever the application stores user data
+  # in).
+  #
+  # E.g. is this is set to `:profile`, the `Login` model will have a
+  # `belongs_to :profile` relation.
+  mattr_accessor :user_model_relation
+
+  # @!attribute [rw] facebook_app_id
+  # The Facebook App ID.
+  mattr_accessor :facebook_app_id
+
+  # @!attribute [rw] facebook_app_secret
+  # The Facebook App secret.
+  mattr_accessor :facebook_app_secret
+
+  # @!attribute [rw] facebook_graph_url
+  # The Facebook grahp URL.
+  mattr_accessor :facebook_graph_url
+
+  # @!attribute [rw] facebook_redirect_uri
+  # The Facebook App's redirect URI.
+  mattr_accessor :facebook_redirect_uri
+
 end

data/lib/rails_api_auth/authentication.rb

@@ -1,27 +1,83 @@
 module RailsApiAuth
 
+  # Module that defines attributes and method for use in controllers. This
+  # module would typically be included in the `ApplicationController`.
   module Authentication
 
-    class RequestForbidden < StandardError; end
-
     extend ActiveSupport::Concern
 
+    # @!attribute [r] current_login
+    # The login that was authenticated from the Bearer token in the
+    # `Authorization` header (if one was successfully authenticated).
+
+    # @!method authenticate!(&block)
+    # Ensures that the `Authorization` header is present with a valid Bearer
+    # token.
+    #
+    # If a valid bearer token is present this method will retrieve the
+    # respective `Login` model and store it in `current_login`. If no or an
+    # invalid Bearer token is present this will result in a 401 response.
+    #
+    # This method will typically be called as a `before_action`:
+    #
+    # ```ruby
+    # class AuthenticatedController < ApplicationController
+    #
+    #   include RailsApiAuth::Authentication
+    #
+    #   before_filter :authenticate!
+    #
+    #   def index
+    #     render text: 'zuper content', status: 201
+    #   end
+    #
+    # end
+    # ```
+    #
+    # You can also call this method with a block to perform additional checks
+    # on the login retrieved for the Bearer token. When the block returns a
+    # truthy value authentication is successful, when the block returns a falsy
+    # value the client will see a 401 response:
+    #
+    # ```ruby
+    # class AuthenticatedController < ApplicationController
+    #
+    #   include RailsApiAuth::Authentication
+    #
+    #   before_filter :authenticate_admin!
+    #
+    #   def index
+    #     render text: 'zuper content', status: 201
+    #   end
+    #
+    #   private
+    #
+    #     def authenticate_with_account!
+    #       authenticate! do
+    #         current_login.account.first_name == 'user x'
+    #       end
+    #     end
+    #
+    # end
+    # ```
+    #
+    # @see #current_login
+
     included do
       attr_reader :current_login
 
-      rescue_from RequestForbidden, with: :deny_access
-
       private
 
-        def deny_access
-          head 403
-        end
-
-        def authenticate!
-          auth_header = request.headers[:authorization]
+        def authenticate!(&block)
+          auth_header = request.headers['Authorization']
           token = auth_header ? auth_header.split(' ').last : ''
-          @current_login ||= Login.find_by!(oauth2_token: token)
+          @current_login = Login.where(oauth2_token: token).first!
 
+          if block_given?
+            head 401 unless block.call
+          else
+            @current_login
+          end
         rescue ActiveRecord::RecordNotFound
           head 401
         end