Unverified Commit c72e314b authored by Alessandro Rodi's avatar Alessandro Rodi Committed by GitHub
Browse files

update README (#454)

parent 8fc2a2db
......@@ -5,17 +5,21 @@
[![Gem Version](https://badge.fury.io/rb/cancancan.svg)](http://badge.fury.io/rb/cancancan)
[![Travis badge](https://travis-ci.org/CanCanCommunity/cancancan.svg?branch=develop)](https://travis-ci.org/CanCanCommunity/cancancan)
[![Code Climate Badge](https://codeclimate.com/github/CanCanCommunity/cancancan.svg)](https://codeclimate.com/github/CanCanCommunity/cancancan)
[![Inch CI](http://inch-ci.org/github/CanCanCommunity/cancancan.svg)](http://inch-ci.org/github/CanCanCommunity/cancancan)
[Wiki](https://github.com/CanCanCommunity/cancancan/wiki) |
[RDocs](http://rdoc.info/projects/CanCanCommunity/cancancan) |
[Screencast](http://railscasts.com/episodes/192-authorization-with-cancan) |
[Gitter](https://gitter.im/CanCanCommunity/cancancan)
[Screencast](http://railscasts.com/episodes/192-authorization-with-cancan) |
CanCanCan is an authorization library for Ruby >= 2.2.0 and Ruby on Rails >= 4.2 which restricts what resources a given user is allowed to access.
All permissions are defined in a single location (the `Ability` class) and not duplicated across controllers, views, and database queries.
All permissions can be defined in one or multiple ability files and not duplicated across controllers, views, and database queries, keeping your permissions logic in one place.
It consists of two main parts:
1. **the authorizations definition library** that allows you to define the rules, for a user,
to access different objects, and provides helpers to check for those permissions.
2. **controller helpers** that help to simplify the code in Rails Controllers by performing the loading and checking of permissions
of models for you in the controllers.
## Installation
......@@ -31,10 +35,6 @@ For Rails < 4.2 use:
## Getting Started
CanCanCan expects a `current_user` method to exist in the controller.
First, set up some authentication (such as [Devise](https://github.com/plataformatec/devise) or [Authlogic](https://github.com/binarylogic/authlogic)).
See [Changing Defaults](https://github.com/CanCanCommunity/cancancan/wiki/changing-defaults) if you need a different behavior.
### 1. Define Abilities
User permissions are defined in an `Ability` class.
......@@ -44,7 +44,7 @@ User permissions are defined in an `Ability` class.
See [Defining Abilities](https://github.com/CanCanCommunity/cancancan/wiki/defining-abilities) for details.
### 2. Check Abilities & Authorization
### 2. Check Abilities
The current user's permissions can then be checked using the `can?` and `cannot?` methods in views and controllers.
......@@ -56,6 +56,14 @@ The current user's permissions can then be checked using the `can?` and `cannot?
See [Checking Abilities](https://github.com/CanCanCommunity/cancancan/wiki/checking-abilities) for more information
### 3. Controller helpers
CanCanCan expects a `current_user` method to exist in the controller.
First, set up some authentication (such as [Devise](https://github.com/plataformatec/devise) or [Authlogic](https://github.com/binarylogic/authlogic)).
See [Changing Defaults](https://github.com/CanCanCommunity/cancancan/wiki/changing-defaults) if you need a different behavior.
### 3.1 Authorizations
The `authorize!` method in the controller will raise an exception if the user is not able to perform the given action.
```ruby
......@@ -65,6 +73,8 @@ def show
end
```
### 3.1 Loaders
Setting this for every action can be tedious, therefore the `load_and_authorize_resource` method is provided to
automatically authorize all actions in a RESTful style resource controller.
It will use a before action to load the resource into an instance variable and authorize it for every action.
......@@ -79,10 +89,11 @@ class ArticlesController < ApplicationController
end
```
See [Authorizing Controller Actions](https://github.com/CanCanCommunity/cancancan/wiki/authorizing-controller-actions) for more information.
See [Authorizing Controller Actions](https://github.com/CanCanCommunity/cancancan/wiki/authorizing-controller-actions)
for more information.
#### Strong Parameters
### 3.2 Strong Parameters
You have to sanitize inputs before saving the record, in actions such as `:create` and `:update`.
......@@ -144,7 +155,7 @@ Finally, it's possible to associate `param_method` with a Proc object which will
See [Strong Parameters](https://github.com/CanCanCommunity/cancancan/wiki/Strong-Parameters) for more information.
### 3. Handle Unauthorized Access
### 4. Handle Unauthorized Access
If the user authorization fails, a `CanCan::AccessDenied` exception will be raised.
You can catch this and modify its behavior in the `ApplicationController`.
......@@ -164,7 +175,7 @@ end
See [Exception Handling](https://github.com/CanCanCommunity/cancancan/wiki/exception-handling) for more information.
### 4. Lock It Down
### 5. Lock It Down
If you want to ensure authorization happens on every action in your application, add `check_authorization` to your `ApplicationController`.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment