# Goma 胡麻

An authentication solution for Rails 4.
Currently supports ActiveRecord only.

The API is almost same as [Sorcery](https://github.com/NoamB/sorcery) \[[LICENSE](https://raw.githubusercontent.com/NoamB/sorcery/master/LICENSE.txt)\].

Lots of code are borrowed or shamelessly copied from [Devise](https://github.com/plataformatec/devise) \[[LICENSE](https://raw.githubusercontent.com/plataformatec/devise/master/MIT-LICENSE)\].

Thank maintainers, committers and contributers of above two gems.

Currently, Goma is in early development phase. There must be bugs and lack of functionalities so that it should not be used for production for a while. I will improve my code and write documents as soon as possible.

All sorts of contributions are welcome.

Because I am not good at English, writing documents, corrections, and suggesting better module, class, variable or method names are also welcome.


## About
Goma is an authentication solution for Rails 4 based on Warden. It:

- allows you to use almost same as Sorcery
- supports authentication in routes
- allows you to have multiple models signed in at the same time

It is composed of following modules:

- Password authenticatable
- Omniauthable
- Confirmable
- Recoverable
- Rememberable
- Trackable
- Timeoutable
- Validatable
- Lockable


## Getting started
Goma works with Rails 4. You can add it to your Gemfile with:

```ruby
gem 'goma'
```

Run the bundle command to install it.
After you install Goma and add it to your Gemfile, you need to run the generator:

```console
rails generate goma:install
```

The generator will install an initializer which describes ALL Goma's configuration options and you MUST take a look at it and change options to fit your needs.

When you are done, you are ready to scaffold an entire resource for authentication, from model and migration to controller and views. (but, I'm sorry, working test suites are not included)

```console
rails generate goma:scaffold NAME
```

Replace NAME by the class name used for the applications users, it's frequently `user` but could also be anything you want. This will create a model with a migration, controllers, views, and mailers (that are configured based on the initializer file which is created by `rails generate goma:install`).

Please note that this scaffold generator is just a "better than nothing' thing. It does not include tests and there must be bugs. But if you see the code which is generated by this scaffold, you can see how to use this gem roughly. If you find bugs, please create an issue or send a pull request.


You can also use the following generators.

```
  goma:mailer
  goma:model
  goma:model:oauth
  goma:scaffold:confirmation  # Confirmable
  goma:scaffold:oauth         # Omniauthable
  goma:scaffold:password      # Recoverable
  goma:scaffold:session       # PasswordAuthenticatable
  goma:scaffold:unlock        # Lockable
  goma:scaffold:user
  goma:scaffold_controller
```

For example, you can add a Goma model as follows:

```console
rails generate goma:model MODEL
```


## API summary

```
  # in routes
  current_user # If you have an :admin scope, you can use current_admin
  user_logged_in? # you can specify scope

  # in controllers
  require_login # this is a before filter (default scope)
  require_user_login # ditto. You can specify a scope.
  login(identifier, password, remember_me=false) # You can use multiple identifiers in a field, such as username or email.
  force_login(user) # Login without credentials (same as auto_login in Sorcery gem)
  logout(scope=Goma.config.default_scope) # Logout. you can specify a scope.
  user_logout # ditto
  logged_in? # Available in view
  user_logged_in? # ditto. You can specify a scope.
  current_user # Available in view. If you have an :admin scope, you can use current_admin

  # Password authenticatable
  find_by_identifier # You can find user by authentication key

  # Rememberable
  remember_me! # Goma call this automatically so that, usually, You don't have to call this manually.
  forget_me!   # ditto

  # Confirmable
  User.load_from_activation_token(token)
  User#activate!
  User.load_from_email_confirmation_token(token)
  User#confirm_email!

  # Recoverable
  User.load_from_reset_password_token(token)
  User#send_reset_password_instructions!
  User#change_password!(new_password, new_password_confirmation)

  # Lockable
  User.load_from_unlock_token(token)
  User#lock_access!
  User#unlock_access!
  User#access_locked?
  User#last_attempt?

  # Omniauthable
  User.create_with_omniauth!(omniauth)
  User#fill_with_omniauth # This method is called when creating user object with OmniAuth
  Authentication#fill_with_omniauth # This method is called when creating authentication object with OmniAuth
```


## Authentication in routes
You can use API for routes as follows

```ruby
YourApp::Application.routes.draw do
  constraints current_user do
    root to: 'dashboard#index' # root for login users
  end

  root to: 'home#index'        # root for public
end
```

You can also specify criteria as follows:

```ruby
YourApp::Application.routes.draw do
  constraints current_user { |u| u && u.role == 'admin' } do
    # for admin users
    # The block parameter is current_user, which is nil when user is not logged in.
  end

  constraints current_user { role == 'admin' } do
    # for admin users
    # this is a shortcut of the above.
    # In this case, when user is not logged in, the block is not executed.
  end
end
```