aurelia-authentication
Aurelia-authentication is a token-based authentication plugin for Aurelia with support for popular social authentication providers (Google, Twitter, Facebook, LinkedIn, Windows Live, FourSquare, Yahoo, Github, Instagram) and a local strategy, i.e. simple username / email and password. It developed of a fork of paul van bladel's aurelia-auth which itself is a port of the great Satellizer library.
Aurelia-authentication makes local and third-party authentication easy. Aurelia-authentication does not use any cookies but relies on a token (designed for JWT, but has basic support for others as well) stored in the local storage of the browser. If your server is setup right, it can be a simple as just to select your server endpoint from your aurelia-api setup, add your third-party client ids and you are ready to go.
You have multiple endpoints? No problem! In the recommended setting, aurelia-authentication makes use of aurelia-api which can set up multiple endpoints. Just specify in your aurelia-authentication configuration which endpoint you want to use for your server and which further endpoints you want to be configured and your token will be sent automatically to your protected API when the user is authenticated.
With aurelia-authentication you can:
- Use local login or third-party providers to authenticate the user
- Automatically add your token to requests to the specified endpoints
- Automatically refresh your token
- Extensively customize the settings
- Use standalone or in conjunction with aurelia-api
- Use Auth0 as your only authentication provider (see the relevant section for more info)
- Update valueConverters using the 'authorization-change' binding signal.
- Subscribe to the 'authorization-change' event.
- And more
Documentation
You can find usage examples and the documentation at the aurelia-authentication-docs.
The changelog provides you with information about important changes.
Installation
Aurelia-Cli
Run npm i aurelia-authentication --save
from your project root.
Aurelia-authentication needs an installation of aurelia-api. It also has submodules (currently only the authFilter) and makes use of extend
and jwt-decode
. So, add following to the build.bundles.dependencies
section of aurelia-project/aurelia.json
.
"dependencies": [
"extend",
{
"name": "aurelia-authentication",
"path": "../node_modules/aurelia-authentication/dist/amd",
"main": "aurelia-authentication"
},
{
"name": "jwt-decode",
"path": "../node_modules/jwt-decode/lib",
"main": "index"
}
],
Jspm
Run jspm i aurelia-authentication
Add aurelia-authentication
to the bundles.dist.aurelia.includes
section of build/bundles.js
.
Aurelia-authentication needs an installation of aurelia-api. It also has submodules. They are imported in it's main file, so no further action is required.
If the installation results in having forks, try resolving them by running:
jspm inspect --forks
jspm resolve --only registry:package-name@version
E.g.
jspm inspect --forks
> Installed Forks
> npm:aurelia-dependency-injection 1.0.0-beta.1.2.3 1.0.0-beta.2.1.0
jspm resolve --only npm:aurelia-dependency-injection@1.0.0-beta.2.1.0
Webpack
Run npm i aurelia-authentication --save
from your project root.
The authFilter
needs to be added to the webpack.config.js
.
Run npm i ModuleDependenciesPlugin --save-dev
from your root project and include it the webpack.config.js
, eg:
const { AureliaPlugin, ModuleDependenciesPlugin } = require('aurelia-webpack-plugin');`
In the plugins
section add the authFilter
, eg:
plugins: [
new AureliaPlugin(),
new ModuleDependenciesPlugin({
"aurelia-authentication": [ "./authFilterValueConverter" ],
}),
Aurelia-authentication needs an aurelia-api. It also has submodules. They are listed as resources in the package.json. So, no further action is required.
Typescript
Npm-based installations pick up the typings automatically. For Jspm-based installations, add to your typings.json
:
"aurelia-authentication": "github:spoonx/aurelia-authentication",
and run typings i
or run
typings i github:spoonx/aurelia-authentication
Usage
Add a configuration file
Set your custom configuration. You can find all options and the default values in the baseConfig.
var baseConfig = {
endpoint: 'auth',
configureEndpoints: ['auth'],
facebook: {
clientId: 'your client id'
}
}
Configure the plugin
Register the plugin and apply your authConfig
.
import authConfig from './authConfig';
aurelia.use
.plugin('aurelia-api', config => {
config.registerEndpoint('auth');
})
.plugin('aurelia-authentication', baseConfig => {
baseConfig.configure(authConfig);
});
Use AuthService in a view-model
import {AuthService} from 'aurelia-authentication';
import {inject} from 'aurelia-framework';
@inject(AuthService)
export class Login {
constructor(authService) {
this.authService = authService;
this.authenticated = false;
};
login(credentialsObject) {
return this.authService.login(credentialsObject)
.then(() => {
this.authenticated = this.authService.authenticated;
});
};
logout() {
return this.authService.logout()
.then(() => {
this.authenticated = this.authService.authenticated;
});
}
authenticateFacebook() {
return this.authService.authenticate('facebook')
.then(() => {
this.authenticated = this.authService.authenticated;
});
}
}
Quick authService api overview
authService
.client
.authenticated
signup(displayNameOrCredentials, emailOrOptions, passwordOrRedirectUri, options, redirectUri)
login(emailOrCredentials, passwordOrOptions, optionsOrRedirectUri, redirectUri)
logout(redirectUri, query, name)
.updateToken()
authenticate(name, redirectUri, userData)
unlink(name, redirectUri)
.getMe(criteriaOrId)
.updateMe(body, criteriaOrId)
.isAuthenticated()
.getTokenPayload()
.getTtl()
.getExp()
Additionally, you can use AuthFilterValueConverter
and AuthenticatedStep
for UI feedback.
You can find more information in the aurelia-authentication-docs.
Note
Some month ago, we've simplified installation and usage! This plugin should now be installed using jspm i aurelia-authentication
or (for webpack) npm i aurelia-authentication --save
. 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).