lux-oauth2
v0.0.3
Published
OAuth2 authorization middleware for Lux API framework.
Downloads
8
Maintainers
Readme
Lux OAuth2 is an OAuth2 authorization server & middleware for Lux API framework.
Install
$ npm install --save lux-oauth2
Usage
Lux OAuth2 has been built with extension in mind. More grant types will soon be available out-of-the-box, along with details of how to define your own custom grant types.
Currently, Lux OAuth2 only supports a password
with refresh_token
grant type flow.
1. Database
Ready your database with the required models listed below. Check out the example app for more guidance.
user
(Model | Migration)oauth-access-token
(Model | Migration)oauth-client
(Model | Migration | Seed)oauth-refresh-token
(Model | Migration)
2. OAuth2 Server
Initialize a new OAuth2 server instance. Ensure to add all the required models and any grant types you wish to use.
// app/middleware/oauth2.js
import { OAuth2BaseServer, OAuth2PasswordGrantType } from 'lux-oauth2';
import OAuthAccessToken from 'app/models/oauth-access-token';
import OAuthClient from 'app/models/oauth-client';
import OAuthRefreshToken from 'app/models/oauth-refresh-token';
import User from 'app/models/user';
class OAuth2Server extends OAuth2BaseServer {
static models = {
accessToken: OAuthAccessToken,
client: OAuthClient,
refreshToken: OAuthRefreshToken,
user: User
};
static grantTypes = [
OAuth2PasswordGrantType
];
}
export default new OAuth2Server();
3. Token route
The token endpoint will require a POST
action. OAuth2 recommends using the /oauth/token
route.
// app/routes.js
this.resource('oauth', {
only: []
}, function(){
this.post('/token', 'token');
});
The payload sent to the server must be wrapped in a data
attribute. The following controller setup allows the parameters through to the controller, where the requestToken
function is then called.
// app/controllers/oauth.js
import { Controller } from 'lux-framework';
import OAuth2Server from 'app/middleware/oauth2';
class OauthController extends Controller {
params = [
'grantType',
'username',
'password'
]
query = [
'data'
]
token(request, response) {
return OAuth2Server.requestToken(request, response);
}
}
export default OauthController;
4. Authenticate
Add the authenticate action to the application controller's beforeAction
array to ensure the OAuth2 server attempts to authenticate a user for each request.
import { Controller } from 'lux-framework';
import OAuth2Server from 'app/middleware/oauth2';
class ApplicationController extends Controller {
beforeAction = [
OAuth2Server.authenticate
];
}
export default ApplicationController;
This adds an oauth2
object to the request, containing an isAuthenticated
boolean value and the currentUser
.
console.log(request.oauth2);
// => { isAuthenticated: true, currentUser: User }
5. Authenticated route
Add the authenticatedRoute
action to any resource you wish to protect.
// app/controllers/user.js
import { Controller } from 'lux-framework';
import OAuth2Server from 'app/middleware/oauth2';
class UsersController extends Controller {
beforeAction = [
OAuth2Server.authenticatedRoute
];
}
export default UsersController;
Keep certain endpoints from requiring authentication using lux-unless.
beforeAction = [
unless({ path: ['/users/stats'] }, OAuth2Server.authenticatedRoute)
];
Options
Server Options
The following additional options can be set on the OAuth2 server.
class OAuth2Server extends OAuth2BaseServer {
accessTokenLifetime = 3600;
refreshTokenLifetime = 1209600;
}
Overriding methods
If you need to override one of the OAuth2Server's core methods, simply redefine the method in the OAuth2Server.
class OAuth2Server extends OAuth2BaseServer {
getUser = async (email, password, done) => {
// add your custom method of retrieving the user...
}
}
Custom Grant types
Coming soon™...
Example
$ cd /examples/lux-oauth2-example
$ npm install
$ lux db:create && lux db:migrate && lux db:seed
$ lux serve
Use the Lux OAuth2 Example Postman Collection to check the following:
- Request a token as the test user.
- Try modifying test user
email
&password
sent to the token endpoint to check credentials errors. - Use the
refresh_token
value to auth via refresh token. - Try to access
/users
to find it requires authentication. - Add
Bearer <YOUR_ACCESS_TOKEN>
to theAuthorization
header to access the/users
data.
Tests
$ npm install
$ npm test
Related Modules
- node-oauth2-server - OAuth2 server in Node.js.
- lux-unless - Conditionally skip a middleware.
License
This project is licensed under the MIT license. See the LICENSE file for more info.