{"id":13558128,"url":"https://github.com/venuu/jsonapi-authorization","last_synced_at":"2025-04-12T17:41:28.650Z","repository":{"id":48278695,"uuid":"50169934","full_name":"venuu/jsonapi-authorization","owner":"venuu","description":"Authorization for JSONAPI::Resource","archived":false,"fork":false,"pushed_at":"2024-07-24T15:55:23.000Z","size":308,"stargazers_count":132,"open_issues_count":16,"forks_count":60,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-03T18:15:38.633Z","etag":null,"topics":["authorization","json-api","jsonapi-authorization","jsonapi-resources","pundit"],"latest_commit_sha":null,"homepage":"http://www.rubydoc.info/github/venuu/jsonapi-authorization","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/venuu.png","metadata":{"files":{"readme":"README-old.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-22T08:59:58.000Z","updated_at":"2024-09-02T16:19:26.000Z","dependencies_parsed_at":"2024-06-18T20:08:36.561Z","dependency_job_id":"c3fbd58c-4abb-4ba4-9868-6ccc6aff56d1","html_url":"https://github.com/venuu/jsonapi-authorization","commit_stats":{"total_commits":249,"total_committers":18,"mean_commits":"13.833333333333334","dds":0.5140562248995983,"last_synced_commit":"5dabf63f61fd0df34daf0ce7efb230220454a050"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venuu%2Fjsonapi-authorization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venuu%2Fjsonapi-authorization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venuu%2Fjsonapi-authorization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/venuu%2Fjsonapi-authorization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/venuu","download_url":"https://codeload.github.com/venuu/jsonapi-authorization/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248607885,"owners_count":21132625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authorization","json-api","jsonapi-authorization","jsonapi-resources","pundit"],"created_at":"2024-08-01T12:04:45.805Z","updated_at":"2025-04-12T17:41:28.620Z","avatar_url":"https://github.com/venuu.png","language":"Ruby","funding_links":[],"categories":["Ruby","others"],"sub_categories":[],"readme":"# JSONAPI::Authorization\n\n[![Build Status](https://img.shields.io/travis/com/venuu/jsonapi-authorization/master.svg?style=flat\u0026maxAge=3600)](https://travis-ci.com/venuu/jsonapi-authorization) [![Gem Version](https://img.shields.io/gem/v/jsonapi-authorization.svg?style=flat\u0026maxAge=3600)](https://rubygems.org/gems/jsonapi-authorization)\n\n**NOTE:** This README is the documentation for `JSONAPI::Authorization`. If you are viewing this at the\n[project page on Github](https://github.com/venuu/jsonapi-authorization) you are viewing the documentation for the `master`\nbranch. This may contain information that is not relevant to the release you are using. Please see the README for the\n[version](https://github.com/venuu/jsonapi-authorization/releases) you are using.\n\n ---\n\n`JSONAPI::Authorization` adds authorization to the [jsonapi-resources][jr] (JR) gem using [Pundit][pundit].\n\n  [jr]: https://github.com/cerebris/jsonapi-resources \"A resource-focused Rails library for developing JSON API compliant servers.\"\n  [pundit]: https://github.com/elabs/pundit \"Minimal authorization through OO design and pure Ruby classes\"\n\nThe core design principle of `JSONAPI::Authorization` is:\n\n**Prefer being overly restrictive rather than too permissive by accident.**\n\nWhat follows is that we want to have:\n\n1. Whitelist over blacklist -approach for authorization\n2. Fall back on a more strict authorization\n\n## Caveats\n\nMake 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][issues].\n\nIf you're using custom processors, make sure that they extend `JSONAPI::Authorization::AuthorizingProcessor`, or authorization will not be performed for that resource.\n\nThis gem should work out-of-the box for simple cases. The default authorizer might be overly restrictive for cases where you are touching relationships.\n\n**If you are modifying relationships**, you should read the [relationship authorization documentation](docs/relationship-authorization.md).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'jsonapi-authorization'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install jsonapi-authorization\n\n## Compatibility\n\n* `v0.6.x` supports JR `v0.7.x`\n* `v0.8.x` supports JR `v0.8.x`\n* Later releases support JR `v0.9.x`\n* **JR `v0.10.x` is NOT SUPPORTED.** See https://github.com/venuu/jsonapi-authorization/issues/64 for more details and to offer help.\n\nWe 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][issues].\n\n## Versioning and changelog\n\n`jsonapi-authorization` follows [Semantic Versioning](https://semver.org/). 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.\n\nGiven the nature of an authorization library, it is likely that most changes are major version bumps.\n\nWhenever we do changes, we strive to write good changelogs in the [GitHub releases page](https://github.com/venuu/jsonapi-authorization/releases).\n\n## Usage\n\nFirst make sure you have a Pundit policy specified for every backing model that your JR resources use.\n\nHook up this gem as the default processor for JR, and optionally allow rescuing from `Pundit::NotAuthorizedError` to output better errors for unauthorized requests:\n\n```ruby\n# config/initializers/jsonapi-resources.rb\nJSONAPI.configure do |config|\n  config.default_processor_klass = JSONAPI::Authorization::AuthorizingProcessor\n  config.exception_class_whitelist = [Pundit::NotAuthorizedError]\nend\n```\n\nMake all your JR controllers specify the user in the `context` and rescue errors thrown by unauthorized requests:\n\n```ruby\nclass BaseResourceController \u003c ActionController::Base\n  include JSONAPI::ActsAsResourceController\n  rescue_from Pundit::NotAuthorizedError, with: :user_not_authorized\n\n  private\n\n  def context\n    {user: current_user}\n  end\n\n  def user_not_authorized\n    head :forbidden\n  end\nend\n```\n\nHave your JR resources include the `JSONAPI::Authorization::PunditScopedResource` module.\n\n```ruby\nclass BaseResource \u003c JSONAPI::Resource\n  include JSONAPI::Authorization::PunditScopedResource\n  abstract\nend\n```\n\n### Policies\n\nTo check whether an action is allowed JSONAPI::Authorization calls the respective actions of your pundit policies\n(`index?`, `show?`, `create?`, `update?`, `destroy?`).\n\nFor relationship operations by default `update?` is being called for all affected resources.\nFor a finer grained control you can define methods to authorize relationship changes. For example:\n\n```ruby\nclass ArticlePolicy\n\n  # (...)\n\n  def add_to_comments?(new_comments)\n    record.published \u0026\u0026 new_comments.all? { |comment| comment.author == user }\n  end\n\n  def replace_comments?(new_comments)\n    allowed = record.comments.all? { |comment| new_comments.include?(comment) || add_to_comments?([comment])}\n    allowed \u0026\u0026 new_comments.all? { |comment| record.comments.include?(comment) || remove_from_comments?(comment) }\n  end\n\n  def remove_from_comments?(comment)\n    comment.author == user || user.admin?\n  end\nend\n```\n\nFor thorough documentation about custom policy methods, check out the [relationship authorization docs](docs/relationship-authorization.md).\n\n## Configuration\n\nYou 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.\n\n```ruby\nJSONAPI::Authorization.configure do |config|\n  config.authorizer = MyCustomAuthorizer\nend\n```\n\nBy 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.\n\n```ruby\nJSONAPI::Authorization.configure do |config|\n  config.pundit_user = :current_user\n  # or a block can be provided\n  config.pundit_user = -\u003e(context){ context[:current_user] }\nend\n```\n\n## Troubleshooting\n\n### \"Unable to find policy\" exception for a request\n\nThe exception might look like this for resource class `ArticleResource` that is backed by `Article` model:\n\n```\nunable to find policy `ArticlePolicy` for `Article'\n```\n\nThis means that you don't have a policy class created for your model. Create one and the error should go away.\n\n## Development\n\nAfter 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.\n\nTo 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](https://rubygems.org).\n\n## Credits\n\nOriginally based on discussion and code samples by [@barelyknown](https://github.com/barelyknown) and others in [cerebris/jsonapi-resources#16](https://github.com/cerebris/jsonapi-resources/issues/16).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/venuu/jsonapi-authorization.\n\n  [issues]: https://github.com/venuu/jsonapi-authorization/issues\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore --\u003e\n\u003ctable\u003e\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"http://vesalaakso.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/482561?v=3\" width=\"100px;\" alt=\"Vesa Laakso\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eVesa Laakso\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=valscion\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=valscion\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#infra-valscion\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=valscion\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Avalscion\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"#question-valscion\" title=\"Answering Questions\"\u003e💬\u003c/a\u003e \u003ca href=\"#review-valscion\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/lime\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/562204?v=3\" width=\"100px;\" alt=\"Emil Sågfors\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eEmil Sågfors\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=lime\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=lime\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#infra-lime\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=lime\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Alime\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"#question-lime\" title=\"Answering Questions\"\u003e💬\u003c/a\u003e \u003ca href=\"#review-lime\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/matthias-g\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1591161?v=3\" width=\"100px;\" alt=\"Matthias Grundmann\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMatthias Grundmann\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=matthias-g\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=matthias-g\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=matthias-g\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"#question-matthias-g\" title=\"Answering Questions\"\u003e💬\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"http://thibaud.gg\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1322?v=3\" width=\"100px;\" alt=\"Thibaud Guillaume-Gentil\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eThibaud Guillaume-Gentil\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=thibaudgg\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"http://netsteward.net\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/71660?v=3\" width=\"100px;\" alt=\"Daniel Schweighöfer\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDaniel Schweighöfer\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=acid\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/bsofiato\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/5076967?v=3\" width=\"100px;\" alt=\"Bruno Sofiato\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBruno Sofiato\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=bsofiato\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/arcreative\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1896026?v=3\" width=\"100px;\" alt=\"Adam Robertson\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAdam Robertson\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=arcreative\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/gnfisher\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/4742306?v=3\" width=\"100px;\" alt=\"Greg Fisher\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eGreg Fisher\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=gnfisher\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=gnfisher\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"http://samlh.com\"\u003e\u003cimg src=\"https://avatars3.githubusercontent.com/u/370182?v=3\" width=\"100px;\" alt=\"Sam\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eSam\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=handlers\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=handlers\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://jpalumickas.com\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/2738630?v=3\" width=\"100px;\" alt=\"Justas Palumickas\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJustas Palumickas\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Ajpalumickas\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=jpalumickas\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=jpalumickas\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"http://www.google.co.uk/profiles/nick.rutherford\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/26158?v=4\" width=\"100px;\" alt=\"Nicholas Rutherford\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eNicholas Rutherford\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=nruth\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=nruth\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"#infra-nruth\" title=\"Infrastructure (Hosting, Build-Tools, etc)\"\u003e🚇\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/Matthijsy\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/5302372?v=4\" width=\"100px;\" alt=\"Matthijsy\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMatthijsy\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/issues?q=author%3AMatthijsy\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=Matthijsy\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=Matthijsy\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/brianswko\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/3952486?v=4\" width=\"100px;\" alt=\"brianswko\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ebrianswko\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Abrianswko\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=brianswko\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"https://github.com/Venuu/jsonapi-authorization/commits?author=brianswko\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvenuu%2Fjsonapi-authorization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvenuu%2Fjsonapi-authorization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvenuu%2Fjsonapi-authorization/lists"}