Ember Simple Auth's API docs are available here

Ember Simple Auth

Ember Simple Auth is a lightweight library for implementing authentication/ authorization with Ember.js applications. It has minimal requirements with respect to application structure, routes etc. With its pluggable strategies it can support all kinds of authentication and authorization mechanisms.

What does it do?

it manages a client side session and synchronizes that across tabs/ windows
it authenticates users against the application's own server, external providers like Facebook etc.
it authorizes requests to the backend server
it is easily customizable and extensible

How do I use it?

Ember Simple Auth is built around the fundamental idea that users are always using the application in the context of a (client side) session. This session can either be authenticated or not. Ember Simple Auth creates that session, provides functionality to authenticate and invalidate it and also has a set of mixins that provide default implementations for common scenarios like redirecting users to the login if they access a restricted page etc.

Ember Simple Auth can be used as a browserified version that exports a global as well as as an AMD build that can be used e.g. with or Ember CLI. This README covers usage with Ember CLI; using it with Ember App Kit or via the browserified distribution is analogous.

When Ember Simple Auth is included in an application (see the Installation instructions for documentation on the various options for including it into all types of Ember applications), it registers an initializer named 'simple-auth'. Once that initializer has run, the session (see the API docs for Session) will be available in all routes and controllers of the application.

While not necessary, the easiest way to use the session is to include the ApplicationRouteMixin mixin provided by Ember Simple Auth in the application route:

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

export default Ember.Route.extend(ApplicationRouteMixin);

This adds some actions to the application route like authenticateSession and invalidateSession as well as callback actions that are triggered when the session's authentication state changes like sessionAuthenticationSucceeded or sessionInvalidationSucceeded (see the API docs for ApplicationRouteMixin). Displaying e.g. login/logout buttons in the UI depending on the session's authentication state then is as easy as:

{{#if session.isAuthenticated}}
  <a {{ action 'invalidateSession' }}>Logout</a>
{{else}}
  {{#link-to 'login'}}Login{{/link-to}}
{{/if}}

To make a route in the application require the session to be authenticated, there is another mixin that Ember Simple Auth provides and that is included in the respective route (see the API docs for AuthenticatedRouteMixin):

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

export default Ember.Route.extend(AuthenticatedRouteMixin);

This will make the route transition to /login (or a different URL if configured) when the session is not authenticated in the beforeModel method.

Authenticators

Authenticators implement the concrete steps necessary to authenticate the session. An application can have several authenticators for different kinds of authentication mechanisms (e.g. the application's own backend server, external authentication providers like Facebook etc.) while the session is only authenticated with one authenticator at a time (see the API docs for Session#authenticate). The authenticator to use is chosen when authentication is triggered:

this.get('session').authenticate('authenticator:custom', {});

Ember Simple Auth does not include any authenticators in the base library but has extension libraries that can be loaded as needed:

simple-auth-oauth2 provides an OAuth 2.0 authenticator
simple-auth-devise provides an authenticator compatible with the popular Ruby on Rails authentication plugin devise
simple-auth-torii provides an authenticator that wraps the torii library

Implementing a custom Authenticator

Besides the option to use one of the predefined authenticators from the extension libraries, it is easy to implement custom authenticators as well. All that is necessary is to extend the base authenticator and implement three methods (see the API docs for Authenticators.Base).

Custom authenticators have to be registered with Ember's dependency injection container so that the session can retrieve an instance, e.g.:

import Base from 'simple-auth/authenticators/base';

var CustomAuthenticator = Base.extend({
  …
});

Ember.Application.initializer({
  name: 'authentication',
  before: 'simple-auth',
  initialize: function(container, application) {
    container.register('authenticator:custom', CustomAuthenticator);
  }
});

To authenticate the session with a custom authenticator, simply pass the registered factory's name to the session's authenticate method (see the API docs for Session#authenticate):

this.get('session').authenticate('authenticator:custom', {});

or when using one of the controller mixins:

// app/controllers/login.js
import LoginControllerMixin from 'simple-auth/mixins/login-controller-mixin';

export default Ember.Controller.extend(LoginControllerMixin, {
  authenticator: 'authenticator:custom'
});

Also see the API docs for Session#authenticate, LoginControllerMixin and AuthenticationControllerMixin.

Authorizers

If the Ember.js application makes requests to a backend server that requires authorization and an authorizer is configured, Ember Simple Auth sets up an $.ajaxPrefilter that is used to authorize AJAX requests. An authorizer can be configured in the global configuration object:

window.ENV = window.ENV || {};
window.ENV['simple-auth'] = {
  authorizer: 'authorizer:custom'
}

While the authenticator acquires some sort of secret information from an authentication provider when it authenticates the session, the authorizer uses that secret information acquired by the authenticator to authorize subsequent requests, thus the authenticator and authorizer have to fit together. An application always only has one authorizer.

Ember Simple Auth does not include any authorizers in the base library but offers extension libraries that can be loaded in the application as needed:

simple-auth-oauth2 provides an OAuth 2.0 authorizer
simple-auth-devise provides an authorizer compatible with the popular Ruby on Rails authentication plugin devise

Implementing a custom Authorizer

Besides the option to use one of the predefined authorizers from the extension libraries, it is easy to implement custom authorizers as well. All you have to do is to extend the base authorizer and implement one method (see the API docs for Authorizers.Base).

To use a custom authorizer, register it with Ember's container and configure it in the global environment object:

import Base from 'simple-auth/authorizers/base';

var CustomAuthorizer = Base.extend({
  …
});

Ember.Application.initializer({
  name: 'authorization',
  before: 'simple-auth',
  initialize: function(container, application) {
    container.register('authorizer:custom', CustomAuthorizer);
  }
});

window.ENV = window.ENV || {};
window.ENV['simple-auth'] = {
  authorizer: 'authorizer:custom'
}

Cross Origin Authorization

Ember Simple Auth will never authorize cross origin requests so that no secret information gets exposed to third parties. To enable authorization for additional origins (for example if the REST API of the application runs on a different domain than the one the Ember.js application is served from), additional origins can be whitelisted in the configuration (beware that origins consist of protocol, host and port where port can be left out when it is 80 for HTTP or 443 for HTTPS):

window.ENV = window.ENV || {};
window.ENV['simple-auth'] = {
  crossOriginWhitelist: ['http://some.other.domain:1234']
}

Stores

Ember Simple Auth persists the session state so it survives page reloads. There is only one store per application that can be configured in the global configuration object:

window.ENV = window.ENV || {};
window.ENV['simple-auth'] = {
  store: 'simple-auth-session-store:local-storage'
}

Store Types

Ember Simple Auth comes with 2 bundled stores:

`localStorage` Store

The localStorage store (see the API docs for Stores.LocalStorage) stores its data in the browser's localStorage; this is the default store.

Ephemeral Store

The ephemeral store (see the API docs for Stores.Ephemeral) stores its data in memory and thus is not actually persistent. This store is mainly useful for testing. Also the ephemeral store cannot keep multiple tabs or windows in sync as tabs/windows cannot share memory.

A cookie based store is available in the extension library simple-auth-cookie-store.

Implementing a custom Store

Implementing a custom store is as easy as implementing custom authenticators or authorizers. All you have to do is to extend the base store and implement three methods (see the API docs for Stores.Base).

Testing

The Ember Simple Auth Testing extension library provides test helpers for testing applications using Ember Simple Auth.

Examples

To run the examples you need to have node.js and grunt installed. If you have those, simply run:

git clone https://github.com/simplabs/ember-simple-auth.git
cd ember-simple-auth
npm install
grunt server

Open http://localhost:8000/examples to access the examples.

Other Examples

Installation

To install Ember Simple Auth in an Ember.js application there are several options:

Ember CLI

If you're using Ember CLI, just add the ember-cli-simple-auth Ember CLI Addon to your project and Ember Simple Auth will setup itself.

The Ember Simple Auth extension libraries are also available as Ember CLI Addons:

Bower

Ember Simple Auth is also available in the "ember-simple-auth" bower package which includes both a browserified version as well as an AMD build. If you're using the AMD build from bower be sure to require the autoloader:

require('simple-auth/ember');

The browserified version will, like the Ember CLI addon, also setup itself once it is loaded in the application.

Other Options

Download a prebuilt version from the releases page
Build it yourself

Building

To build Ember Simple Auth yourself you need to have node.js and grunt installed. If you have those, simply run:

git clone https://github.com/simplabs/ember-simple-auth.git
cd simple-auth
npm install
grunt dist

After running that you will find the compiled files in the dist directory.

If you want to run the tests as well you also need PhantomJS. You can run the tests with:

grunt test

You can also start a development server by running

grunt server

and then run the tests in the browser at http://localhost:8000.

mewben / ember-simple-auth Goto Github PK