passport-wix-app

Wix Application authentication strategy for Passport.

Useful helper for Wix Application developers

Install

$ npm install -S passport-wix-app

Usage

This module parses instance parameter passed by Wix Applications (see documentation 🌐)

Wix sends several other parameters (not only instance). You could get their values straight from the original request. Just pass passReqToCallback: true among other Strategy options.

Additional request's parameters depend on Wix Application type. Read more on the official Wix-Dev site:

for widget 🌐
for page 🌐

Configure Strategy

The wix-app authentication strategy authenticates a user using instance parameter, passed by Wix 🌐.

The strategy requires options and verify callback.

passport.use(new WixAppStrategy({"secret": "WIX-APP-SECRET"},
  function verifyCallback (instance, done) {

    // any user-verification logic
    // ...
    // here is an example:
    User.findOne({
      application: instance.instanceId,
      userId: instance.uid
    }, function (err, user) {
      // error during verification
      if (err) { return done(err) }

      // user is not found/not authenticated
      if (!user) { return done(null, false) }

      // success:
      return done(null, user)
    })
  }
))

Options

You can pass additional options to the WixAppStrategy constructor:

new WixAppStrategy(options, callback)

The available options are:

passReqToCallback - determines whether to pass the incoming request (req) to the verify callback
secret - Optional, defaults to null. Defines the secret assigned to your Wix Application. Note that you can omit secret on a configuration step and pass secret on request handling, when the app will call passport.authenticate() method.

Verification callback

Verification callback will be called with several params (see passReqToCallback in options-section):

req - optional incoming Express-request 🌐 (will be passed if passReqToCallback option is set to true)
instance - parsed Wix-Instance 🌐
callback - passport-done function

Parsed Instance

Example of parsed instance (taken from Wix-documentation 🌐 and extended with custom fields - ext):

parsedInstance = {
    "instanceId":       "bf296da1-75ce-48e6-9f72-14b7148d4fa2",
    "signDate":         "2015-12-10T06:57:37.201Z",
    "uid":              "da32cbf7-7f8b-4f9b-a97e-e67f3072ce92",
    "permissions":      "OWNER",
    "ipAndPort":        "91.199.119.13/35734",
    "vendorProductId":  null,
    "originInstanceId": "c38e4e00-dcc1-433e-9e90-b332def7b342",
    "siteOwnerId":      "da32cbf7-7f8b-4f9b-a97e-e67f3072ce92",

    // additional params:
    "ext": {
        "ip":           "91.199.119.13",
        "port":         35734,
        "signDate":     new Date(2015, 11, 10, 06, 57, 37, 201)
    },
}

Authenticate Requests

Use passport.authenticate(), specifying the 'wix-app' strategy, to authenticate requests.

For example, as route middleware in an Express 🌐 application:

app.post('/login',
  passport.authenticate('wix-app', { failureRedirect: '/login' }),
  function(req, res) {
    res.redirect('/');
  });

Or, with late-loaded secret:

app.post('/login',
  passport.authenticate('wix-app', {
    secret: 'secret-key',
    failureRedirect: '/login'
  }),
  function(req, res) {
    res.redirect('/');
  });

Credits

The passport-local 🌐 (by Jared Hanson) was used as a scaffold for this module.

License

Please, read the LICENSE file in the root of the repository (or downloaded package).