jsonapi-authorization

by venuu

Authorization for JSONAPI::Resource

129 Stars 48 Forks Last release: about 1 year ago (v3.0.2) MIT License 260 Commits 24 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

JSONAPI::Authorization

Build Status Gem Version

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.

The core design principle of

JSONAPI::Authorization
is:

Prefer being overly restrictive rather than too permissive by accident.

What follows is that we want to have:

  1. Whitelist over blacklist -approach for authorization
  2. Fall back on a more strict authorization

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.

If you're using custom processors, make sure that they extend

JSONAPI::Authorization::AuthorizingProcessor
, or authorization will not be performed for that resource.

This gem should work out-of-the box for simple cases. The default authorizer might be overly restrictive for cases where you are touching relationships.

If you are modifying relationships, you should read the relationship authorization documentation.

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
  • Later releases support JR
    v0.9.x
  • JR
    v0.10.x
    is NOT SUPPORTED.
    See https://github.com/venuu/jsonapi-authorization/issues/64 for more details and to offer help.

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.

Versioning and changelog

jsonapi-authorization
follows Semantic Versioning. We prefer to make more major version bumps when we do changes that are likely to be backwards incompatible. That holds true even when it's likely the changes would be backwards compatible for a majority of our users.

Given the nature of an authorization library, it is likely that most changes are major version bumps.

Whenever we do changes, we strive to write good changelogs in the GitHub releases page.

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

Policies

To check whether an action is allowed JSONAPI::Authorization calls the respective actions of your pundit policies (

index?
,
show?
,
create?
,
update?
,
destroy?
).

For relationship operations by default

update?
is being called for all affected resources. For a finer grained control you can define methods to authorize relationship changes. For example:
class ArticlePolicy

(...)

def add_to_comments?(new_comments) record.published && new_comments.all? { |comment| comment.author == user } end

def replace_comments?(new_comments) allowed = record.comments.all? { |comment| new_comments.include?(comment) || add_to_comments?([comment])} allowed && new_comments.all? { |comment| record.comments.include?(comment) || remove_from_comments?(comment) } end

def remove_from_comments?(comment) comment.author == user || user.admin? end end

For thorough documentation about custom policy methods, check out the relationship authorization docs.

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

By default JSONAPI::Authorization uses the

:user
key from the JSONAPI context hash as the Pundit user. If you would like to use
:current_user
or some other key, it can be configured as well.
JSONAPI::Authorization.configure do |config|
  config.pundit_user = :current_user
  # or a block can be provided
  config.pundit_user = ->(context){ context[:current_user] }
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.

Contributors

Thanks goes to these wonderful people (emoji key):

Vesa Laakso
Vesa Laakso

๐Ÿ’ป ๐Ÿ“– ๐Ÿš‡ โš ๏ธ ๐Ÿ› ๐Ÿ’ฌ ๐Ÿ‘€
Emil Sรฅgfors
Emil Sรฅgfors

๐Ÿ’ป ๐Ÿ“– ๐Ÿš‡ โš ๏ธ ๐Ÿ› ๐Ÿ’ฌ ๐Ÿ‘€
Matthias Grundmann
Matthias Grundmann

๐Ÿ’ป ๐Ÿ“– โš ๏ธ ๐Ÿ’ฌ
Thibaud Guillaume-Gentil
Thibaud Guillaume-Gentil

๐Ÿ’ป
Daniel Schweighรถfer
Daniel Schweighรถfer

๐Ÿ’ป
Bruno Sofiato
Bruno Sofiato

๐Ÿ’ป
Adam Robertson
Adam Robertson

๐Ÿ“–
Greg Fisher
Greg Fisher

๐Ÿ’ป โš ๏ธ
Sam
Sam

๐Ÿ’ป โš ๏ธ
Justas Palumickas
Justas Palumickas

๐Ÿ› ๐Ÿ’ป โš ๏ธ
Nicholas Rutherford
Nicholas Rutherford

๐Ÿ’ป โš ๏ธ ๐Ÿš‡
Matthijsy
Matthijsy

๐Ÿ› โš ๏ธ ๐Ÿ’ป
brianswko
brianswko

๐Ÿ› โš ๏ธ ๐Ÿ’ป

This project follows the all-contributors specification. Contributions of any kind welcome!

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.