Перевод (рус.) оф. справки по Ember Simple Auth

Ember Simple Auth поддерживает все версии Ember.js старше 1.12.

Ember Simple Auth

Ember Simple Auth это легкая библиотека для реализации механизма аутентификации/авторизации пользователей в приложении Ember.js. Она выставляет минимальные требования к структуре приложения, его маршрутизации и т.п. Благодаря своей расширяемой модульной структуре, она может поддерживать все виды механизмов аутентификации и авторизации пользователей .

Содержание

Базовая информация

Что делает?
Как работает?
Пример приложения

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

Установка
Пошаговое руководство

Основные функции

Служба сессий
Аутентификаторы
Настройка Аутентификатора
Реализация пользовательского Аутентификатора
Авторизаторы
Настройка Авторизатора
Реализация пользовательского Авторизатора
Хранилища сессий
Типы хранилищ
Пользовательская настройка хранилищ
Реализация пользовательских хранилищ
Тестирование

Другие руководства

Управление текущим пользователем

Другие ресурсы

Что делает?

поддерживает сессии на стороне клиента, синхронизирует свое состояние со множеством вкладок/окон приложения.
аутентификация сессии не использует собственный сервер, полагаясь на внешних провайдеров, таких как Facebook и т.п.
направляет запрос авторизации бэкенд серверу
просто настраивается и расширяется

Как работает?

Ember Simple Auth содержит 4-ре основных блока: сессии, хранилище сессий, аутентификаторы, и при необходимости авторизаторы.

Служба сессий это главный интерфейс библиотеки. Она обеспечивает методы для аутентификации и инвалидации сессии, а также для установки и чтения данных сессии.

Хранилище содержит состояние сессии так, что оно сохраняется при перезагрузке страницы. Оно так-же синхронизирует состояние сессии со множеством вкладок и страниц приложения, к примеру, выход пользователя в одном из окон или вкладке повлечет его выход во всех остальных открытых окнах или вкладках.

Аутентификаторы аутентификации сессии. Приложение может поддерживать множество способов аутентификации, отправляя учетные данные пользователя к своему бэкенд серверу, или Facebook, GitHub и т.п.

Авторизаторы используют данные их хранилища, полученные с помощью аутентификатора, для генерации данных авторизации, которые могут быть включены в исходящие запросы, такие как запросы Ember Data.

Пример приложения

Ember Simple Auth содержит пример приложения который реализует полное решение по аутентификации включающее механизмы аутентификации на собственном сервере и с помощью Facebook, авторизацию для запросов Ember Data и вывода ошибок. Ознакомьтесь с этим примером. Для его запуска, выполните следующие команды:

git clone https://github.com/simplabs/ember-simple-auth.git
cd ember-simple-auth
npm install && bower install && ember serve

и перейдите по адресу http://localhost:4200.

Установка

Установить библиотеку довольно просто:

ember install ember-simple-auth

Обновление из ember-cli-simple-auth / pre-1.0 релизов?

1.0 релиз ember-simple-auth содержит много критических изменений, но обновление Просто.

Пошаговое руководство

После того, как библиотека установлена, служба сессий может быть внедрена везде, где это необходимо приложению Для того чтобы к примеру отображать кнопку входа/выхода в зависимости от состояния текущей сессии, вставьте службу в соответствующий контроллер, или компонент, и запросите ее свойство isAuthenticated в шаблоне

// app/controllers/application.js
import Ember from 'ember';

export default Ember.Controller.extend({
  session: Ember.inject.service('session')

  …
});

{{!-- app/templates/application.hbs --}}
<div class="menu">
  …
  {{#if session.isAuthenticated}}
    <a {{action 'invalidateSession'}}>Logout</a>
  {{else}}
    {{#link-to 'login'}}Login{{/link-to}}
  {{/if}}
</div>
<div class="main">
  {{outlet}}
</div>

В экшене invalidateSession вызовите метод службы сессий invalidate для инвалидации сессии и выхода пользователя из системы:

// app/controllers/application.js
import Ember from 'ember';

export default Ember.Controller.extend({
  session: Ember.inject.service('session'),

  …

  actions: {
    invalidateSession() {
      this.get('session').invalidate();
    }
  }
});

Для аутентификации сессии, служба сессий содержит метод authenticate, который принимает имя используемого аутентификатора, а так-же остальные, специфичные ему аргументы. Для определения аутентификатора, добавьте новый файл в app/authenticators и наследуйте один из существующих аутентификаторов, на пример:

// app/authenticators/oauth2.js
import OAuth2PasswordGrant from 'ember-simple-auth/authenticators/oauth2-password-grant';

export default OAuth2PasswordGrant.extend();

В этом случае, форма входа будет следующей:

{{!-- app/templates/login.hbs --}}
<form {{action 'authenticate' on='submit'}}>
  <label for="identification">Login</label>
  {{input id='identification' placeholder='Enter Login' value=identification}}
  <label for="password">Password</label>
  {{input id='password' placeholder='Enter Password' type='password' value=password}}
  <button type="submit">Login</button>
  {{#if errorMessage}}
    <p>{{errorMessage}}</p>
  {{/if}}
</form>

Сессия может быть аутентифицированаp методом службы сессий authenticate:

// app/controllers/login.js
import Ember from 'ember';

export default Ember.Controller.extend({
  session: Ember.inject.service('session'),

  actions: {
    authenticate() {
      let { identification, password } = this.getProperties('identification', 'password');
      this.get('session').authenticate('authenticator:oauth2', identification, password).catch((reason) => {
        this.set('errorMessage', reason.error || reason);
      });
    }
  }
});

Служба сессий также обеспечивает authenticationSucceeded и invalidationSucceeded события которые срабатывают при удачном открытии или закрытии сессии (они происходят не только когда пользователь отправляет форму входа или нажмет кнопку выхода из системы, но и когда сессия открыта или закрыта в другом окне или вкладке приложения). **Для получения этих событий автоматически, просто подмешайте ApplicationRouteMixin в маршрутизатор приложения:

// app/routes/application.js
import Ember from 'ember';
import ApplicationRouteMixin from 'ember-simple-auth/mixins/application-route-mixin';

export default Ember.Route.extend(ApplicationRouteMixin);

ApplicationRouteMixin автоматически отображает события сессии в sessionAuthenticated и sessionInvalidated методах, которые он реализует. Так, sessionAuthenticated метод осуществит переход по указанному маршруту, в то время как sessionInvalidated метод перезагрузит страницу для очистки всех потенциально конфиденциальных данных из памяти. Для того, что-бы маршрут приложения был доступен только в аутентифицированной сессии, подмешайте AuthenticatedRouteMixin в соответствующий маршрут:

// app/routes/protected.js
import Ember from 'ember';
import AuthenticatedRouteMixin from 'ember-simple-auth/mixins/authenticated-route-mixin';

export default Ember.Route.extend(AuthenticatedRouteMixin);

Это создаст маршрут (и все суб-маршруты) перехода к login маршруту, если сеанс не прошел проверку подлинности. Добавьте login маршрут в маршрутизаторе следующим образом:

// app/router.js
Router.map(function() {
  this.route('login');
}

Маршрут перехода, когда сеанс не прошел проверку подлинности, может быть настроен отличным отlogin.

Для сокрытия маршрута от несанкционированного доступа, при прохождении сессией проверки (к примеру, это имеет смысл для маршрутов входа и регистрации), подмешайте UnauthenticatedRouteMixin в соответствующий маршрут.

Для того что бы добавить авторизационную информацию в исходящие API запросы приложения, необходимо определить авторизатор. Для этого, добавьте новый файл в app/authorizers, например:

// app/authorizers/oauth2.js
import OAuth2Bearer from 'ember-simple-auth/authorizers/oauth2-bearer';

export default OAuth2Bearer.extend();

и используйте это с помощью метода authorize службы сессий, например:

this.get('session').authorize('authorizer:oauth2', (headerName, headerValue) => {
  const headers = {};
  headers[headerName] = headerValue;
  Ember.$.ajax('/secret-data', { headers });
});

Чтобы включить авторизацию во все запросы Ember Data если сессия аутентифицирована, подмешайте DataAdapterMixin в адаптер приложения:

// app/adapters/application.js
import DS from 'ember-data';
import DataAdapterMixin from 'ember-simple-auth/mixins/data-adapter-mixin';

export default DS.JSONAPIAdapter.extend(DataAdapterMixin, {
  authorizer: 'authorizer:oauth2'
});

Служба сессий

Служба сессий это главный интерфейс библиотеки. Он реализует authenticate, invalidate и authorize методы также, как события сессий, как показано выше.

Она обеспечивает isAuthenticated, и data свойства. Последние могу быть использованы для получения и установки данных сессии. В то время как специальная authenticated секция содержит данные аутентифицированной сессии доступными только для чтения, все остальные секции данных доступны для записи, и останутся в сессии после закрытия.

Это применяется для хранения на стороне клиента всех видов данных, нуждающихся в синхронизации между вкладками окнами, к примеру:

this.get('session').set('data.locale', 'de');

Аутентификаторы

Аутентификаторы реализуют конкретные шаги, необходимые для аутентификации сессии. Приложение может содержать несколько аутентификаторов для различных аутентификационных механизмов (к примеру: свой бэкенд сервер приложения; внешние аутентификаторы, такие как Facebook, GitHub и т.п.), во время одного сеанса, проверка подлинности осуществляется одним из них.

Аутентификатор, выбранный при аутентификации, инициируется именем, которым он зарегистрирован в контейнере Ember:

this.get('session').authenticate('authenticator:some');

Ember Simple Auth содержит 3 аутентификатора:

OAuth2PasswordGrantAuthenticator: OAuth 2.0 аутентификатор реализующий "Resource Owner Password Credentials Grant Type"
DeviseAuthenticator: аутентификатор, поддерживающий Ruby on Rails рлагин devise
ToriiAuthenticator: аутентификатор обертка для torii library

Для использования любого из них, определите новый аутентификатор в app/authenticators, наследующий от Ember Simple Authauthenticator.

// app/authenticators/oauth2.js
import OAuth2PasswordGrant from 'ember-simple-auth/authenticators/oauth2-password-grant';

export default OAuth2PasswordGrant.extend();

и вызовите метод службы сессий authenticate с соответствующим именем, при необходимости указав остальные специфичные аргументы:

this.get('session').authenticate('authenticator:some', data);

Настройка Аутентификатора

Аутентификаторы легко настраиваются под себя, путем изменения соответствующих свойств, к примеру:

// app/authenticators/oauth2.js
import OAuth2PasswordGrant from 'ember-simple-auth/authenticators/oauth2-password-grant';

export default OAuth2PasswordGrant.extend({
  serverTokenEndpoint: '/custom/endpoint'
});

Реализация пользовательского Аутентификатора

Помимо расширения одного из предопределенных авторизаторов, в приложении можно реализовать свой собственный. Для этого, наследуйте имеющийся abstract base authenticator и переопределите метод authenticate, restore, а при необходимости, и invalidate:

// app/authenticators/custom.js
import Base from 'ember-simple-auth/authenticators/base';

export default Base.extend({
  restore(data) {
    …
  },
  authenticate(options) {
    …
  },
  invalidate(data) {
    …
  }
});

Авторизаторы

Авторизаторы используют данные сессии, полученные аутентификатором, для построения данных авторизации, которые могут быть включены в исходящие сетевые запросы. Так как авторизатор зависим от данных получаемых аутентификатором, авторизаторы и аутентификаторы должны соответствовать друг другу.

Ember Simple Auth содержит 2 авторизатора:

OAuth2BearerAuthorizer: OAuth 2.0 авторизатор, который использует Bearer токены
DeviseAuthorizer: авторизатор, поддерживающий поппулярный Ruby on Rails плагин devise

Для использования любого из них, определите новый авторизатор в app/authorizers, наследующий от Ember Simple Auth authorizer

// app/authorizers/oauth2.js
import OAuth2Bearer from 'ember-simple-auth/authorizers/oauth2-bearer';

export default OAuth2Bearer.extend();

и вызовите метод службы сессий authorize с соответствующим именем:

this.get('session').authorize('authorizer:some', (/*authorization data*/) => {
  // Use authorization data
});

В отличие от предыдущих версий Ember Simple Auth, авторизация больше не будет происходить автоматически для всех запросов, но должна быть инициирована в явном виде как служба. При использовании Ember Data, можно использовать примесь DataAdapterMixin в адаптере, для автоматической авторизации всех API запросов:

// app/adapters/application.js
import DS from 'ember-data';
import DataAdapterMixin from 'ember-simple-auth/mixins/data-adapter-mixin';

export default DS.JSONAPIAdapter.extend(DataAdapterMixin, {
  authorizer: 'authorizer:some'
});

Настройка Авторизатора

Авторизаторы легко настраиваются под себя, путем изменения соответствующих свойств, к примеру:

// app/authorizers/devise.js
import DeviseAuthorizer from 'ember-simple-auth/authorizers/devise';

export default DeviseAuthorizer.extend({
  identificationAttributeName: 'login'
});

Реализация пользовательского Авторизатора

Помимо расширения одного из предопределенных авторизаторов, в приложении можно реализовать свой собственный. Для этого, наследуйте имеющийся abstract base authorizer и переопределите метод authorize:

// app/authorizers/custom.js
import Base from 'ember-simple-auth/authorizers/base';

export default Base.extend({
  authorize(sessionData, block) {
    …
  }
});

Хранилища сессий

Ember Simple Auth сохраняет состояние сессии с помощью хранилища сессий, так они выживают при перезагрузках страниц Существует только одно хранилище для отдельного приложения, которое определяется в app/session-stores/application.js:

// app/session-stores/application.js
import Cookie from 'ember-simple-auth/session-stores/cookie';

export default Cookie.extend();

Если хранилище не определено, то по умолчанию, будет использовано адаптивное хранилище, которое применяет localStorage если доступно, или cookie, если нет. Для настройки адаптивного хранилища, наследуйте его в пользовательском хранилище, в файле app/session-stores/application.js и переопределите необходимые свойства.

Типы хранилищ

Ember Simple Auth содержит 4-ре типа хранилищ сессий пользователей:

Адаптивное хранилище

Адаптивное хранилище использует для хранения данных локальное хранилище браузера, или куки если локальное хранилище недоступно **Это тип хранилища по умолчанию.

Локальное хранилище

Локальное хранилище хранит данные в локальном хранилище браузера. Используется адаптивным хранилищем, если доступно.

Cookie хранилище хранит данные в куках. Используется адаптивным хранилищем, если недоступно локальное хранилище.

Эфемерное хранилище

Эфемерное хранилище хранит данные в памяти, не предназначенно для длительного хранения но удобно для тестирования. Так-же оно не синхронизирует несколько окон/вкладок приложения.

Пользовательская настройка хранилищ

Хранилище сессий легко настраивается под себя, путем изменения соответствующих свойств, к примеру:

// app/session-stores/application.js
import AdaptiveStore from 'ember-simple-auth/session-stores/adaptive';

export default AdaptiveStore.extend({
  cookieName: 'my-apps-session-cookie'
});

Реализация пользовательских хранилищ

Кроме использования одного из предопределенных хранилищ сессий, в приложении можно реализовать свое собственное хранилище. Для того, что-бы сделать это, наследуйте abstract base session store который содержиться в Ember Simple Auth, и реализует persist, restore и clear методы:

// app/session-stores/application.js
import Base from 'ember-simple-auth/session-stores/base';

export default Base.extend({
  persist() {
    …
  },

  restore() {
    …
  }
});

Тестирование

Ember Simple Auth предоставляется с набором хелперов для тестов, которые можно использовать в приемочном тестировании:

currentSession(app): возвращает текущую сессию.
authenticateSession(app, sessionData): аутентификаторы сессии; необязательный аргумент sessionData может быть использован для имитации ответа аутентификатора - к примеру, токена..
invalidateSession(app): не валидная сессия.

Хелперы для тестов импортируются в пространство имен приложения из модуля helpers/ember-simple-auth:

// tests/acceptance/…
import { currentSession, authenticateSession, invalidateSession } from '<app-name>/tests/helpers/ember-simple-auth';

Другие руководства

Управление текущим пользователем

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

Ember Simple Auth конфигурируется в секции 'ember-simple-auth' файла config/environment.js например:

js ENV['ember-simple-auth'] = { baseURL: 'path/to/base/url' };

Обращайтесь к API документации для ознакомления с доступными настройками.

Лицензия

Ember Simple Auth разрабатывается simplabs GmbH/Marco Otte-Witte при поддержке сообщества. Лицензия: MIT License.

Ember Simple Auth не является частью официального Ember.js и не поддерживается основной командой Ember.js.

Wiki

ember2drupal / EmberSimpleAuth