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

grant is build on top of mashape / guardian

Providers live demo

amazon	asana	bitly	box	digitalocean	dropbox
facebook	flickr	foursquare	github	google	heroku
imgur	instagram	linkedin	live	mailchimp	openstreetmap
paypal	slack	soundcloud	stackexchange	stocktwits	stripe
trello	tumblr	twitch	twitter	vimeo	yahoo

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"
      }
    }
    

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

1. Set up your common server callback in server.json 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 (take a look at the reserved routes for Grant)
2. Optionally you can override the end callback for each provider individually (take a look at the configuration structure)

License

MIT