# Identity

Аутентификация и авторизация для Rails приложения.

## Установка

Добавьте строчку в Gemfile приложения:

```ruby
gem 'anadea-identity'
```

и запустите в консоли:

```console
$ bundle
```

Сгенерируйте миграции:

```console
$ rake identity_engine:install:migrations
```

проверьте их и запустите:

```console
$ rake db:migrate
```

## Использование

### Аутентификация

Проверьте маршруты: `rake routes`. Вы увидите набор маршрутов, подобных тем, что
даёт [Devise](https://github.com/plataformatec/devise). Собственно, Identity и
есть не слишком толстая обёртка поверх Devise.

У вас работает логин (через форму email/пароль), регистрация (через форму
email/пароль/подтверждение пароля), восстановление пароля и многое другое.

### Модель User

Вызов `current_user` в контроллере вернёт `Identity::User`, соответствующий
таблице `identity_users`. Не нужно добавлять в эту модель методы и не нужно
добавлять в эту таблицу колонки, кроме тех, которые используются Devise или
Identity. Эту модель следует считать публичным интерфейсом, предоставляеым гемом.

Рекомендуется заводить модели типа `Profile` или `Account` которые будут
"принадлежать" (`belong_to :user, class_name: "Identity::User"`) этой модели
и ссылаться на неё с помощью внешнего ключа.

### Авторизация

Модель `Identity::User` расширена ролями с помощью
[Rolify](https://github.com/RolifyCommunity/rolify). В частности, у вас есть
говорящие за себя методы:

```ruby
user.add_role :manager
user.remove_role :manager
user.has_role? :manager

Identity::User.with_role :manager
```

У вас есть многое другое – смотрите документацию Rolify.

Используйте эти методы в вызовах вашего авторизационного фреймворка, такого, как
[CanCanCan](https://github.com/CanCanCommunity/cancancan).

### Админка

Чтобы получить админку по пользователям, подключите
[ActiveAdmin](https://github.com/activeadmin/activeadmin) и сгенерируйте
конфигурационный файл без генерации пользователей (`--skip-users`).

### Конфигурация

Создайте руби-файл в `config/initializers` со следующим содержимым:

```ruby
Identity.setup do |config|
  config.devise_modules += [:confirmable]
  # и много других конфигурационных опций
end
```

#### Доступные опции

Вы всегда можете узнать полный список конфигурацинных опций и их значения по
умолчанию, ознакомившись [с исходным кодом](lib/identity.rb).

* `config.devise_modules` – модули Devise, которые вы используете. Например,
  выключение `registerable` приведёт к невозможности зарегистрироваться, в том
  числе, исчезнет соответствующая ссылка, а включение `confirmable` приведёт к
  тому, что приложение станет требовать подтверждение адреса электронной почты,
  при условии, что в таблице `identity_users` есть соответствующие колонки
  (по умолчанию нет).

  Вы можете как модифицировать этот массив, так и полностью его переопределить:

  ```ruby
  config.devise_modules += [:confirmable]
  config.devise_modules = [:database_authenticatable, :omniauthable, ...]
  ```

  По умолчанию включены модули database_authenticatable, registerable,
  recoverable, rememberable, trackable и validatable. Если включить хотя бы один
  omniauth provider, автоматически подключится omniauthable. За подробным их
  описанием обратитесь в документацию Devise.

* `config.layout` – макет (layout), используемый формами логина, регистрации и
  прочего. По умолчанию используется главный макет вашего приложения –
  `"application"`.

* `config.auth_routes` – если задать `false`, маршруты подключены не будут и вы
  можете сами подключить их.

* `config.admin_role` – "главная" роль в приложении. Роль, которой можно
  управлять из предлаемой гемом админки, и роль, которая по умолчанию является
  допуском в эту админку.

Вы также можете использовать любые конфигурационные опции самого Devise.
Они будут переданы Devise в точности. Например:

```ruby
config.parent_controller = "ApplicationController"
```

За подробным списком того, что можно сконфигурировать в Devise, обратитесь к его
документации.

#### Сделанные кастомизации в конфигурации Devise.

Мы делаем небольшие изменения в конфигурации Devise по умолчанию. Вы можете это
увидеть в [исходном коде гема](lib/identity/devise_config.rb).

* `config.mailer_sender` – мы достаём это из переменной окружения MAIL_FROM.
* `config.sign_out_via` – GET и только GET. Это должно работать без джаваскрипта.
* `config.parent_controller` – мы не наследуемся от `ApplicationController` вашего
  приложения. Devise предлагает для этого определять методы в
  `ApplicationController`.Если вам нужно переопределить поведение аутентификационных
  контроллеров, мы рекомендуем создать специальный базовый контроллер в
  приложении и указать его в качестве `parent_controller`. Затем определять в
  нём методы типа `after_sign_in_path_for`, как и предлагает Devise.

### Логин через Facebook.

Для того, чтобы включить в приложении логин через Facebook нужно:

* подключить `gem 'omniauth-facebook'` в своем Gemfile.
* указать `config.omniauth :facebook, ENV['FACEBOOK_KEY'], ENV['FACEBOOK_SECRET']`
  в `config/initializers/identity.rb`.
* создать приложение в Facebook можно с помощью [инструкции](https://getsocio.com/Help/How_to_set_up_Facebook_Application).

### Логин через Twitter.

Для того, чтобы включить в приложении логин через Twitter нужно:

* подключить `gem 'omniauth-twitter'` в своем Gemfile.
* указать `config.omniauth :twitter, ENV['TWITTER_KEY'], ENV['TWITTER_SECRET']`
  в `config/initializers/identity.rb`.
* создать приложение в Twitter можно [здесь](https://apps.twitter.com/).

### Логин через Google.

Для того, чтобы включить в приложении логин через Google нужно:

* подключить `gem 'omniauth-google-oauth2'` в своем Gemfile.
* указать `config.omniauth :google_oauth2, ENV['GOOGLE_KEY'], ENV['GOOGLE_SECRET']`
  в `config/initializers/identity.rb`.
* создать приложение в Google можно [здесь](https://console.developers.google.com/project).
* для создания приложения можно воспользоваться [инструкцией](https://developers.google.com/identity/protocols/OpenIDConnect#appsetup)