Nanananananananana.. Pat Man!

    @osjs/database-auth

    1.0.8 • Public • Published

    OS.js Logo

    OS.js is an open-source web desktop platform with a window manager, application APIs, GUI toolkit, filesystem abstractions and much more.

    Support Support Donate Donate Community

    OS.js v3 Database Auth Adapter

    This is the Database Auth Adapter for OS.js v3. Built on TypeORM.

    To set this up, you need to do the following steps:

    1. Set up your database
    2. Install
    3. Configure Server
    4. Configure Client
    5. Configure CLI
    6. Manage Users

    Please see the OS.js Authentication Guide for general information.

    You can find a complete example using docker on github

    Set up your database

    Before you begin you need to chose a database and set this up on your host system.

    This documentation uses mysql by default, but you can use any SQL flavor that TypeORM supports.

    The database and credentials you set up in this step has to be reflected in the configurations below.

    Assuming you have installed mysql (refer to you operating system documentation) and logged into the server:

    # Create a new database called "osjsv3"
    mysql> CREATE DATABASE osjsv3;
    
    # Creates a new used called "osjsv3" with password "secret"
    mysql> CREATE USER 'osjsv3'@'localhost' IDENTIFIED BY 'secret';
    
    # Give permission for the user to access the database
    mysql> GRANT ALL ON osjsv3.* TO 'osjsv3'@'localhost';

    Note that the mysql users are not related to OS.js users.

    If you've already installed @osjs/database-settings module you can skip this step and use the same database and credentials.

    Installation

    Install the required OS.js module and database driver:

    npm install --save --production @osjs/database-auth
    npm install --save mysql

    Configure Server

    To connect the server with the database authentication module, you'll have to modify your Server bootstrap script.

    In your src/server/index.js file:

    // In the top of the file load the library
    const dbAuth = require('@osjs/database-auth');
    
    // Locate this line in the file and add the following:
    osjs.register(AuthServiceProvider, {
      args: {
        adapter: dbAuth.adapter,
        config: {
          connection: {
            // Change this to match your local database server
            type: 'mysql',
            host: 'localhost',
            username: 'osjsv3',
            password: 'secret',
            database: 'osjsv3',
    
            // See TypeORM documentation for more settings
          }
        }
      }
    });

    NOTE: You have to restart the server after making these changes.

    Configure Client

    By default OS.js is set up to log in with the demo / demo user for demonstration purposes.

    In your src/client/config.js file:

    module.exports = {
      public: '/',
    
      // Either comment out this section, or remove it entirely
      /*
      auth: {
        login: {
          username: 'demo',
          password: 'demo'
        }
      }
      */
    };

    NOTE: You have to rebuild using npm run build after making these changes.

    Configure CLI

    To get CLI commands to manage users, you'll have to modify your CLI bootstrap script.

    In your src/cli/index.js file:

    // In the top of the file load the library
    const dbAuth = require('@osjs/database-auth');
    
    // Create a database authentication instance
    const dbCli = dbAuth.cli({
      // Change this to match your local database server
      type: 'mysql',
      host: 'localhost',
      username: 'osjsv3',
      password: 'secret',
      database: 'osjsv3',
    
      // See TypeORM documentation for more settings
    });
    
    // Then finally add 'dbCli' to the tasks array
    module.exports = {
      discover: [],
      tasks: [dbCli]
    };

    Manage Users

    You can now manage users with ex. npx osjs-cli <task>

    The npx command comes with npm 5.2 or later, but if you for some reason don't have this you can install it manually. Or alternatively use node node_modules/.bin/osjs-cli <task>

    Available tasks:

    • user:list - Lists users
    • user:add --username=STR - Adds user (as admin)
    • user:add --username=STR --groups=GROUP1,GROUP2 - Adds user with groups
    • user:pwd --username=STR - Changes user password
    • user:remove --username=STR - Removes user

    Example: npx osjs-cli user:add --username=anders.

    Notes

    If you want to use sqlite run npm install sqlite3 and change the connection options to:

    {
      connection: {
        type: 'sqlite',
        database: 'path/to/database.sql'
      }
    }

    For more information about configuration: https://typeorm.io/

    If you don't want to repeat the connection information over multiple files, for example create src/database-connection.js with the contents:

    module.exports = {
      type: 'mysql',
      host: 'localhost',
      username: 'osjsv3',
      password: 'secret',
      database: 'osjsv3',
    }

    and then in your scripts:

    {
      connection: require('../database-connection.js')
    }

    Contribution

    Documentation

    See the Official Manuals for articles, tutorials and guides.

    Links

    Keywords

    Install

    npm i @osjs/database-auth

    DownloadsWeekly Downloads

    4

    Version

    1.0.8

    License

    BSD-2-Clause

    Unpacked Size

    21.3 kB

    Total Files

    9

    Last publish

    Collaborators

    • andersevenrud