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	[email protected]
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)