passport-fellowshipone

Passport-FellowshipOne

Passport strategy for authenticating with Fellowship One using the OAuth 1.0a API.

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

Install

$ npm install passport-fellowshipone

Usage

Configure Strategy

The Fellowship One authentication strategy authenticates users using a Fellowship One account and OAuth 1.0a tokens. The strategy requires a verify callback, which accepts these credentials and calls done providing a user, as well as options specifying a developer key and callback URL.

var FellowshipOneStrategy = require('passport-fellowshipone').Strategy;

passport.use(new FellowshipOneStrategy({
    apiURL: 'https://MyChurch.staging.fellowshiponeapi.com/v1',
    consumerKey: F1_DEVELOPER_KEY,
    consumerSecret: F1_SECRET,
    callbackURL: "http://127.0.0.1:3000/auth/fellowshipone/callback"
  },
  function verify(token, tokenSecret, profile, done) {
    User.findOrCreate({ userId: profile.id }, function (err, user) {
      return done(err, user);
    });
  }
));

F1-specific options

To make life a little easier for dealing with Fellowship One's API, you can set these options:

• churchCode - Your Fellowship One Church Code. When set, this will be used to automatically build the apiURL option. If you want to use the staging environment, you must also set apiURL!
• apiURL - The base URL for Fellowship One API operations (i.e. https://{churchCode}.staging.fellowshiponeapi.com/v1). This is auto-calculated from churchCode when not specified, but can be provided here for customizations (i.e. pointing to staging). Supports URI Templating, using the options object to provide properties.

The returned profile

The verify callback is given a profile when a user successfully authenticates. The profile is constructed from the user's F1 Person record, but only contains a subset of information so that it can be easily linked to a user record in your application.

The profile's properties are:

• id - (Number) The authenticated user's numeric ID
• uri - The full URI for accessing the user's Person record
• displayName - A name to be used in user-facing views. If the user has a goesByName set in their F1 Person record, this will be used, otherwise this is the firstName from F1.
• fullName - The user's full name (using displayName as the first name)
• email - A guess at the user's primary e-mail address. If they have an e-mail address set as preferred in the F1 Person record, this will be it. Otherwise, the first e-mail address found for them is used.

Authenticate Requests

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

For example, as route middleware in an Express application:

app.get('/auth/fellowshipone',
  passport.authenticate('fellowshipone'));

app.get('/auth/fellowshipone/callback',
  passport.authenticate('fellowshipone', { failureRedirect: '/login' }),
  function(req, res) {
    // Successful authentication, redirect home.
    res.redirect('/');
  });

Tests

$ npm install --dev
$ make test

Credits

• Jared Hanson - for Passport and for passport-familysearch upon which this module was based.
• Dave Henderson - for converting passport-familysearch to work with the Fellowship One API

License

The MIT License

Copyright (c) 2014-2015 Dave Henderson