0.0.3 • Public • Published

    Download count all time npm Gitter

    Lux OAuth2 is an OAuth2 authorization server & middleware for Lux API framework.


    $ npm install --save lux-oauth2


    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.

    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 = [
    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(){'/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 = [
      query = [
      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 = [
    export default ApplicationController;

    This adds an oauth2 object to the request, containing an isAuthenticated boolean value and the currentUser.

    // => { 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 = [
    export default UsersController;

    Keep certain endpoints from requiring authentication using lux-unless.

    beforeAction = [
      unless({ path: ['/users/stats'] }, OAuth2Server.authenticatedRoute)


    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™...


    $ 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 the Authorization header to access the /users data.


    $ npm install
    $ npm test

    Related Modules


    This project is licensed under the MIT license. See the LICENSE file for more info.


    npm i lux-oauth2

    DownloadsWeekly Downloads






    Last publish


    • avatar