simplabs

A few weeks ago a new version of the "official" ember deployment solution ember-cli-deploy was released:

ember-cli-deploy 0.5 is now released and ready for use with a great docs site and already-rich plugin ecosystem: https://t.co/6yhjmjQrYD

— Luke Melia (@lukemelia) 29. Oktober 2015

Aaron Chambers and me gave detailed walkthroughs of the basic ideas behind the pipeline at the Ember-London and Ember.js-Munich meetups respectively.

The new release encourages heavy use of deploy plugins that all implement different parts of a deployment via hooks and are themselves Ember CLI addons. What wasn't available though was a plugin for notifying external webservices (e.g. an error-tracking service) during or after deployments so we decided to write one.

Introducing ember-cli-deploy-notifications

ember-cli-deploy-notifications makes it easy to notify external services by adding them to a notifications.services.<service> property in config/deploy.js. First you have to install the addon:

ember install ember-cli-deploy-notifications

The second step is to configure the services that you want to notify while executing the deployment pipeline.

// config/deploy.js module.exports = function(deployTarget) { var ENV = { // ... notifications: { services: { bugsnag: { didActivate: { apiKey: '' } } } } }; return ENV; }

Every time a new revision gets activated now by ember-cli-deploy, ember-cli-deploy-notifications will sent a POST request to the bugsnag service to notify it of the newly activated deployment revision.

Customization

We figured out that there are a lot of different internal and external services that users of ember-cli-deploy wanted to notify when executing the deploy pipeline. Thus we wanted to make ember-cli-deploy-notifications as flexible as possible but still keep things easy and simple for the most basic use cases.

Based on that assumption we came up with the idea of "preconfigured" and "custom" services.

Custom services

Services need to be configured with values for url, headers, method and body. We figured out that these are all the necessary parts of a webservice request that you need to be able to customize.

Additionally you need to provide a property named the same as the hook that you want the service to be notified on when running through the deploy pipeline (as we wouldn't know when to notify a service otherwise):

// config/deploy.js module.exports = function(deployTarget) { var ENV = { // ... notifications: { services: { simplabs: { url: 'https://notify.simplabs.com/deploy', headers: {}, method: 'POST', body: function(context) { var deployer = context.deployer; return { secret: 'supersecret', deployer: deployer } }, didActivate: true } } } }; return ENV; };

url, headers, method and body are the basic ideas behind the service abstraction in ember-cli-deploy-notifications but to keep things simple you don't have to provide headers and method for every custom service as these properties will default to {} and 'POST' respectively.

As you can see service configuration properties can either be defined directly or generated dynamically based on the deployment context. this will always point to the service's configuration itself in all of these functions which enables you to do things like this:

// config/deploy.js module.exports = function(deployTarget) { var ENV = { // ... notifications: { services: { slack: { webhookURL: '' url: function() { return this.webhookURL; }, body: { text: 'A new revision was deployed!' }, didActivate: true } } } }; return ENV; };

The configuration properties named the same as ember-cli-deploy's pipeline-hooks can also be used to override configuration defaults on a per hook basis:

// config/deploy.js module.exports = function(deployTarget) { var ENV = { // ... notifications: { services: { slack: { url: '', body: { text: 'A new revision was deployed!' }, didActivate: true, didFail: { body: { text: 'Deployment failed!' } } } } } }; return ENV; };

Preconfigured services

As we wanted to make it as easy as possible to get started with ember-cli-deploy-notifications there are already some preconfigured services.

Preconfigured services differ from custom services in the fact that the community has already provided a default configuration for these services. For example the popular error tracking service bugsnag is already preconfigured which makes it easy to use out of the box with ember-cli-deploy-notifications:

// config/deploy.js module.exports = function(deployTarget) { var ENV = { // ... notifications: { services: { bugsnag: { apiKey: '', didActivate: true, } } } }; return ENV; };

There is also a preconfigured service for slack.

Next Steps

We are excited to share this small ember-cli-deploy plugin with the ember community and would like to hear your feedback! We are already using it in client projects and, though pretty small, found it to be a very useful addition to our deployment workflow.

With Ember Simple Auth 1.0.0 having been released a few days ago, a lot of people will want to upgrade their applications to it so they can finally make the switch to Ember.js 2.0. While quite a big part of the public API has been changed in 1.0.0, updating an application from Ember Simple Auth 0.8.0 or earlier versions is actually not as hard as it might appear at first glance. This post explains the steps that are necessary to bring an application to 1.0.0.

As 1.0.0 marks the first stable release of Ember Simple Auth, upcoming versions will adhere to the Semantic Versioning rule of not including breaking changes in patch level or minor releases. In fact, Ember Simple Auth will follow Ember's example and only make additive, backwards compatible changes in all 1.x releases and only remove deprecated parts of the library in the next major release.

Uninstall previous versions

Ember Simple Auth 1.0.0 is only distributed as an Ember CLI Addon and drops the previous bower distribution as well as the individual ember-cli-simple-auth-* packages. The first step when upgrading to 1.0.0 is to uninstall these packages from the application. To do that simply remove the ember-simple-auth package from bower.json as well as all ember-cli-simple-auth-* packages from packages.json.

Install 1.0.0

Once the previous versions are uninstalled, install the 1.0.0 release:

ember install ember-simple-auth

Fix the imports

With 1.0.0 all modules that it defines now live in the ember-simple-auth namespace as opposed to the simple-auth namespace of previous versions. All the import statements that import code from Ember Simple Auth need to be updated accordingly, e.g.

import ApplicationRouteMixin from 'simple-auth/mixins/application-route-mixin';

becomes

import ApplicationRouteMixin from 'ember-simple-auth/mixins/application-route-mixin';

Also the modules for the OAuth 2.0 authenticator and authorizer have been renamed from just oauth2 to oauth2-password-grant and oauth2-bearer respectively so that 'simple-auth/authenticators/oauth2' is now 'ember-simple-auth/authenticators/oauth2-password-grant' and 'simple-auth/authorizers/oauth2' is now 'ember-simple-auth/authorizers/oauth2-bearer'.

Inject the session service

With Ember Simple Auth 1.0.0 the session is no longer automatically injected into all routes, controllers and components but instead is now available as an Ember.Service so in all routes, controllers and components that use the session (or back a template that uses it), that session service needs to be injected, e.g.:

import Ember from 'ember'; export default Ember.Controller.extend({ session: Ember.inject.service() });

Define Authenticators and Authorizers

Ember Simple Auth 1.0.0 does not automatically merge all the predefined authenticators and authorizers into the application anymore but instead requires authenticators and authorizers the application actually uses to be defined explicitly. So if you e.g. were previously using the OAuth 2.0 authenticator simply define an authenticator that extends the OAuth 2.0 authenticator in app/authenticators:

// app/authenticators/oauth2.js import OAuth2PasswordGrant from 'ember-simple-auth/authenticators/oauth2-password-grant'; export default OAuth2PasswordGrant.extend({ serverTokenRevocationEndpoint: '/revoke' });

In addition to the renamed module, the signature of the OAuth 2.0 authenticator has changed as well so that it now expects dedicated arguments for the user's identification and password instead of one object containing both values, so

const credentials = this.getProperties('identification', 'password'); this.get('session').authenticate('authenticator:oauth2', credentials);

becomes

const { identification, password } = this.getProperties('identification', 'password'); this.get('session').authenticate('authenticator:oauth2', identification, password);

Also authenticators and authorizers are not configured via config/environment.js anymore but instead the respective properties are simply overridden in the extended classes as for the serverTokenRevocationEndpoint property in the example above.

Setup authorization

Ember Simple Auth's old auto-authorization mechanism was complex (especially when working with cross origin requests where configuring the crossOriginWhitelist was causing big problems for many people) and has been removed in 1.0.0. Instead authorization is now explicit. To authorize a block of code use the session service's authorize method, e.g.:

this.get('session').authorize('authorizer:oauth2-bearer', (headerName, headerValue) => { xhr.setRequestHeader(headerName, headerValue); });

If the application uses Ember Data, you can authorize all of the requests it sends to the API by using the new DataAdapterMixin, e.g.:

// 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:application' });

Migrating custom sessions

While previous versions of Ember Simple Auth allowed to configure a custom session class in order to add properties and methods to the session, Ember Simple Auth 1.0.0 makes the session private and only exposes the session service. In order to migrate a custom session class to work with the service there are 2 options.

Extend the session service

You can simply extend the session service and add custom properties and methods in the subclass, e.g.:

// app/services/session.js import Ember from 'ember'; import DS from 'ember-data'; import SessionService from 'ember-simple-auth/services/session'; export default SessionService.extend({ store: Ember.inject.service(), account: Ember.computed('data.authenticated.account_id', function() { const accountId = this.get('data.authenticated.account_id'); if (!Ember.isEmpty(accountId)) { return DS.PromiseObject.create({ promise: this.get('store').find('account', accountId) }); } }) });

Create dedicated services

You can also create dedicated services that use the session service internally, e.g.:

import Ember from 'ember'; import DS from 'ember-data'; export default Ember.Service.extend({ session: Ember.inject.service('session'), store: Ember.inject.service(), account: Ember.computed('session.data.authenticated.account_id', function() { const accountId = this.get('session.data.authenticated.account_id'); if (!Ember.isEmpty(accountId)) { return DS.PromiseObject.create({ promise: this.get('store').find('account', accountId) }); } }) });

In this case the session service remains unchanged and whenever you need the currently authenticated account you'd use the session-account service to get that.

Both solutions work fine but the latter results in cleaner code and better separation of concerns.

Session Stores

Previous versions of Ember Simple Auth allowed the session store to be configured in config/environment.js. Ember Simple Auth 1.0.0 removes that configuration setting and will always use the 'application' session store. If not overridden by the application that session store will be an instance of the new AdaptiveStore that internally uses the LocalStorageStore if localStorage storage is available and the CookieStore if it is not. To customize the application store, define it in app/session-stores/application.js, extend a predefined session store and customize properties (as done for authenticators and authorizers as described above) or implement a fully custom store, e.g.:

// app/session-store/application.js import CookieStore from 'ember-simple-auth/session-stores/cookie'; export default CookieStore.extend({ cookieName: 'my_custom_cookie_name });

Ember Simple Auth 1.0.0 will also automatically use the EphemeralStore when running tests so there is no need anymore to configure that for the test environment (in fact the configuration setting has been removed).

Update acceptance tests

While previous versions of Ember Simple Auth automatically injected the test helpers, version 1.0.0 requires them to be imported in the respective acceptance tests, e.g.:

import { invalidateSession, authenticateSession, currentSession } from '../helpers/ember-simple-auth';

Also they now take the application instance as a first argument so instead of

authenticateSession();

one would now write

authenticateSession(App);

Update the application route if necessary

The ApplicationRouteMixin in Ember Simple Auth 1.0.0 now only defines the two methods sessionAuthenticated and sessionInvalidated as opposed to the previous four actions. If the application overrides any of these actions it would now have to override these methods.

Wrapping up

We are happy to announce the first public release of the rails_api_auth gem. rails_api_auth is a lightweight Rails Engine that implements the _"Resource Owner Password Credentials Grant"_ OAuth 2.0 flow as well as Facebook authentication and is built for usage in API projects. If you're building a client side application with e.g. a browser MVC like Ember.js (where you might be using Ember Simple Auth which works great with rails_api_auth of course), a mobile app or anything else that's backed by a Rails-based API, rails_api_auth is for you.

Why another Authentication Engine?

Of course there are lots of authentication libraries for Rails already. While all of them are great and work well especially with traditional server rendered applications none of them are really lightweight and simple. In fact they are all pretty massive - all of them provide a lot more functionality than rails_api_auth does of course though. However, when you're building an API and all you want is to provide a mechanism for users to exchange their login credentials for a token and then validate that incoming requests include a valid token in the Authorization header, you just don't need most of that functionality and could use sth. much smaller, easier to understand and debug. In fact, rails_api_auth is basically just the controller and model plus a few helper methods that we use in most of our Rails-based API projects. When we realized we were reimplementing those in most projects we decided to extract them into an engine so they could be easily reused and also shared with others.

The "Resource Owner Password Credentials Grant"

The "Resource Owner Password Credentials Grant" flow is really just a formalization of the process where the users send their login credentials to the server and in return receive a token (we're using random Bearer tokens for now but will also support JSON Web Tokens (JWTs) soon). That token will then be sent in the Authorization header in subsequent requests so that the server can validate the user's identity. The engine stores these credentials and tokens in Login models. Storing that data in a separate model instead of the application's User model keeps the authentication code clearly separated from user profile data etc. and makes the engine easier to integrate. The Login model can be associated to the application's User model by setting the user_model_relation configuration value (see the README for more info on configuring the engine).

The "Resource Owner Password Credentials Grant" flow defines 2 endpoints - one for obtaining a token and one for revoking it (the 2nd one is actually optional as users can be logged without any server interaction by simply deleting the token on the client):

token POST /token oauth2#create revoke POST /revoke oauth2#destroy

Both of these endpoints are already implemented in the engine. To validate that incoming requests include a valid Bearer token, the library defines the authenticate! method that is easily added as a before_action in authenticated-only controllers:

class SecretThingsController < ApplicationController include RailsApiAuth::Authentication before_filter :authenticate! end

When a valid token is present and a Login with that token exists, the method will save that in the current_login attribute so that it can be used in the controller. If no token is present or no Login exists for the token, it will respond with 401 and prevent the actual controller action from being executed. The authenticate! method can also be called with a block to add custom checks for the user's authentication state.

Facebook Authentication

Another common way of authenticating users that we're using in many projects is Facebook authentication. The typical flow for this authentication type in web applications is opening a popup that displays Facebook's login page and - after that - a page where the users grants your application access to their profile data. Once the user did that, Facebook will redirect to the web app and include an auth_code in the response that the web app then takes and sends to its API to validate it and exchange it for a Bearer token.

rails_api_auth implements the API part of that in the POST /token route as well - see the demo project for an example of how to use it.

Feedback and contributions welcome!

The first beta of Ember Simple Auth 1.0 will be released soon and this post provides a first look at the changes that come with it.

Ember 2.0 Compatibility

The biggest improvement of course is that the library will be compatible with Ember 2.0 (which is mainly due to the fact that it now uses instance initializers for a majority of its setup work). Also when using Ember 1.13 you shouldn't be seeing any deprecations triggered by Ember Simple Auth anymore so that the upgrade path to 2.0 is clean.

Session as a Service

While previous versions of Ember Simple Auth injected the session into routes, controllers and components, Ember Simple Auth 1.0 drops that and instead provides a new Session service that encapsulates all access to the actual session and can simply be injected wherever necessary, e.g.:

import Ember from 'ember'; const { service } = Ember.inject; export default Ember.Component.extend({ session: service('session'), actions: { authenticate() { let data = this.getProperties('identification', 'password'); this.get('session').authenticate('authenticator:oauth2-password-grant', data).catch((reason) => { this.set('errorMessage', reason.error); }); } } });

It provides a similar UI as the old session object, including authenticate and invalidate methods. Instead of reading the session content directly from the session as was the case in old versions of the library, the session provides a content property that can be used to read and write date from and to the session.

Also support for defining a custom session class has been dropped in favor of defining a service that uses the session service to provide functionality based on that. E.g. the typical use case of providing access to the authenticated account can now easily be implemented with a SessionAccount service that in turn uses the Session service:

import Ember from 'ember'; const { inject, computed, isEmpty } = Ember; export default Ember.Service.extend({ session: inject.service('session'), account: computed('session.content.secure.account_id', function() { const accountId = this.get('session.content.secure.account_id'); if (!isEmpty(accountId)) { return DS.PromiseObject.create({ promise: this.container.lookup('store:main').find('account', accountId) }); } }) });

Ember CLI only

While previous versions of Ember Simple Auth provided 3 different versions (AMD, globals and the Ember CLI addons) where the Ember CLI addon was also split up into several sub addons, 1.0 will come as one single Ember CLI addon. This offers 3 main advantages:

The project structure is the standard Ember CLI addon structure and no longer a custom set of grunt tasks etc. This not only makes the development and release process much simpler but also promotes contributions from others.

It is now much simpler to install Ember CLI as it's now only ember install ember-simple-auth command instead of install at least 2 packages or potentially more.

Since all the source is now transpiled with Babel as part of the Ember CLI build process, all the source code has been updated to use thinks like template strings, function literals, deconstruction etc., making the code far more concise and readable.

Getting to 1.0

1.0 is still not fully finished and ready for release. While I plan to release a first beta until next week latest, getting to the final release still requires some work:

The docs need to be updated to fit the new API and modules. Existing documentation is still based on classes and namespaces and we need to find a way to convert that so we document modules instead.

The docs are also not complete for new features like the Session service and existing documentation needs to be reviewed for whether it's actually still correct.

The code should be reviewed and cleaned up before the final 1.0 release - much of it is still what I wrote almost 2 years ago when I was still relatively new to Ember and could probably be greatly improved.

The setup of the AJAX prefilter should be decoupled from the library so that it's opt-in and could be replaced with a different approach (e.g. sth. that sets a property on the application's Ember Data adapter instead) - see #522 and #270. A compatibility Addon should be extracted that implements the current behavior of setting up the prefilter automatically.

We are holding a three day Workshop in Munich from July 22nd to 24th, taking participants through building a full Ember.js application. The topics we will cover are:

Ember Basics - understanding the core concepts

Ember CLI and the container

The Run-Loop, Promises and ES2015

Routing from the outside in

Ember Data - connecting an application to an API

JSON API

Components - data down, actions up

Services and managing State

Testing Ember apps

Debugging Ember apps and the Ember Inspector

Authentication

Deployment

Animations and Effects with Liquid Fire

Realtime Data with Websockets

defaults write com.apple.CrashReporter DialogType none

The last blog post showed how to use Ember Simple Auth with Ember CLI to implement session handling and authentication. This post shows how to test that code.

The testing package

First of all install the new ember-cli-simple-auth-testing package:

npm install --save-dev ember-cli-simple-auth-testing ember generate ember-cli-simple-auth-testing

This package adds test helpers to the application (unless it's running with the production environment) that make it easy to authenticate and invalidate the session in tests without having to stub server responses etc. To make these helpers available to all tests, import them in tests/helpers/start-app.js:

tests/helpers/start-app.js: … import 'simple-auth-testing/test-helpers'; export default function startApp(attrs) { …

Configuring the test environment

The next step is to configure the test environment. As the tests should be isolated and leave no traces of any kind so that subsequent tests don't have implicit dependencies on the ones that have run earlier, Ember Simple Auth's default localStorage store cannot be used as that would leave data in the localStorage. Instead configure the ephemeral store to be used in the test environment:

// config/environment.js if (environment === 'test') { ENV['simple-auth'] = { store: 'simple-auth-session-store:ephemeral' } }

The ephemeral store stores data in memory and thus will be completely fresh for every test so that tests cannot influence each other.

Adding the Tests

Now everything is set up and a test can be added. To e.g. test that a certain route can only be accessed when the session is authenticated, add tests like these (notice the use of the test helpers authenticateSession and invalidateSession):

test('a protected route is accessible when the session is authenticated', function() { expect(1); authenticateSession(); visit('/protected'); andThen(function() { equal(currentRouteName(), 'protected'); }); }); test('a protected route is not accessible when the session is not authenticated', function() { expect(1); invalidateSession(); visit('/protected'); andThen(function() { notEqual(currentRouteName(), 'protected'); }); });

With the latest release of Ember Simple Auth, using the library with ember-cli has become much simpler. As ember-cli in general is still pretty new to many people though, this post describes how to setup a project using Ember Simple Auth with ember-cli.

Setting up the basic project

First of all you need to install PhantomJS, bower and of course ember-cli (Ember Simple Auth requires at least Ember CLI 0.0.44):

npm install -g phantomjs npm install -g bower npm install -g ember-cli

Then use ember-cli to create the new project:

ember new my-auth-app

At this point the basic project is set up and ready to run:

cd my-auth-app ember server

Installing Ember Simple Auth

Installing Ember Simple Auth in an ember-cli project is really easy now. All you have to do is install the ember-cli addon from npm:

npm install --save-dev ember-cli-simple-auth ember generate ember-cli-simple-auth

This will install Ember Simple Auth's AMD distribution into the project, register the initializer so Ember Simple Auth automatically sets itself up and add itself as a dependency to the project's package.json.

You can add a login route and login/logout links to verify it all actually works:

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

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

Also implement the ApplicationRouteMixin in the project's application route:

// app/routes/application.js import Ember from 'ember'; import ApplicationRouteMixin from 'simple-auth/mixins/application-route-mixin'; export default Ember.Route.extend(ApplicationRouteMixin);

Setting up authentication

To actually give the user the option to login, we need to add an authentication package for Ember Simple Auth. Let's assume you have an OAuth 2.0 compatible server running at http://localhost:3000. To use that, install the OAuth 2.0 extension library which again is as easy as installing the package from npm:

npm install --save-dev ember-cli-simple-auth-oauth2 ember generate ember-cli-simple-auth-oauth2

Like the ember-cli-simple-auth package this will setup itself so that nothing else has to be done in order to use the OAuth 2.0 functionality.

The OAuth 2.0 authentication mechanism needs a login form, so let's create that:

// 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> </form>

Then implement the LoginControllerMixin in the login controller and make that use the OAuth 2.0 authenticator to perform the actual authentication:

// app/controllers/login.js import Ember from 'ember'; import LoginControllerMixin from 'simple-auth/mixins/login-controller-mixin'; export default Ember.Controller.extend(LoginControllerMixin, { authenticator: 'simple-auth-authenticator:oauth2-password-grant' });

As the OAuth 2.0 authenticator would by default use the same domain and port to send the authentication requests to that the Ember.js is loaded from you need to configure it to use http://localhost:3000 instead:

// config/environment.js if (environment === 'development') { … ENV['simple-auth-oauth2'] = { serverTokenEndpoint: 'http://localhost:3000/token' } …

You also need to make sure that your server allows cross origin requests by enabling CORS (e.g. with rack-cors if you're using a rack based server).

Conclusion

Ember Simple Auth 0.6.0 introduced some significant improvements that make it a lot easier to use the library with Ember CLI as that's the new de facto standard for building Ember applications.

No more initializers

First of all the requirement to define an initializer to set up the library has been dropped. With the recently introduced Ember CLI Addons system (see Robert Jackson's great introduction), Ember Simple Auth can now be installed via npm and will register its initializer automatically:

npm install --save-dev ember-cli-simple-auth

Better Documentation

The documentation has been rewritten to focus on using the library with ES6 modules, e.g.:

// app/routes/application.js import ApplicationRouteMixin from 'simple-auth/mixins/application-route-mixin'; export default Ember.Route.extend(ApplicationRouteMixin);

Using the browserified version that exports the SimpleAuth global (which is no longer attached to the Ember global) is not really deprecated but I wouldn't encourage anybody to using that in real projects as Ember CLI is clearly so much better.

Ember.SimpleAuth 0.3.0 was just released. The main change in this release is the split of Ember.SimpleAuth into one core library and a set of extension libraries. These extension libraries include everything that's not mandatorily required for Ember.SimpleAuth like authenticators, stores etc. so that every application would only have to load whatever it needs. These extension libraries are:

ember-simple-auth-oauth2: includes the OAuth 2.0 authenticator and authorizer which are just one option out of many and probably not needed in many projects (e.g. when using a custom authenticator)

ember-simple-auth-devise: new authenticator/authorizer package that is compatible with the Ruby gem devise.

ember-simple-auth-cookie-store: The cookie store which is probably only used in few projects.

There are hopefully more extension libraries to come as people start to provide more authenticators, authorizers and other components and now there's a (more or less, pre 1.0) stable API for these libraries as well as a set of tasks to build and test them

Another bigger change in this release is that having an authorizer is now optional. As there are applications that are purely client side and don't use a server backend expecting every application to use an authorizer was probably not so great in the first place. However, applications that do use an authorizer can simply configure one in Ember.SimpleAuth's setup method and everything will behave as before:

Ember.Application.initializer({ name: 'authentication', initialize: function(container, application) { Ember.SimpleAuth.setup(container, application, { authorizerFactory: 'authorizer:oauth2-bearer' }); } });