loopback/docs/bundled-models.md

Bundled Models

The Loopback library is unopinioned in the way you define your app's data and logic. Loopback also bundles useful pre-built models for common use cases.

• User - register and authenticate users of your app locally or against 3rd party services.
• Email - send emails to your app users using smtp or 3rd party services.

Defining a model with loopback.createModel() is really just extending the base loopback.Model type using loopback.Model.extend(). The bundled models extend from the base loopback.Model allowing you to extend them arbitrarily.

User Model

Register and authenticate users of your app locally or against 3rd party services.

Define a User Model

Extend a vanilla Loopback model using the built in User model.

// create a data source
var memory = loopback.memory();

// define a User model
var User = loopback.User.extend('user');

// attach to the memory connector
User.attachTo(memory);

// also attach the accessToken model to a data source
User.accessToken.attachTo(memory);

// expose over the app's api
app.model(User);

Note: By default the loopback.User model uses the loopback.AccessToken model to persist access tokens. You can change this by setting the accessToken property.

Note: You must attach both the User and User.accessToken model's to a data source!

User Creation

Create a user like any other model.

// username and password are not required
User.create({email: 'foo@bar.com', password: 'bar'}, function(err, user) {
  console.log(user);
});

Login a User

Create an accessToken for a user using the local auth strategy.

Node.js

User.login({username: 'foo', password: 'bar'}, function(err, accessToken) {
  console.log(accessToken);
});

REST

You must provide a username and password over rest. To ensure these values are encrypted, include these as part of the body and make sure you are serving your app over https (through a proxy or using the https node server).

POST

  /users/login
  ...
  {
    "email": "foo@bar.com",
    "password": "bar"
  }

  ...

  200 OK
  {
    "sid": "1234abcdefg",
    "uid": "123"
  }

Logout a User

Node.js

// login a user and logout
User.login({"email": "foo@bar.com", "password": "bar"}, function(err, accessToken) {
  User.logout(accessToken.id, function(err) {
    // user logged out
  });
});

// logout a user (server side only)
User.findOne({email: 'foo@bar.com'}, function(err, user) {
  user.logout();
});

REST

POST /users/logout
...
{
  "sid": "<accessToken id from user login>"
}

Verify Email Addresses

Require a user to verify their email address before being able to login. This will send an email to the user containing a link to verify their address. Once the user follows the link they will be redirected to / and be able to login normally.

// first setup the mail datasource (see #mail-model for more info)
var mail = loopback.createDataSource({
  connector: loopback.Mail,
  transports: [{
    type: 'smtp',
    host: 'smtp.gmail.com',
    secureConnection: true,
    port: 465,
    auth: {
      user: 'you@gmail.com',
      pass: 'your-password'
    }
  }]
});

User.email.attachTo(mail);
User.requireEmailVerfication = true;
User.afterRemote('create', function(ctx, user, next) {
  var options = {
    type: 'email',
    to: user.email,
    from: 'noreply@myapp.com',
    subject: 'Thanks for Registering at FooBar',
    text: 'Please verify your email address!'
    template: 'verify.ejs',
    redirect: '/'
  };
  
  user.verify(options, next);
});

Reset Password

You can implement password reset using the User.resetPassword method.

Request a password reset access token.

Node.js

User.resetPassword({
  email: 'foo@bar.com'
}, function () {
  console.log('ready to change password');
});

REST

POST

  /users/reset-password
  ...
  {
    "email": "foo@bar.com"
  }
  ...
  200 OK

You must the handle the resetPasswordRequest event this on the server to send a reset email containing an access token to the correct user. The example below shows a basic setup for sending the reset email.

User.on('resetPasswordRequest', function (info) {
  console.log(info.email); // the email of the requested user
  console.log(info.accessToken.id); // the temp access token to allow password reset

  // requires AccessToken.belongsTo(User)
  info.accessToken.user(function (err, user) {
    console.log(user); // the actual user
    var emailData = {
      user: user,
      accessToken: accessToken
    };

    // this email should include a link to a page with a form to
    // change the password using the access token in the email
    Email.send({
      to: user.email,
      subject: 'Reset Your Password',
      text: loopback.template('reset-template.txt.ejs')(emailData),
      html: loopback.template('reset-template.html.ejs')(emailData)
    });
  });
});

AccessToken Model

Identify users by creating accessTokens when they connect to your loopback app. By default the loopback.User model uses the loopback.AccessToken model to persist accessTokens. You can change this by setting the accessToken property.

// define a custom accessToken model    
var MyAccessToken = loopback.AccessToken.extend('MyAccessToken');

// define a custom User model
var User = loopback.User.extend('user');

// use the custom accessToken model
User.accessToken = MyAccessToken;

// attach both AccessToken and User to a data source
User.attachTo(loopback.memory());
MyAccessToken.attachTo(loopback.memory());

Email Model

Send emails from your loopback app.

// extend a one-off model for sending email
var MyEmail = loopback.Email.extend('my-email');

// create a mail data source
var mail = loopback.createDataSource({
  connector: loopback.Mail,
  transports: [{
    type: 'smtp',
    host: 'smtp.gmail.com',
    secureConnection: true,
    port: 465,
    auth: {
      user: 'you@gmail.com',
      pass: 'your-password'
    }
  }]
});

// attach the model
MyEmail.attachTo(mail);

// send an email
MyEmail.send({
  to: 'foo@bar.com',
  from: 'you@gmail.com',
  subject: 'my subject',
  text: 'my text',
  html: 'my <em>html</em>'
}, function(err, mail) {
  console.log('email sent!');
});

NOTE: the mail connector uses nodemailer. See the nodemailer docs for more info.