Grant

grant is build on top of mashape / guardian

Providers Playground

500px	amazon	asana	bitly	box	digitalocean
dropbox	facebook	flickr	flowdock	foursquare	github
google	heroku	imgur	instagram	linkedin (2)	live
mailchimp	openstreetmap	paypal	redbooth	salesforce	slack
soundcloud	stackexchange	stocktwits	stripe	trello	tumblr
twitch	twitter	vimeo	yahoo	yammer

Usage

var express = require('express');
var Grant = require('grant');

var grant = new Grant({...configuration see below...});

var app = express();
// mount grant
app.use(grant);
// app server middlewares
app.use(cookieParser());
app.use(session());

Reserved Routes for Grant

/connect/:provider/:override?
/step/:number
/connect/:provider/callback

Configuration

{
  "server": {
    "protocol": "http",
    "host": "localhost:3000",
    "callback": "/callback"
  },
  "provider1": {
    "key": "...",
    "secret": "...",
    "scope": ["scope1", "scope2", ...],
    "state": "some state",
    "callback": "/provider1/callback"
  },
  "provider2": {...},
  ...
}

• server - configuration about your server
  • protocol - either http or https
  • host - your server's host name localhost:3000 | dummy.com:5000 | mysite.com ...
  • callback - common callback for all providers in your config
• provider1 - any supported provider (see the above table) google | facebook ...

  • key - consumer_key or client_id of your app

  • secret - consumer_secret or client_secret of your app

  • scope - OAuth scopes array

  • state - OAuth state string

  • callback - specific callback to use for this provider (overrides the global one specified in the server key)
    

    • These callbacks are used only on your server!
      
    • These callbacks are not the one you specify for your app!
    • You should always specify the callback or redirect url of your app like this:
      http(s)://mydomain.com/connect/[provider]/callback where
      
      • provider is one of the above provider names
      • mydomain.com is your site's domain name

  • protocol | host - additionally you can override these common values inherited from the server key

  • custom1 - create sub configuration for that provider
    You can override any of the above keys here
    Example
    

    "facebook": {
      "key": "...",
      "secret": "...",
      // by default request publish permissions via /connect/facebook
      "scope": ["publish_actions", "publish_stream"],
      // set specific callback route on your server for this provider only
      "callback": "/facebook/callback"
      // custom override keys
      "groups": {
        // request only group permissions via /connect/facebook/groups
        "scope": ["user_groups", "friends_groups"]
      },
      "pages": {
        // request only page permissions via /connect/facebook/pages
        "scope": ["manage_pages"],
        // additionally use specific callback route on your server for this override only
        "callback": "/pages/callback"
      }
    }

Dynamic Override

Additionally you can make a POST request to the /connect/[provider] route to override your provider's options dynamically for each request

// example using request
request.post('http://mydomain.com/connect/facebook', {
  form: {scope:['some','other','scopes']}
}, function (err, res, body) {});

Typical Flow

1. Register OAuth application on your provider's web site
2. For callback or redirect url you should always use this format
   http(s)://mydomain.com/connect/[provider]/callback where
   

• provider is one of the above provider names
• mydomain.com is your site's domain name

3. Set up your common server callback under the server key of your configuration. This is the final callback when the OAuth flow is complete. Grant will redirect you to it after hitting the /connect/[provider]/callback specified for your app, therefore this callback should be something different than the reserved routes for Grant
4. Optionally you can override the end callback for each provider individually, take a look at the configuration data structure

Quirks

• At some point LinkedIn added support for OAuth2, so if you want to use that flow, you should use linkedin2 for provider name, instead of linkedin which is for OAuth1

License

MIT