Ember Simple Auth's API docs are available here
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.
- it manages a client side session and synchronizes that across tabs/ windows
- it authenticates the session against the application's own server, external providers like Facebook etc.
- it authorizes requests to backend servers
- it is easily customizable and extensible
Ember Simple Auth can be used as a browserified version that exports a global as well as as an AMD build or an Ember CLI Addon. 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, controllers and components of the application.
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.
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 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}}
In the invalidateSession
action simply call the session's invalidate
method:
invalidateSession: function() {
this.get('session').invalidate();
}
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.
To prevent a route from being accessed when the session is authenticated (which
makes sense for the login
route for example), use the
UnauthenticatedRouteMixin
).
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:some', {});
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
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
),
e.g.:
// app/authenticators/custom.js
import Base from 'simple-auth/authenticators/base';
export default Base.extend({
restore: function(data) {
…
},
authenticate: function(options) {
…
},
invalidate: function(data) {
…
}
});
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', {});
Note that when you're not using Ember CLI the authenticator will not be registered with the container automatically and you need to do that in an initializer:
// app/initializers/authentication.js
import CustomAuthenticator from '../authenticators/custom';
export default {
name: 'authentication',
before: 'simple-auth',
initialize: function(container, application) {
application.register('authenticator:custom', CustomAuthenticator);
}
};
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 application's
environment object:
//config/environment.js
ENV['simple-auth'] = {
authorizer: 'simple-auth-authorizer:oauth2-bearer'
}
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
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
).
// app/authorizers/custom.js
import Base from 'simple-auth/authorizers/base';
export default Base.extend({
authorize: function(jqXHR, requestOptions) {
…
}
});
and configure it on the application's environment object:
//config/environment.js
ENV['simple-auth'] = {
authorizer: 'authorizer:custom'
}
Note that when you're not using Ember CLI the authorizer will not be registered with the container automatically and you need to do that in an initializer:
// app/initializers/authentication.js
import CustomAuthorizer from '../authorizers/custom';
export default {
name: 'authentication',
before: 'simple-auth',
initialize: function(container, application) {
application.register('authorizer:custom', CustomAuthorizer);
}
};
Ember Simple Auth will only authorize cross origin requests when the origin has been whitelisted beforehand 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):
//config/environment.js
ENV['simple-auth'] = {
crossOriginWhitelist: ['http://some.other.domain:1234']
}
Whitelist all domains by specifying *
(this should be used carefully of
course).
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 application's environment object:
//config/environment.js
ENV['simple-auth'] = {
store: 'simple-auth-session-store:local-storage'
}
Ember Simple Auth comes with 2 bundled stores:
The localStorage
store (see the
API docs for Stores.LocalStorage
)
stores its data in the browser's localStorage
; this is the default 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 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
).
The Ember Simple Auth Testing extension library provides test helpers for testing applications using Ember Simple Auth.
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.
- Ember App Kit
- Ember Simple Auth with Rails 4
- Ember Simple Auth with ember-cli and the Devise authenticator/authorizer
To install Ember Simple Auth in an Ember.js application there are several options:
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:
- ember-cli-simple-auth-oauth2
- ember-cli-simple-auth-devise
- ember-cli-simple-auth-cookie-store
- ember-cli-simple-auth-torii
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.
- Download a prebuilt version from the releases page
- Build it yourself
If you're not using Ember CLI, Ember Simple Auth will read all configuration
values from window.ENV['simple-auth']
instead of the ENV
object exported
from Ember CLI's config/environment.js
. file
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 ember-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/test/.
Ember Simple Auth is developed by and © simplabs/Marco Otte-Witte and contributors. It is released under the MIT License.
Ember Simple Auth is not an official part of Ember.js and is not maintained by the Ember.js Core Team.