README.md in simple_auth-3.0.0 vs README.md in simple_auth-3.1.0
- old
+ new
@@ -1,28 +1,32 @@
# Simple Auth
-[](https://travis-ci.org/fnando/simple_auth)
-[](https://codeclimate.com/github/fnando/simple_auth)
-[](http://badge.fury.io/rb/simple_auth)
+[](https://travis-ci.org/fnando/simple_auth)
+[](https://codeclimate.com/github/fnando/simple_auth)
+[](https://codeclimate.com/github/fnando/simple_auth/coverage)
+[](https://rubygems.org/gems/simple_auth)
+[](https://rubygems.org/gems/simple_auth)
-SimpleAuth is an authentication library to be used when everything else is just too complicated.
+SimpleAuth is an authentication library to be used when everything else is just
+too complicated.
-This library only handles session. You have to implement the authentication strategy as you want (e.g. in-site authentication, OAuth, etc).
+This library only handles session. You have to implement the authentication
+strategy as you want (e.g. in-site authentication, OAuth, etc).
-Rails 4.2+ running over Ruby 2.1+ is required.
-
## Installation
Just the following line to your Gemfile:
gem "simple_auth"
Then run `rails generate simple_auth:install` to copy the initializer file.
## Usage
-The initializer will install the required helper methods on your controller. So, let's say you want to support `user` and `admin` authentication. You'll need to specify the following scope.
+The initializer will install the required helper methods on your controller. So,
+let's say you want to support `user` and `admin` authentication. You'll need to
+specify the following scope.
```ruby
# config/initializers/simple_auth.rb
SimpleAuth.setup do |config|
config.scopes = %i[user admin]
@@ -31,11 +35,14 @@
config.install_helpers!
end
```
-Session is valid only when `Controller#authorized_#{scope}?` method returns `true`, which is the default behavior. You can override these methods with your own rules; the following example shows how you can authorize all e-mails from `@example.com` to access the admin dashboard.
+Session is valid only when `Controller#authorized_#{scope}?` method returns
+`true`, which is the default behavior. You can override these methods with your
+own rules; the following example shows how you can authorize all e-mails from
+`@example.com` to access the admin dashboard.
```ruby
class Admin::DashboardController < ApplicationController
private
def authorized_admin?
@@ -68,14 +75,36 @@
redirect_to root_path
end
end
```
-First thing to notice is that simple_auth doesn't care about how you authenticate. You could easily set up a different authentication strategy, e.g. API tokens. The important part is assign the `record:` and `scope:` options. The `return_to` helper will give you the requested url (before the user logged in) or the default url.
+First thing to notice is that SimpleAuth doesn't care about how you
+authenticate. You could easily set up a different authentication strategy, e.g.
+API tokens. The important part is assigning the `record:` and `scope:` options.
+The `return_to` helper will give you the requested url (before the user logged
+in) or the default url.
-Same thing applies to destroying a session. You can just reset it, calling `reset_session`.
+SimpleAuth uses [GlobalID](https://github.com/rails/globalid) as the session
+identifier. This allows using any objects that respond to `#to_gid`, including
+namespaced models and POROs.
-You can restrict access by using 2 macros. Use `redirect_logged_#{scope}` to avoid rendering a page for logged user.
+```ruby
+session[:user_id]
+#=> gid://myapp/User/1
+```
+
+If you need to locate a record using such value, you can do it by calling
+`GlobalID::Locator.locate(session[:user_id])`
+
+### Logging out users
+
+Logging out a user is just as simple; all you have to do is calling the regular
+`reset_session`.
+
+### Restricting access
+
+You can restrict access by using 2 macros. Use `redirect_logged_#{scope}` to
+avoid rendering a page for logged user.
```ruby
class SignupController < ApplicationController
before_action :redirect_logged_user
end