@enablo/passport-workchat v1.0.3

passport-workchat

Passport strategy for authenticating with Workplace by Facebook using Work Chat and the Graph API.

This module lets you authenticate using Workplace by Facebook in your Node.js application. By plugging into Passport, Workplace by Facebook authentication can easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.

Breaking Changes

Version 1.x

Prior to update 1.x there was no way to use passport-workchat with App Secret Proof enabled.

The update to 1.x brings this feature into the package and makes it mandatory to use.

Install

$ npm install @enablo/passport-workchat

Usage

Create a Custom Integration

Before using passport-workchat, you must create a new custom integration within Workplace by Facebook.

You will need to give the custom integration to send messages to anyone, read profile and email addresses.

Once created, supply the access token and app secret to the strategy.

Configure Strategy

The Workplace by Facebook authentication strategy authenticates users by sending an One Time Pin/Password to the user via Work Chat. To send the Work Chat messages the strategy requires the access token and app secret from the custom integration via the accessToken and appSecret parameters respectively.

passport.use(new WorkChatStrategy({
  accessToken: process.env.WORKPLACE_ACCESS_TOKEN,
  appSecret: process.env.WORKPLACE_APP_SECRET,
}));

Authenticate Requests

Use passport.authenticate(), specifying the 'workchat' strategy, to authenticate requests.

The authentication process expects two requests. The first request to should include just the workplaceUsername to initiate the OTP process.

{
  "workplaceUsername": "user@workplace.com"
}

The second request should contain the OTP code entered by the user to finalise the authentication process.

{
  "workplaceUsername": "user@workplace.com",
  "code": "1234"
}

For example, as route middleware in an Express application:

app.post('/login', passport.authenticate('workchat'), (req, res) => {
  return res.send(req.user);
});

Examples

Developers using the popular Express web framework can refer to an to the examples directory for an example of a basic implementation.