ember-cli-guardsman v0.0.0

Ember-cli-guardsman

An Ember CLI addon to interface with any server-side authentication and authorisation system.

This addon is built upon the ember-cli-adpater-pattern allowing you to easily create your own storage container adapters.

Installation

From within your Ember CLI project directory run:

ember install ember-cli-guardsman

Usage

This addon implements a service to interface with several OAuth2 providers by providing an abstract API that hides the implementation details of each provider adapter.

Configuration

Before the guardsman service can be used it first must be configured through config/environment. This allows you to define which of the providers you want to make available to your application through the guardsman service.

Example:

// config/environment.js
module.exports = function(environment) {
  var ENV = {
    guardsman: {
      providers: [
        {
          name: 'Facebook',
          config: {
            clientId: 'xxxxxx'
          }
        },
        {
          name: 'Github',
          config: {
            clientId: 'xxxxxx'
          }
        },
        {
          name: 'Google',
          config: {
            clientId: 'xxxxxx'
          }
        }
      ]
    }
  };

  return ENV;
};

This configures your application to use all 3 adapters bundled with this addon.

providers

The providers array takes a series of objects defining the configuration of each adapter. This is a requirement of ember-cli-adpater-pattern where each object may take additional key/value pairs. This addon however only requires the name of the adapter in pascal case.

Injection

This addon makes no assumptions about what ember objects you want to make the guardsman service available. Therefore in order to make the service available you need to implement you own injections.

Example:

// app/initializers/guardsman.js
export function initialize(application) {
  application.inject('controller', 'guardsman', 'service:guardsman');
  application.inject('route', 'guardsman', 'service:guardsman');
};

export default {
  name: 'guardsman',
  initialize: initialize
};

This will make the guardsman service available to all controllers and routes. It is however unlikely that you will require the service to be injected into every controller or route of your applications. Therefore it is recommended that you include the service on a per object basis.

Example:

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

export default Ember.Controller.extend({
  guardsman: Ember.inject.service()
});

This will create a dependency on the application controller and inject the guardsman service into this controller only. This can be repeated across all objects that need access to the service.

Guardsman Service

The guardsman service implements an abstract API that currently supports the following methods:

• open
• fetch
• close

When using this API, by default the service will call the corresponding method on each of the adapters unless a specific adapter is specified. This means that if you were to call open on the service, it would in turn call open on each of the adapters and thus authenticate against each provider configured in config/environment.

Example:

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

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

  login: Ember.on('init', function() {
    const guardsman = this.get('guardsman');
    guardsman.open({ username: 'Jean-Luc Picard', password: 'Enterprise-D' });
  })
});

This is likely not the desired behaviour and is a consequence of the ember-cli-adpater-pattern. If you only want to authenticate against a single provider you must specify the name.

Example:

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

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

  login: Ember.on('init', function() {
    const guardsman = this.get('guardsman');
    guardsman.open('Facebook', { username: 'Jean-Luc Picard', password: 'Enterprise-D' });
  })
});

This will only authenticate using the Facebook adapter.

Each API call will be wrapped within a promise that resolves with the returned result of the adapter mapped to the adapter name. This means that for any method called on the service where a return value is expected you must use the Promise API to access it.

Example:

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

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

  login: Ember.on('init', function() {
    const guardsman = this.get('guardsman');
    guardsman.open('Facebook', { username: 'Jean-Luc Picard', password: 'Enterprise-D' }).then(function() {
      console.log(values['Facebook']); // Will print the value returned from the Facebook adapter.
    });
  })
});

Development

Installation

• git clone this repository
• npm install
• bower install

Running

• ember server
• Visit your app at http://localhost:4200.

Running Tests

• npm test (Runs ember try:testall to test your addon against multiple Ember versions)
• ember test
• ember test --server

Building

• ember build

For more information on using ember-cli, visit http://www.ember-cli.com/.