JSONAPI::Authorization

NOTE: This README is the documentation for JSONAPI::Authorization. If you are viewing this at the project page on Github you are viewing the documentation for the master branch. This may contain information that is not relevant to the release you are using. Please see the README for the version you are using.

---

JSONAPI::Authorization adds authorization to the jsonapi-resources (JR) gem using Pundit.

Caveats

Make sure to test for authorization in your application, too. We should have coverage of all operations, though. If that isn't the case, please open an issue.

This gem should work out-of-the box for simple cases. The default authorizer might be overly restrictive for more complex cases.

The API is subject to change between minor version bumps until we reach v1.0.0.

Installation

Add this line to your application's Gemfile:

gem 'jsonapi-authorization'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jsonapi-authorization

Compatibility

• v0.6.x supports JR v0.7.x
• v0.8.x supports JR v0.8.x

We aim to support the same Ruby and Ruby on Rails versions as jsonapi-resources does. If that's not the case, please open an issue.

Usage

First make sure you have a Pundit policy specified for every backing model that your JR resources use.

Hook up this gem as the default processor for JR, and optionally allow rescuing from Pundit::NotAuthorizedError to output better errors for unauthorized requests:

# config/initializers/jsonapi-resources.rb
JSONAPI.configure do |config|
  config.default_processor_klass = JSONAPI::Authorization::AuthorizingProcessor
  config.exception_class_whitelist = [Pundit::NotAuthorizedError]
end

Make all your JR controllers specify the user in the context and rescue errors thrown by unauthorized requests:

class BaseResourceController < ActionController::Base
  include JSONAPI::ActsAsResourceController
  rescue_from Pundit::NotAuthorizedError, with: :user_not_authorized

  private

  def context
    {user: current_user}
  end

  def user_not_authorized
    head :forbidden
  end
end

Have your JR resources include the JSONAPI::Authorization::PunditScopedResource module.

class BaseResource < JSONAPI::Resource
  include JSONAPI::Authorization::PunditScopedResource
  abstract
end

Configuration

You can use a custom authorizer class by specifying a configure block in an initializer file. If using a custom authorizer class, be sure to require them at the top of the initializer before usage.

JSONAPI::Authorization.configure do |config|
  config.authorizer = MyCustomAuthorizer
end

Troubleshooting

"Unable to find policy" exception for a request

The exception might look like this for resource class ArticleResource that is backed by Article model:

unable to find policy `ArticlePolicy` for `Article'

This means that you don't have a policy class created for your model. Create one and the error should go away.

Development

After checking out the repo, run bundle install to install dependencies. Then, run bundle exec rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Credits

Originally based on discussion and code samples by @barelyknown and others in cerebris/jsonapi-resources#16.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/venuu/jsonapi-authorization.