loopback-with-admin

    2.6.1 • Public • Published

    loopback-with-admin

    Run loopback server easier.

    features

    • passing model definitions via arguments (no need to generate JSON files)
    • switching environment easier
    • admin role, which can access to all endpoints
    • easier ACL settings
    • easier custom role settings
    • easier push notification settings

    install

    npm install loopback-with-admin

    usage

    simplest run

    // model definitions
    // see "models" section for more detail
    const models = {
      user: {
        base: 'User'
      }
    };
     
    require('loopback-with-admin').run(models).then(lbInfo => {
      // see "LoopbackInfo" section for more detail
      console.log(lbInfo.getURL())         // loopback api root
      console.log(lbInfo.getAdminTokens()) // access tokens of admin
    })

    Or more strictly, pass models like

    require('loopback-with-admin').run({models: models})

    run with config dir

    before running, you can prepare a directory which contains custom config information.

    (config-dir) # any name is acceptable
    |-- common
    |   |-- server.coffee
    |-- development
    |   `-- datasources.coffee
    `-- production
        `-- datasources.coffee
    const lbWithAdmin = require('loopback-with-admin')
    const configDir = '/path/to/config-dir'
     
    lbWithAdmin.run({models: models}, configDir).then(lbInfo => {
      // loopback started with the config
    })
     
     

    See "configs" section for more details.

    run with config object

     
    const lbWithAdmin = require('loopback-with-admin')
    const config = {server: {port: 3001}}
    lbWithAdmin.run({models: models}, config)

    switching environment

     
    const configDir = '/path/to/config-dir'
     
    require('loopback-with-admin').run({models: models}, configDir, {env: 'production'})

    env is set following the rules.

    • uses the passed value if exists
    • uses NODE_ENV if exists
    • default value is 'development'

    When your config dir is

    (config-dir) # any name is acceptable
    |-- common
    |   |-- server.coffee
    |-- development
    |   `-- datasources.coffee
    |-- local
    |   `-- datasources.coffee
    |-- production
    |   `-- datasources.coffee

    and launching script like

    $ NODE_ENV=local node app.js

    then, loopback-with-admin selects configs in "local" directory.

    model definitions

    const models = {
      player: { // model name
        base: 'User', // following loopback model definition
        aclType: 'admin' // only 'aclType' is the specific property for loopback-with-admin
      },
     
      instrument: { // another model
        aclType: 'owner-read'
      }
    }
     
    require('loopback-with-admin').run({models: models})
    • Models should be the same format as loopback model definition except aclType value.
    • name is automatically set from definition information.
    • plural is set to the same value as the name unless you set manually.

    aclType for easier ACL settings

    aclType is prepared for defining complicated acls easier. loopback-with-admin generates acls from aclType with the following rules.

    aclType meaning
    admin only admin can CRUD the model (default)
    owner the owner of the model can CRUD
    public-read everyone can READ the model and admin can CRUD
    member-read authenticated users can READ the model and admin can CRUD
    public-read-by-owner CRUD by the owner, and read by everyone
    member-read-by-owner CRUD by the owner, and read by authenticated users
    none everyone can CRUD the model

    more detailed settings

    const models = {
      player: {
        base: 'User',
        aclType: {
          owner: 'rwx',
          member: 'r'
        }
      }
    }

    aclType can be an object, whose key contains the following roles.

    • owner: $owner role in LoopBack
    • member: $authenticated role in LoopBack
    • public: $everyone role in LoopBack
    • participant: participant token (see participant role section)
    • [custom roles] : see custom roles section.

    The values of the keys are rwx, which is the same as Unix permission. x here means EXECUTE accessType in LoopBack.

    See loopback roles for instructions. https://docs.strongloop.com/display/public/LB/Defining+and+using+roles

    custom roles

    You can define custom roles like the following code.

    const customRoles = {
      'doctor': '/path/to/doctor-role.js',
      'patient': '/path/to/patient-role.js'
    }
     
    require('loopback-with-admin').run({models: models, customRoles: customRoles})

    role-defining JS file

    In the file, you must export a function, which will be passed to the 2nd argument of Role.registerResolver in LoopBack.

    See how to define custom roles in LoopBack. https://docs.strongloop.com/display/public/LB/Defining+and+using+roles

    Example:

     
    module.exports = function(role, context, cb) {
      var app = this // `app` can be acquired via `this`
     
      function reject(err) {
        if (err) { return cb(err) }
        cb(null, false)
      }
     
      if (context.modelName !== 'patient') { return reject() }
     
      var userId = context.accessToken.userId
      if (!userId || userId === context.modelId) {
          return reject()
      }
     
      cb(null, true) // is in role

    admin role

    admin role is the role with which every REST APIs are available. The role and one user with it are automatically generated at boot phase.

    admin access tokens

    To be admin, you need to know its access tokens. The following code can get those.

    require('loopback-with-admin').run(models, config).then(lbInfo => {
      let tokens = lbInfo.getAdminTokens()
      console.log(tokens) // access tokens (String[]) of admin.
    })

    set fetch function to set tokens

    By default, the token is fixed and it's loopback-with-admin-token. You must change the value by passing fetch function.

    const admin = {
      fetch: function() {
        return ['your-secret-token1', 'your-secret-token2']
      }
    }
     
    require('loopback-with-admin').run(models, config, { admin: admin })

    change tokens periodically

    const admin = {
      fetch: function() {
        return generateSecretValuesByRandom().then(value => [ value ]) // fetch function allows Promise to return
      },
      intervalHours: 24 // change the value every day (by default, it's 12 hours)
    }
     
    require('loopback-with-admin').run(models, config, { admin: admin })

    admin user information

    property value
    id loopback-with-admin-user-id
    email loopback-with-admin@example.com
    password admin-user-password

    In fact, these value makes no sense as admin can never be accessed via REST APIs. No one can login with the account information.

    configs

    Four types of configs are available.

    • datasources
    • middleware
    • server
    • push-credentials

    See JSON files in default-values/non-model-configs directory.

    You can set the same properties as these JSONs.

    datasources

    config key meaning
    memory on memory datasource
    db datasource for custom entities

    Each datasource name has its connectors.

    available loopback connectors

    Available datasources are

    • mongodb
    • memory
    • memory-idstr

    memory-idstr is the default connector, which stores data only in memory, and id type is string whereas id type of "memory" is number. See loopback-connector-memory-idstr.

    To use mongodb, add dependencies in package.json of your repository

    • loopback-connector-mongodb: "1.13.0"
    • mongodb: "2.0.35"

    server

    config key meaning default
    restApiRoot REST api root /api
    port port number 3000

    push-credentials

    config key meaning
    gcmServerApiKey api key for Google Cloud Messaging (GCM)
    apnsCertData certificate pem contents for APNs
    apnsKeyData key pem contents for APNs

    LoopbackInfo

    require('loopback-with-admin').run() returns promise of LoopbackInfo.

    It contains the information of the launched loopback.

    • getURL()
    • getAdminTokens()
    • config
    • models

    getURL()

    Returns hosting URL.

    const config = {
      server: {
        port: 4156,
        restApiRoot: 'awesome-endpoint'
      }
    }
    require('loopback-with-admin').run(models, config).then(lbInfo => {
      lbInfo.getURL() // localhost:4156/awesome-endpoint
    })

    getAdminTokens()

    Returns Array of access tokens (string).

    const admin = {
      fetch: function() {
        return ['your-secret-token1', 'your-secret-token2']
      }
    }
     
    require('loopback-with-admin').run(models, config, { admin: admin }).then(lbInfo => {
      console.log(lbInfo.getAdminTokens()) // ['your-secret-token1', 'your-secret-token2']
    })

    getEnv()

    Returns environment name where loopback launched.

    config

    Contains all config values used to build loopback.

    • datasources
    • middleware
    • server
    • push-credentials

    See configs section above.

    models

    Contains model definitions used to build loopback

    See models section above.

    participant role (since v2.4)

    The role for anonymous but limited access. Programs which know a specific static access token can become the role. The token is set by options param in run() method.

    const participantToken = 'AbCdE'
    require('loopback-with-admin').run(models, config, { participantToken })
    

    Then, all accesses with the accessToken AbCdE will be participant role.

    push notification settings

    (coming soon)

    Keywords

    none

    Install

    npm i loopback-with-admin

    DownloadsWeekly Downloads

    86

    Version

    2.6.1

    License

    MIT

    Last publish

    Collaborators

    • cureapp-admin