Skip to content
This repository was archived by the owner on Nov 25, 2020. It is now read-only.

Commit

Permalink
feat(project): Rename project to remove spoonx prefix. enable npm ins…
Browse files Browse the repository at this point in the history
…tallation

BREAKING CHANGE: `spoonx/` prefix dropped from install name for authentication and api. Update `package.json` and `config.js` accordingly.
  • Loading branch information
doktordirk committed Apr 3, 2016
1 parent c6af3e1 commit 637aac4
Show file tree
Hide file tree
Showing 8 changed files with 68 additions and 45 deletions.
49 changes: 32 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,12 @@

> Makes setting up authentication for your Aurelia app simple.
## Important note

`jspm i aurelia-authentication` or (for webpack) `npm i aurelia-authentication`. Make sure you update all references to `spoonx/aurelia-authentication` and `spoonx/aurelia-api` and remove the `spoonx/` prefix (don't forget your config.js, package.json, imports and bundles).

## What is aurelia-authentication?

This is a largely refactored module based on [paul van bladel's aurelia-authentication](https://github.com/paulvanbladel/aurelia-auth/).

aurelia-authentication is a token-based authentication plugin for [Aurelia](http://aurelia.io/) with support for popular social authentication providers (Google, Twitter, Facebook, LinkedIn, Windows Live, FourSquare, Yahoo, Github, Instagram) and a local stragegy, i.e. simple username / email and password.
Expand All @@ -20,15 +25,15 @@ Basically, aurelia-authentication does not use any cookies but relies on a JWT (

Both **local storage** as well as **session storage** can be used (via the aurelia-authentication security configuration file).

Spoonx/aurelia-authentication makes use of [aurelia-api](https://github.com/SpoonX/aurelia-api) for convenient use of the aurelia-fetch-client. Options are available to directly use aurelia-fetch-client instead. If configured, the aurelia token will be sent automatically to your protected API when the user is authenticated.
aurelia-authentication makes use of [aurelia-api](https://github.com/SpoonX/aurelia-api) for convenient use of the aurelia-fetch-client. Options are available to directly use aurelia-fetch-client instead. If configured, the aurelia token will be sent automatically to your protected API when the user is authenticated.

![Authentication header](./pictures/authHeader.png)

## How this differs from 'paulvanbladel/aurelia-auth'

This repository was originally a fork of paulvanbladel/aurealia-auth. It was forked when the original repository was in a period of inactivity, and later made into a repository of it's own. As such we often get asked how this repository differs from the original. So, at the time of writing the differences are as follows:

- Provides the option to use endpoints, introduced by [spoonx/aurelia-api](https://github.com/SpoonX/aurelia-api), which simplifies API access.
- Provides the option to use endpoints, introduced by [aurelia-api](https://github.com/SpoonX/aurelia-api), which simplifies API access.
- By using aurelia-api the developer can specify which endpoints require the authentication patch.
- TypeScript support added through the addition of d.ts (typescript definition) files
- Lots of bug fixes
Expand All @@ -37,16 +42,19 @@ This repository was originally a fork of paulvanbladel/aurealia-auth. It was for
**Aside:** Public SpoonX repositories are open to the community and actively maintained and used by the SpoonX company. They follow a strict deploy cycle with reviews and follow semantic versioning. This ensures code quality control and long term commitment.

## Installation

We assume that you know about ([NodeJs](https://nodejs.org/), [Gulp](http://gulpjs.com/)) and [Aurelia](http://aurelia.io/).
Since aurelia-authentication is an [Aurelia plugin](https://github.com/aurelia/skeleton-plugin), we also assume that you have your [Aurelia](http://aurelia.io/) project up and running.

```
jspm install github:spoonx/aurelia-authentication
```sh
jspm install aurelia-authentication
```

## How to use aurelia-authentication?

aurelia-authentication does not contain any UI widgets. It's conceived as a simple service with following interface:
```javascript

```js
login(email, password)
logout(redirectUri)
authenticate(provider, redirect, userData)
Expand All @@ -57,13 +65,15 @@ isAuthenticated()
getTokenPayload()
unlink(provider)
```

Login is used for the local authentication strategy (email + password). Authenticate is for social media authentication. Authenticate is also used for linking a social media account to an existing account.

### Add an aurelia-authentication security configuration file

Add an javascript file to your project where you will store the aurelia-authentication security configuration data. Call it for example authConfig.js.
Since this file is available via the browser, it should never contain sensitive data. Note that for OAuth the clientId is non sensitive. The client secret is sensitive data and should be only available server side. The aurelia-authentication config file is compatible with the original Satellizer config file, easing the migration of AngularJs projects to Aurelia.

Spoonx/aurelia-authentication uses [aurelia-api](https://github.com/SpoonX/aurelia-api). Set here the aurelia-api endpoint for the authorization requests and specify all endpoints you want to have configured for authorized requests. The aurelia token will be added to requests to those endpoints.
aurelia-authentication uses [aurelia-api](https://github.com/SpoonX/aurelia-api). Set here the aurelia-api endpoint for the authorization requests and specify all endpoints you want to have configured for authorized requests. The aurelia token will be added to requests to those endpoints.

```js
var baseConfig = {
Expand Down Expand Up @@ -111,17 +121,17 @@ else {
}

export default config;

```

The above configuration file can cope with a development and production version (not mandatory of course). The strategy is that when your run on localhost, the development configuration file is used, otherwise the production configuration file is taken.

### Update the aurelia configuration file

In your aurelia configuration file, add the plugin and inject the aurelia-authentication security configuration file.

While not mandantory, spoonx/aureli-auth is easiest to use in conjunction with [aurelia-api](https://github.com/SpoonX/aurelia-api). Aurelia-api allows to setup several endpoints for Rest services. This can be used to seperate public and protected routes. For that, we first need to register the endpoints with aurelia-api. Bellow we setup the endpoints 'auth' and 'protected-api'. These will be setup in the proceeding spoonx/aurelia-authentication-plugin configuration for authorized access (specified in above authConfig.js example). The endpoint 'public-api' bellow could be used for public access only, since we didn't add it above to the 'configureEndpoints' array and thus the access token will not be added by aurelia-authentication.
While not mandantory, aurelia-authentication is easiest to use in conjunction with [aurelia-api](https://github.com/SpoonX/aurelia-api). Aurelia-api allows to setup several endpoints for Rest services. This can be used to seperate public and protected routes. For that, we first need to register the endpoints with aurelia-api. Bellow we setup the endpoints 'auth' and 'protected-api'. These will be setup in the proceeding aurelia-authentication-plugin configuration for authorized access (specified in above authConfig.js example). The endpoint 'public-api' bellow could be used for public access only, since we didn't add it above to the 'configureEndpoints' array and thus the access token will not be added by aurelia-authentication.

```javascript
```js
import authConfig from './authConfig';

export function configure(aurelia) {
Expand All @@ -130,36 +140,37 @@ export function configure(aurelia) {
.standardConfiguration()
.developmentLogging()
/* setup the api endpoints first (if desired) */
.plugin('spoonx/aurelia-api', configure => {
.plugin('aurelia-api', configure => {
configure
.registerEndpoint('auth', 'https://myapi.org/auth')
.registerEndpoint('protected-api', 'https://myapi.org/protected-api')
.registerEndpoint('public-api', 'http://myapi.org/public-api');
})
/* configure spoonx/aurelia-authentication */
.plugin('spoonx/aurelia-authentication', baseConfig => {
/* configure aurelia-authentication */
.plugin('aurelia-authentication', baseConfig => {
baseConfig.configure(authConfig);
});

aurelia.start().then(a => a.setRoot());
}

```

### Provide a UI for a login, signup and profile.
### Provide a UI for a login, signup and profile

See aurelia-authentication-samples for more details.

Button actions are passed to the corresponding view model via a simple click.delegate:

```html
<button class="btn btn-block btn-google-plus" click.delegate="authenticate('google')">
<span class="ion-social-googleplus"></span>Sign in with Google
</button>
```

The login view model will speak directly with the aurelia-authentication service, which is made available via constructor injection.

```js
import {AuthService} from 'spoonx/aurelia-authentication';
import {AuthService} from 'aurelia-authentication';
import {inject} from 'aurelia-framework';
@inject(AuthService)

Expand Down Expand Up @@ -192,6 +203,7 @@ export class Login {
```

On the profile page, social media accounts can be linked and unlinked. For a nice UI experience, use if.bind for either showing the link or unlink button:

```html
<button class="btn btn-sm btn-danger" if.bind="profile.facebook" click.delegate="unlink('facebook')">
<i class="ion-social-facebook"></i> Unlink Facebook Account
Expand All @@ -200,6 +212,7 @@ On the profile page, social media accounts can be linked and unlinked. For a nic
<i class="ion-social-facebook"></i> Link Facebook Account
</button>
```

### Making the Aurelia Router authentication aware

The logout and profile links are only shown when the user is authenticated, whereas the login link is only visible when the user is not authenticated.
Expand Down Expand Up @@ -228,12 +241,13 @@ The logout and profile links are only shown when the user is authenticated, wher
</ul>
</div>
```

Menu items visibility can also be linked with the authFilter to the isAuthenticated value.

In the router config function, you can specifify an auth property in the routing map indicating wether or not the user needs to be authenticated in order to access the route:

```js
import {AuthorizeStep} from 'spoonx/aurelia-authentication';
import {AuthorizeStep} from 'aurelia-authentication';

export class App {
configureRouter(config, router) {
Expand All @@ -252,9 +266,10 @@ export class App {
};
}
```

In the above example the customer route is only available for authenticated users.

## Full configuration options.
## Full configuration options

Via the above mentioned configuration virtually all aspects of the authentication process can be tweaked:

Expand Down
8 changes: 4 additions & 4 deletions config.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@ System.config({
},

map: {
"aurelia-api": "npm:aurelia-api@2.1.2",
"aurelia-dependency-injection": "npm:aurelia-dependency-injection@1.0.0-beta.1.2.0",
"aurelia-fetch-client": "npm:aurelia-fetch-client@1.0.0-beta.1.2.0",
"aurelia-polyfills": "npm:aurelia-polyfills@1.0.0-beta.1.1.0",
"aurelia-polyfills": "npm:aurelia-polyfills@1.0.0-beta.1.1.1",
"aurelia-router": "npm:aurelia-router@1.0.0-beta.1.2.0",
"fetch": "github:github/fetch@0.11.0",
"spoonx/aurelia-api": "github:spoonx/aurelia-api@2.1.2",
"github:spoonx/aurelia-api@2.1.2": {
"npm:aurelia-api@2.1.2": {
"aurelia-dependency-injection": "npm:aurelia-dependency-injection@1.0.0-beta.1.2.0",
"aurelia-fetch-client": "npm:aurelia-fetch-client@1.0.0-beta.1.2.0",
"extend": "npm:extend@3.0.0",
Expand All @@ -30,7 +30,7 @@ System.config({
"npm:aurelia-metadata@1.0.0-beta.1.2.0": {
"aurelia-pal": "npm:aurelia-pal@1.0.0-beta.1.2.0"
},
"npm:aurelia-polyfills@1.0.0-beta.1.1.0": {
"npm:aurelia-polyfills@1.0.0-beta.1.1.1": {
"aurelia-pal": "npm:aurelia-pal@1.0.0-beta.1.2.0"
},
"npm:aurelia-route-recognizer@1.0.0-beta.1.2.0": {
Expand Down
20 changes: 12 additions & 8 deletions doc/configure-client.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,35 @@
## Client configuration options
# Client configuration options

## Configuring the endpoint

### Configuring the endpoint
aurelia-authentication uses [aurelia-api](https://github.com/SpoonX/aurelia-api), which has support for [multiple endpoints](https://github.com/SpoonX/aurelia-api/blob/master/doc/getting-started.md#multiple-endpoints).
By default, aurelia-orm uses the HttpClient from [aurelia-fetch-client](https://github.com/aurelia/fetch-client) when no specific endpoint has been configured, and if no [default endpoint](https://github.com/SpoonX/aurelia-api/blob/master/doc/getting-started.md#default-endpoint) was configured.
So, if you want aurelia to use your **default** endpoint, you only have to configure aurelia-api.
If you wish to use a **specific** endpoint to have aurelia-authentication talk to, you have to set the `endpoint` config option to a string, being the endpoint name.

#### Authorization header
### Authorization header

If you require more flexibility, and want to send the authorization header along to multiple endpoints, you can simply use the `configureEndpoints` config option.
Set this to an array of endpoint names to configure, and aurelia-authentication will do the rest, and make sure that all requests (when authenticated) get enriched with the authorization header.

### Configure the Fetch Client
## Configure the Fetch Client

If you don't want to use aurelia-api, you have to configure the aurelia-fetch-client. In your aurelia app file, inject the {FetchConfig} class from aurelia-authentication. We need to explicitly opt-in for the configuration of your fetch client by calling the configure function of the FetchConfig class:
```
import 'bootstrap';

```js
import 'bootstrap';
import {inject} from 'aurelia-framework';
import {Router} from 'aurelia-router';
import {FetchConfig} from 'spoonx/aurelia-authentication';
import {FetchConfig} from 'aurelia-authentication';

@inject(Router,FetchConfig, AppRouterConfig )
export class App {

constructor(router, fetchConfig, appRouterConfig){
this.router = router;
this.fetchConfig = fetchConfig;
}

activate(){
this.fetchConfig.configure();
}
Expand Down
28 changes: 16 additions & 12 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,32 +22,36 @@
"test": "./node_modules/.bin/gulp test"
},
"jspm": {
"registry": "npm",
"jspmPackage": true,
"main": "aurelia-authentication",
"format": "amd",
"directories": {
"dist": "dist/amd"
},
"dependencies": {
"aurelia-dependency-injection": "npm:aurelia-dependency-injection@^1.0.0-beta.1.2.0",
"aurelia-fetch-client": "npm:aurelia-fetch-client@^1.0.0-beta.1.2.0",
"aurelia-router": "npm:aurelia-router@^1.0.0-beta.1.2.0",
"fetch": "github:github/fetch@^0.11.0",
"spoonx/aurelia-api": "github:spoonx/aurelia-api@^2.1.2"
"aurelia-api": "^2.1.2",
"aurelia-dependency-injection": "^1.0.0-beta.1.2.0",
"aurelia-fetch-client": "^1.0.0-beta.1.2.0",
"aurelia-router": "^1.0.0-beta.1.2.0"
},
"peerDependencies": {
"aurelia-dependency-injection": "npm:aurelia-dependency-injection@^1.0.0-beta.1.2.0",
"aurelia-fetch-client": "npm:aurelia-fetch-client@^1.0.0-beta.1.2.0",
"aurelia-router": "npm:aurelia-router@^1.0.0-beta.1.2.0",
"fetch": "github:github/fetch@^0.11.0",
"spoonx/aurelia-api": "github:spoonx/aurelia-api@^2.1.2"
"aurelia-api": "^2.1.2",
"aurelia-dependency-injection": "^1.0.0-beta.1.2.0",
"aurelia-fetch-client": "^1.0.0-beta.1.2.0",
"aurelia-router": "^1.0.0-beta.1.2.0"
},
"devDependencies": {
"aurelia-polyfills": "npm:aurelia-polyfills@^1.0.0-beta.1.1.0",
"aurelia-polyfills": "^1.0.0-beta.1.1.0",
"fetch": "github:github/fetch@^0.11.0"
}
},
"dependencies": {},
"dependencies": {
"aurelia-dependency-injection": "^1.0.0-beta.1.2.0",
"aurelia-fetch-client": "^1.0.0-beta.1.2.0",
"aurelia-router": "^1.0.0-beta.1.2.0",
"aurelia-api": "^2.1.2"
},
"devDependencies": {
"aurelia-tools": "^0.1.20",
"babel-dts-generator": "^0.4.7",
Expand Down
2 changes: 1 addition & 1 deletion src/app.fetch-httpClient.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import {HttpClient} from 'aurelia-fetch-client';
import {AuthService} from './authService';
import {BaseConfig} from './baseConfig';
import {inject} from 'aurelia-dependency-injection';
import {Config, Rest} from 'spoonx/aurelia-api';
import {Config, Rest} from 'aurelia-api';

@inject(HttpClient, Config, AuthService, BaseConfig)
export class FetchConfig {
Expand Down
2 changes: 1 addition & 1 deletion src/aurelia-authentication.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import {HttpClient} from 'aurelia-fetch-client';
import {Config, Rest} from 'spoonx/aurelia-api';
import {Config, Rest} from 'aurelia-api';

import {AuthService} from './authService';
import {AuthorizeStep} from './authorizeStep';
Expand Down
2 changes: 1 addition & 1 deletion test/app.fetch-httpClient.config.spec.js
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import {Container} from 'aurelia-dependency-injection';
import {FetchConfig} from '../src/aurelia-authentication';
import {HttpClient} from 'aurelia-fetch-client';
import {Config} from 'spoonx/aurelia-api';
import {Config} from 'aurelia-api';

function getContainer() {
let container = new Container();
Expand Down
2 changes: 1 addition & 1 deletion test/aurelia-authentication.spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import {
authUtils
} from '../src/aurelia-authentication';
import {BaseConfig} from '../src/baseConfig';
import {Config, Rest} from 'spoonx/aurelia-api';
import {Config, Rest} from 'aurelia-api';
import {HttpClient} from 'aurelia-fetch-client';

let noop = () => {
Expand Down

0 comments on commit 637aac4

Please sign in to comment.