grant

What is grant?

The 'grant' npm package is a middleware for OAuth that allows you to easily integrate with various OAuth providers. It supports multiple frameworks like Express, Koa, Hapi, and more. It simplifies the process of setting up OAuth flows for authentication and authorization.

What are grant's main functionalities?

Express Integration

This code demonstrates how to integrate the 'grant' package with an Express application to handle OAuth authentication with Google. It sets up the necessary middleware and routes to handle the OAuth flow.

const express = require('express');
const session = require('express-session');
const Grant = require('grant-express');

const app = express();
app.use(session({secret: 'very secret'}));
app.use(new Grant({
  defaults: {
    protocol: 'http',
    host: 'localhost:3000',
    transport: 'session',
    state: true
  },
  google: {
    key: 'GOOGLE_CLIENT_ID',
    secret: 'GOOGLE_CLIENT_SECRET',
    scope: ['profile', 'email'],
    callback: '/handle_google_callback'
  }
}));

app.get('/handle_google_callback', (req, res) => {
  res.json(req.session.grant.response);
});

app.listen(3000, () => {
  console.log('Server listening on http://localhost:3000');
});

Koa Integration

This code demonstrates how to integrate the 'grant' package with a Koa application to handle OAuth authentication with GitHub. It sets up the necessary middleware and routes to handle the OAuth flow.

const Koa = require('koa');
const session = require('koa-session');
const Grant = require('grant-koa');

const app = new Koa();
app.keys = ['very secret'];
app.use(session(app));
app.use(new Grant({
  defaults: {
    protocol: 'http',
    host: 'localhost:3000',
    transport: 'session',
    state: true
  },
  github: {
    key: 'GITHUB_CLIENT_ID',
    secret: 'GITHUB_CLIENT_SECRET',
    scope: ['user'],
    callback: '/handle_github_callback'
  }
}));

app.use(async (ctx) => {
  if (ctx.path === '/handle_github_callback') {
    ctx.body = ctx.session.grant.response;
  }
});

app.listen(3000, () => {
  console.log('Server listening on http://localhost:3000');
});

Hapi Integration

This code demonstrates how to integrate the 'grant' package with a Hapi application to handle OAuth authentication with Twitter. It sets up the necessary middleware and routes to handle the OAuth flow.

const Hapi = require('@hapi/hapi');
const Grant = require('grant-hapi');

const start = async () => {
  const server = Hapi.server({
    port: 3000,
    host: 'localhost'
  });

  await server.register({
    plugin: Grant,
    options: {
      defaults: {
        protocol: 'http',
        host: 'localhost:3000',
        transport: 'session',
        state: true
      },
      twitter: {
        key: 'TWITTER_CONSUMER_KEY',
        secret: 'TWITTER_CONSUMER_SECRET',
        callback: '/handle_twitter_callback'
      }
    }
  });

  server.route({
    method: 'GET',
    path: '/handle_twitter_callback',
    handler: (request, h) => {
      return request.yar.get('grant').response;
    }
  });

  await server.start();
  console.log('Server running on %s', server.info.uri);
};

start();

Other packages similar to grant

passport

Passport is a popular authentication middleware for Node.js. It supports a wide range of authentication strategies, including OAuth, OAuth2, OpenID, and more. Compared to 'grant', Passport offers more flexibility and a larger ecosystem of strategies, but it can be more complex to set up.

simple-oauth2

Simple OAuth2 is a library for integrating OAuth2 authentication in Node.js applications. It provides a straightforward API for obtaining access tokens and refreshing them. Compared to 'grant', Simple OAuth2 is more focused on OAuth2 and does not support as many frameworks out of the box.

bell

Bell is a Hapi plugin for third-party authentication using OAuth, OAuth2, and more. It is specifically designed for Hapi applications and provides a seamless integration with the Hapi framework. Compared to 'grant', Bell is more specialized for Hapi but does not support other frameworks.

README

Grant

170+ Supported Providers / OAuth Playground

23andme | 500px | acton | acuityscheduling | aha | amazon | angellist | arcgis | asana | assembla | auth0 | authentiq | axosoft | baidu | basecamp | battlenet | beatport | bitbucket | bitly | box | buffer | campaignmonitor | cheddar | clio | coinbase | concur | constantcontact | coursera | dailymile | dailymotion | deezer | delivery | deputy | deviantart | digitalocean | discogs | discord | disqus | docusign | dribbble | dropbox | ebay | echosign | ecwid | edmodo | egnyte | etsy | eventbrite | evernote | everyplay | eyeem | facebook | familysearch | feedly | fitbit | flattr | flickr | flowdock | fluidsurveys | formstack | foursquare | freeagent | freshbooks | geeklist | genius | getbase | getpocket | gitbook | github | gitlab | gitter | goodreads | google | groove | gumroad | harvest | hellosign | heroku | homeaway | iconfinder | idme | idonethis | imgur | infusionsoft | instagram | intuit | jamendo | jawbone | jumplead | kakao | letsfreckle | linkedin | live | lyft | mailchimp | mailup | mapmyfitness | medium | meetup | microsoft | mixcloud | mixer | moves | moxtra | mydigipass | myob | nest | nylas | okta | openstreetmap | optimizely | patreon | paypal | pinterest | plurk | podio | producteev | producthunt | projectplace | pushbullet | ravelry | redbooth | reddit | runkeeper | salesforce | shoeboxed | shopify | skyrock | slack | slice | smartsheet | smugmug | socialpilot | socrata | soundcloud | spotify | square | stackexchange | stocktwits | stormz | strava | stripe | surveygizmo | surveymonkey | thingiverse | ticketbud | timelyapp | todoist | trakt | traxo | trello | tripit | tumblr | twitch | twitter | typeform | uber | underarmour | unsplash | upwork | uservoice | vend | venmo | verticalresponse | viadeo | vimeo | visualstudio | vk | weekdone | weibo | withings | wordpress | wrike | xero | xing | yahoo | yammer | yandex | zendesk

Table of Contents

• Providers
• Middleware
  • Express
  • Koa
  • Hapi
  • Alternative Require
  • Path Prefix
  • Reserved Routes
• Configuration
  • Basics
  • Redirect URL
  • Static Overrides
  • Dynamic Override
• Advanced Configuration
  • Custom Parameters
  • Custom Providers
  • Development Environments
  • Programmatic Access
  • Sandbox Redirect URI
  • Quirks
• Response Data
• Misc
  • Typical Flow
  • Get User Profile
• Examples

Express

npm install grant-express

var express = require('express')
var session = require('express-session')
var grant = require('grant-express')

var app = express()
// REQUIRED: any session store - see /examples/express-session-stores
app.use(session({secret: 'grant'}))
// mount grant
app.use(grant({/*configuration - see below*/}))

Koa

npm install grant-koa

var Koa = require('koa')
var session = require('koa-session')
var mount = require('koa-mount')
var grant = require('grant-koa')

var app = new Koa()
// REQUIRED: any session store - see /examples/koa-session-stores
app.keys = ['grant']
app.use(session(app))
// mount grant
app.use(mount(grant({/*configuration - see below*/})))

Hapi

npm install grant-hapi

var Hapi = require('hapi')
var yar = require('yar')
var grant = require('grant-hapi')

var server = new Hapi.Server()
server.register([
  // REQUIRED: any session store - see /examples/hapi-session-stores
  {plugin: yar, options: {cookieOptions: {password: 'grant', isSecure: false}}},
  // mount grant
  {plugin: grant(), options: {/*configuration - see below*/}}
])

Alternative Require

Alternatively you can require Grant directly (each pair is identical):

// Express
var Grant = require('grant-express')
var Grant = require('grant').express()
// Koa
var Grant = require('grant-koa')
var Grant = require('grant').koa()
// Hapi
var Grant = require('grant-hapi')
var Grant = require('grant').hapi()

Path Prefix

You can mount Grant under specific path prefix:

// Express
app.use('/path/prefix', grant({config}))
// Koa
app.use(mount('/path/prefix', grant({config})))
// Hapi
server.register([{plugin: grant({config}), routes: {prefix: '/path/prefix'}}])

In this case it is required to specify the path prefix using the path configuration option for the server key:

{
  "server": {
    "protocol": "...",
    "host": "...",
    "path": "/path/prefix"
  }
}

Lastly that path prefix should be specified in your OAuth application's redirect URL as well:

[protocol]://[host][path]/connect/[provider]/callback

In case you want your callback routes prefixed, set them accordingly:

{
  "facebook": {
    "callback": "/path/prefix/handle_facebook_callback"
  }
}

Reserved Routes

/connect/:provider/:override?
/connect/:provider/callback

Configuration

{
  "server": {
    "protocol": "http",
    "host": "localhost:3000",
    "callback": "/callback",
    "transport": "session",
    "state": true
  },
  "provider1": {
    "key": "...",
    "secret": "...",
    "scope": ["scope1", "scope2", ...],
    "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 ...
  • path - path prefix to use for the Grant middleware (defaults to empty string if omitted)
  • callback - common callback route for all providers in your config /callback | /done ...
  • transport - transport to use to deliver the response data in your final callback route querystring | session (defaults to querystring if omitted)
  • state - generate random state string on each authorization attempt true | false (OAuth2 only, defaults to false if omitted)
• provider1 - any supported provider facebook | twitter ...
  • key - consumer_key or client_id of your OAuth app
  • secret - consumer_secret or client_secret of your OAuth app
  • scope - array of OAuth scopes to request
  • callback - specific callback route to use for this provider (overrides the global one specified under the server key)
  • custom_params - custom authorization parameters (see the Custom Parameters section)

Additionally any of the reserved keys can be overriden for a provider.

Redirect URL

For redirect URL of your OAuth application you should always use this format:

[protocol]://[host]/connect/[provider]/callback

Where protocol and host should match the ones from which you initiate the OAuth flow, and provider is the provider's name from the list of supported providers.

This redirect URL is used internally by Grant. You will receive the response data from the OAuth flow inside the route specified in the callback key of your Grant configuration.

See the Path Prefix section on how to configure the redirect URL when using the path configuration option.

Static Overrides

You can add arbitrary {object} keys inside your provider's configuration to create sub configurations that override the global settings for that provider:

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

The custom key names must be different from the reserved ones.

Dynamic Override

Additionally you can make a POST request to the /connect/:provider/:override? route to override your provider's configuration dynamically on each request:

<form action="/connect/facebook" method="post" accept-charset="utf-8">
  <input type="checkbox" name="scope" value="user_birthday" /> user_birthday
  <input type="checkbox" name="scope" value="user_hometown" /> user_hometown
  <input type="checkbox" name="scope" value="user_location" /> user_location
  <button>submit</button>
</form>

Keep in mind that in this case you'll have to mount the body-parser middleware for Express and Koa before mounting Grant:

// express
var parser = require('body-parser')
app.use(parser.urlencoded({extended: true}))
app.use(grant({config}))
// koa
var parser = require('koa-bodyparser')
app.use(parser())
app.use(mount(grant({config})))

Alternatively you can make a GET request to the /connect/:provider/:override? route:

https://mywebsite.com/connect/facebook?scope=user_photos%2Cuser_videos

Custom Parameters

Some providers may employ custom authorization parameters outside of the specified ones in the configuration section. You can pass those custom parameters using the custom_params option:

"google": {
  "custom_params": {"access_type": "offline"}
},
"reddit": {
  "custom_params": {"duration": "permanent"}
},
"trello": {
  "custom_params": {"name": "my app", "expiration": "never"}
}

Additionally any custom parameter that is not a reserved key, and is listed under the custom_parameters array for that provider, can be defined along with the rest of the options.

Refer to the provider's OAuth documentation, and the Grant's OAuth configuration (search for custom_parameters).

Custom Providers

In case you have a private OAuth provider that you don't want to be part of the officially supported ones, you can define it in your configuration by adding a custom key for it.

In this case you have to specify all of the required provider keys by yourself:

{
  "server": {
    "protocol": "https",
    "host": "mywebsite.com"
  },
  "mywebsite": {
    "authorize_url": "https://mywebsite.com/authorize",
    "access_url": "https://mywebsite.com/token",
    "oauth": 2,
    "key": "[CLIENT_ID]",
    "secret": "[CLIENT_SECRET]",
    "scope": ["read", "write"]
  }
}

Refer to the Grant's OAuth configuration to see how various providers are configured.

Development Environments

You can easily configure different development environments:

{
  "development": {
    "server": {"protocol": "http", "host": "dummy.com:3000"},
    "facebook": {
      "key": "development OAuth app credentials",
      "secret": "development OAuth app credentials"
    },
    "twitter": {...}, ...
  },
  "staging": {
    "server": {"protocol": "https", "host": "staging.mywebsite.com"},
    "facebook": {
      "key": "staging OAuth app credentials",
      "secret": "staging OAuth app credentials"
    },
    "twitter": {...}, ...
  },
  "production": {
    "server": {"protocol": "https", "host": "mywebsite.com"},
    "facebook": {
      "key": "production OAuth app credentials",
      "secret": "production OAuth app credentials"
    },
    "twitter": {...}, ...
  }
}

Then you can pass the environment flag:

NODE_ENV=production node app.js

And use it in your application:

var config = require('./config.json')
var grant = new Grant(config[process.env.NODE_ENV || 'development'])

Programmatic Access

Once you initialize a new instance of Grant:

var grant = new Grant(require('./config'))

You get a special config property attached to that instance. It contains the generated configuration data for all of the providers defined in your config file.

In case of dynamic access to a non pre-configured provider, it is automatically added to the config list on first access to the /connect/:provider route.

Sandbox Redirect URI

Very rarely you may need to override the default redirect_uri that Grant generates for you.

For example Feedly supports only http://localhost as redirect URL of their Sandbox OAuth application, and it won't allow the http://localhost/connect/feedly/callback path:

"feedly": {
  "redirect_uri": "http://localhost"
}

In case you override the redirect_uri in your config, you'll have to redirect the user to the [protocol]://[host]/connect/[provider]/callback route that Grant uses to execute the last step of the OAuth flow:

var qs = require('querystring')

app.get('/', (req, res) => {
  if (process.env.NODE_ENV === 'development' &&
      req.session.grant &&
      req.session.grant.provider === 'feedly' &&
      req.query.code
  ) {
    res.redirect('/connect/' + req.session.grant.provider + '/callback?'
      + qs.stringify(req.query))
  }
})

After that you will receive the Response Data from the OAuth flow inside the route specified in the callback key of your configuration.

Quirks

Subdomain

Some providers require you to set your company name or server region as subdomain in the OAuth URLs. You can set that value through the subdomain option:

"shopify": {
  "subdomain": "mycompany"
},
"battlenet": {
  "subdomain": "us"
}

Then Grant will generate the correct OAuth URLs:

"shopify": {
  "authorize_url": "https://mycompany.myshopify.com/admin/oauth/authorize",
  "access_url": "https://mycompany.myshopify.com/admin/oauth/access_token"
},
"battlenet": {
  "authorize_url": "https://us.battle.net/oauth/authorize",
  "access_url": "https://us.battle.net/oauth/token"
}

Alternatively you can override the entire request_url, authorize_url and access_url in your configuration.

Sandbox URLs

Some providers may have sandbox URLs for testing. To use them just override the entire request_url, authorize_url and access_url in your configuration (notice the sandbox bits):

"paypal": {
  "authorize_url": "https://www.sandbox.paypal.com/webapps/auth/protocol/openidconnect/v1/authorize",
  "access_url": "https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice"
},
"evernote": {
  "request_url": "https://sandbox.evernote.com/oauth",
  "authorize_url": "https://sandbox.evernote.com/OAuth.action",
  "access_url": "https://sandbox.evernote.com/oauth"
}

Ebay

Set the redirect URL of your OAuth app as usual [protocol]://[host]/connect/ebay/callback. Then Ebay will generate a special string called RuName (eBay Redirect URL name) that you need to set as redirect_uri in Grant:

"ebay": {
  "redirect_uri": "[RUNAME]"
}

Flickr, Optimizely

Flickr uses a custom authorization parameter to pass its scopes called perms, and Optimizely uses scopes. However you should use the regular scope option in your configuration:

"flickr": {
  "scope": ["write"]
}
"optimizely": {
  "scope": ["all"]
}

SurveyMonkey

Set your Mashery user name as key and your application key as api_key:

"surveymonkey": {
  "key": "[MASHERY_USER_NAME]",
  "secret": "[CLIENT_SECRET]",
  "api_key": "[CLIENT_ID]"
}

Fitbit, LinkedIn, ProjectPlace

Initially these providers supported only OAuth1, so the fitbit and linkedin names are used for that. To use their OAuth2 flow append 2 at the end of their names:

"fitbit2": {
  // then navigate to /connect/fitbit2
},
"linkedin2": {
  // then navigate to /connect/linkedin2
},
"projectplace2": {
  // then navigate to /connect/projectplace2
}

VisualStudio

Set your Client Secret as secret not the App Secret:

"visualstudio": {
  "key": "[APP_ID]",
  "secret": "[CLIENT_SECRET not APP_SECRET]"
}

Response Data

The OAuth response data is returned as querystring in your final callback - the one you specify in the callback key of your Grant configuration.

Alternatively the response data can be returned inside the session, see the configuration section above and the session transport example.

OAuth1

For OAuth1 the access_token and the access_secret are accessible directly, raw contains the raw response data:

{
  access_token: '...',
  access_secret: '...',
  raw: {
    oauth_token: '...',
    oauth_token_secret: '...',
    some: 'other data'
  }
}

OAuth2

For OAuth2 the access_token and the refresh_token (if present) are accessible directly, raw contains the raw response data:

{
  access_token: '...',
  refresh_token: '...',
  raw: {
    access_token: '...',
    refresh_token: '...',
    some: 'other data'
  }
}

Error

In case of an error, the error key will be populated with the raw error data:

{
  error: {
    some: 'error data'
  }
}

Typical Flow

1. Register OAuth application on your provider's web site.
2. For redirect URL of your OAuth application always use this format: [protocol]://[host]/connect/[provider]/callback
3. Create config.json file containing:

"server": {
  "protocol": "https",
  "host": "mywebsite.com"
},
"facebook": {
  "key": "[CLIENT_ID]",
  "secret": "[CLIENT_SECRET]",
  "callback": "/handle_facebook_callback"
},
"twitter": {
  "key": "[CONSUMER_KEY]",
  "secret": "[CONSUMER_SECRET]",
  "callback": "/handle_twitter_callback"
}

1. Initialize Grant and mount it:

// Express
var express = require('express')
var session = require('express-session')
var grant = require('grant-express')
express()
  .use(session({secret: 'grant'}))
  .use(grant(require('./config.json')))
// or Koa
// or Hapi

1. Navigate to /connect/facebook to initiate the OAuth flow for Facebook, or navigate to /connect/twitter to initiate the OAuth flow for Twitter.
2. Once the OAuth flow is completed you will receive the response data in the /handle_facebook_callback route for Facebook, and in the /handle_twitter_callback route for Twitter.

Take a look at the examples.

Get User Profile

Once you have your access tokens secured, you can start making authorized requests on behalf of your users. Purest is a generic REST API client library that supports hundreds of REST API providers.

For example, you may want to get the user's profile after the OAuth flow has completed:

var request = require('request')
var purest = require('purest')({request})
var config = require('@purest/config')
var facebook = purest({provider: 'facebook', config})
var twitter = purest({provider: 'twitter', config,
  key: '[CONSUMER_KEY]', secret: '[CONSUMER_SECRET]'
})

facebook
  .get('me')
  .auth('[ACCESS_TOKEN]')
  .request((err, res, body) => {
    // here body is a parsed JSON object containing
    // id, first_name, last_name, gender, username, ...
  })

twitter
  .get('users/show')
  .qs({screen_name: 'nodejs'})
  .auth('[ACCESS_TOKEN]', '[ACCESS_SECRET]')
  .request((err, res, body) => {
    // here body is a parsed JSON object containing
    // id, screen_name, ...
  })

Changelog

v4.1.2 (2018/07/16)

• New: Official support for 4 new providers: arcgis, nest, okta, typeform
• Change: Updated 2 providers: dropbox, withings