lux-oauth2

    0.0.3 • Public • Published

    Download count all time npm Gitter

    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.

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

    Tests

    $ npm install
    $ npm test
    

    Related Modules

    License

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

    Install

    npm i lux-oauth2

    DownloadsWeekly Downloads

    0

    Version

    0.0.3

    License

    MIT

    Last publish

    Collaborators

    • avatar