README.md in jsonapi-authorization-1.0.0.alpha6 vs README.md in jsonapi-authorization-1.0.0.beta1

- old
+ new

@@ -12,22 +12,31 @@ `JSONAPI::Authorization` adds authorization to the [jsonapi-resources][jr] (JR) gem using [Pundit][pundit]. [jr]: https://github.com/cerebris/jsonapi-resources "A resource-focused Rails library for developing JSON API compliant servers." [pundit]: https://github.com/elabs/pundit "Minimal authorization through OO design and pure Ruby classes" +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][issues]. 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 [more complex cases][complex-case]. +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](docs/relationship-authorization.md). + The API is subject to change between minor version bumps until we reach v1.0.0. - [complex-case]: https://github.com/venuu/jsonapi-authorization/issues/15 - ## Installation Add this line to your application's Gemfile: ```ruby @@ -95,12 +104,11 @@ 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 `add_to_<relation>?`, `replace_<relation>?`, and `remove_from_<relation>?` -as the following example shows. +For a finer grained control you can define methods to authorize relationship changes. For example: ```ruby class ArticlePolicy # (...) @@ -118,13 +126,11 @@ comment.author == user || user.admin? end end ``` -Caveat: In case a relationship is modifiable through multiple ways it is your responsibility to ensure consistency. -For example if you have a many-to-many relationship with users and projects make sure that -`ProjectPolicy#add_to_users?(users)` and `UserPolicy#add_to_projects?(projects)` match up. +For thorough documentation about custom policy methods, check out the [relationship authorization docs](docs/relationship-authorization.md). ## 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. @@ -175,11 +181,12 @@ ## Contributors Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)): <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> -| [<img src="https://avatars.githubusercontent.com/u/482561?v=3" width="100px;"/><br /><sub>Vesa Laakso</sub>](http://vesalaakso.com)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=valscion) [πŸ“–](https://github.com/Venuu/jsonapi-authorization/commits?author=valscion) πŸš‡ [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=valscion) [πŸ›](https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Avalscion) πŸ’¬ πŸ‘€ | [<img src="https://avatars.githubusercontent.com/u/562204?v=3" width="100px;"/><br /><sub>Emil SΓ₯gfors</sub>](https://github.com/lime)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=lime) [πŸ“–](https://github.com/Venuu/jsonapi-authorization/commits?author=lime) πŸš‡ [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=lime) [πŸ›](https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Alime) πŸ’¬ πŸ‘€ | [<img src="https://avatars.githubusercontent.com/u/1591161?v=3" width="100px;"/><br /><sub>Matthias Grundmann</sub>](https://github.com/matthias-g)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=matthias-g) [πŸ“–](https://github.com/Venuu/jsonapi-authorization/commits?author=matthias-g) [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=matthias-g) πŸ’¬ | [<img src="https://avatars.githubusercontent.com/u/1322?v=3" width="100px;"/><br /><sub>Thibaud Guillaume-Gentil</sub>](http://thibaud.gg)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=thibaudgg) | [<img src="https://avatars.githubusercontent.com/u/71660?v=3" width="100px;"/><br /><sub>Daniel SchweighΓΆfer</sub>](http://netsteward.net)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=acid) | [<img src="https://avatars.githubusercontent.com/u/5076967?v=3" width="100px;"/><br /><sub>Bruno Sofiato</sub>](https://github.com/bsofiato)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=bsofiato) | [<img src="https://avatars.githubusercontent.com/u/1896026?v=3" width="100px;"/><br /><sub>Adam Robertson</sub>](https://github.com/arcreative)<br />[πŸ“–](https://github.com/Venuu/jsonapi-authorization/commits?author=arcreative) | +<!-- prettier-ignore --> +| [<img src="https://avatars.githubusercontent.com/u/482561?v=3" width="100px;"/><br /><sub><b>Vesa Laakso</b></sub>](http://vesalaakso.com)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=valscion "Code") [πŸ“–](https://github.com/Venuu/jsonapi-authorization/commits?author=valscion "Documentation") [πŸš‡](#infra-valscion "Infrastructure (Hosting, Build-Tools, etc)") [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=valscion "Tests") [πŸ›](https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Avalscion "Bug reports") [πŸ’¬](#question-valscion "Answering Questions") [πŸ‘€](#review-valscion "Reviewed Pull Requests") | [<img src="https://avatars.githubusercontent.com/u/562204?v=3" width="100px;"/><br /><sub><b>Emil SΓ₯gfors</b></sub>](https://github.com/lime)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=lime "Code") [πŸ“–](https://github.com/Venuu/jsonapi-authorization/commits?author=lime "Documentation") [πŸš‡](#infra-lime "Infrastructure (Hosting, Build-Tools, etc)") [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=lime "Tests") [πŸ›](https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Alime "Bug reports") [πŸ’¬](#question-lime "Answering Questions") [πŸ‘€](#review-lime "Reviewed Pull Requests") | [<img src="https://avatars.githubusercontent.com/u/1591161?v=3" width="100px;"/><br /><sub><b>Matthias Grundmann</b></sub>](https://github.com/matthias-g)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=matthias-g "Code") [πŸ“–](https://github.com/Venuu/jsonapi-authorization/commits?author=matthias-g "Documentation") [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=matthias-g "Tests") [πŸ’¬](#question-matthias-g "Answering Questions") | [<img src="https://avatars.githubusercontent.com/u/1322?v=3" width="100px;"/><br /><sub><b>Thibaud Guillaume-Gentil</b></sub>](http://thibaud.gg)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=thibaudgg "Code") | [<img src="https://avatars.githubusercontent.com/u/71660?v=3" width="100px;"/><br /><sub><b>Daniel SchweighΓΆfer</b></sub>](http://netsteward.net)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=acid "Code") | [<img src="https://avatars.githubusercontent.com/u/5076967?v=3" width="100px;"/><br /><sub><b>Bruno Sofiato</b></sub>](https://github.com/bsofiato)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=bsofiato "Code") | [<img src="https://avatars.githubusercontent.com/u/1896026?v=3" width="100px;"/><br /><sub><b>Adam Robertson</b></sub>](https://github.com/arcreative)<br />[πŸ“–](https://github.com/Venuu/jsonapi-authorization/commits?author=arcreative "Documentation") | | :---: | :---: | :---: | :---: | :---: | :---: | :---: | -| [<img src="https://avatars3.githubusercontent.com/u/4742306?v=3" width="100px;"/><br /><sub>Greg Fisher</sub>](https://github.com/gnfisher)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=gnfisher) [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=gnfisher) | [<img src="https://avatars3.githubusercontent.com/u/370182?v=3" width="100px;"/><br /><sub>Sam</sub>](http://samlh.com)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=handlers) [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=handlers) | [<img src="https://avatars0.githubusercontent.com/u/2738630?v=3" width="100px;"/><br /><sub>Justas Palumickas</sub>](https://jpalumickas.com)<br />[πŸ›](https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Ajpalumickas) [πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=jpalumickas) [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=jpalumickas) | +| [<img src="https://avatars3.githubusercontent.com/u/4742306?v=3" width="100px;"/><br /><sub><b>Greg Fisher</b></sub>](https://github.com/gnfisher)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=gnfisher "Code") [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=gnfisher "Tests") | [<img src="https://avatars3.githubusercontent.com/u/370182?v=3" width="100px;"/><br /><sub><b>Sam</b></sub>](http://samlh.com)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=handlers "Code") [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=handlers "Tests") | [<img src="https://avatars0.githubusercontent.com/u/2738630?v=3" width="100px;"/><br /><sub><b>Justas Palumickas</b></sub>](https://jpalumickas.com)<br />[πŸ›](https://github.com/Venuu/jsonapi-authorization/issues?q=author%3Ajpalumickas "Bug reports") [πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=jpalumickas "Code") [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=jpalumickas "Tests") | [<img src="https://avatars1.githubusercontent.com/u/26158?v=4" width="100px;"/><br /><sub><b>Nicholas Rutherford</b></sub>](http://www.google.co.uk/profiles/nick.rutherford)<br />[πŸ’»](https://github.com/Venuu/jsonapi-authorization/commits?author=nruth "Code") [⚠️](https://github.com/Venuu/jsonapi-authorization/commits?author=nruth "Tests") [πŸš‡](#infra-nruth "Infrastructure (Hosting, Build-Tools, etc)") | <!-- ALL-CONTRIBUTORS-LIST:END --> -This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome! \ No newline at end of file +This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!