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; ;;;; static models = accessToken: OAuthAccessToken client: OAuthClient refreshToken: OAuthRefreshToken user: User ; static grantTypes = OAuth2PasswordGrantType ; ;
3. Token route
The token endpoint will require a POST
action. OAuth2 recommends using the /oauth/token
route.
// app/routes.jsthis;
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;; params = 'grantType' 'username' 'password' query = 'data' { return OAuth2Server; } ;
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.
;; beforeAction = OAuth2Serverauthenticate ; ;
This adds an oauth2
object to the request, containing an isAuthenticated
boolean value and the currentUser
.
console;// => { isAuthenticated: true, currentUser: User }
5. Authenticated route
Add the authenticatedRoute
action to any resource you wish to protect.
// app/controllers/user.js;; beforeAction = OAuth2ServerauthenticatedRoute ; ;
Keep certain endpoints from requiring authentication using lux-unless.
beforeAction = ;
Options
Server Options
The following additional options can be set on the OAuth2 server.
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.
getUser = async { // 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.