Grant

[![npm-version]][npm] [![test-ci-img]][test-ci-url] [![test-cov-img]][test-cov-url] [![snyk-vulnerabilities]][snyk]

> _OAuth Proxy_

200+ Supported Providers / [OAuth Playground][grant-oauth]

$3

- Providers
- Handlers
- Express / Koa / Hapi / Fastify
- AWS Lambda / Azure Function / Google Cloud Function / Vercel
- Configuration
- Basics / Description / Values / Scopes
- Connect
- Origin / Prefix / Redirect URI / Custom Parameters / OpenID Connect / PKCE / Static Overrides
- Callback
- Data / Transport / Response / Session
- Dynamic Configuration
- Instance / State / HTTP / OAuth Proxy
- Misc
- Configuration / Handlers / Request / Types / OAuth Quirks
- Examples
- [express][examples] / [koa][examples] / [hapi][examples] / [fastify][examples] / [aws][grant-aws] / [azure][grant-azure] / [gcloud][grant-gcloud] / [vercel][grant-vercel]
- [Changelog][changelog]

----

Handlers

$3

Express

``js var express = require('express') var session = require('express-session') var grant = require('grant').express()

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

Koa

`js var Koa = require('koa') var session = require('koa-session') var grant = require('grant').koa()

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

Hapi

`js 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/handler-hapi {plugin: yar, options: {cookieOptions: {password: 'grant', isSecure: false}}}, // mount grant {plugin: grant({/configuration - see below/})} ])`

Fastify

`js var fastify = require('fastify') var cookie = require('@fastify/cookie') var session = require('@fastify/session') var grant = require('grant').fastify()

fastify() .register(cookie) .register(session, {secret: 'grant', cookie: {secure: false}}) .register(grant({/configuration - see below/}))`

`$3`

AWS Lambda

`js var grant = require('grant').aws({ config: {/configuration - see below/}, session: {secret: 'grant'} })

exports.handler = async (event) => { var {redirect, response} = await grant(event) return redirect || { statusCode: 200, headers: {'content-type': 'application/json'}, body: JSON.stringify(response) } }`

Azure Function

`js var grant = require('grant').azure({ config: {/configuration - see below/}, session: {secret: 'grant'} })

module.exports = async (context, req) => { var {redirect, response} = await grant(req) return redirect || { status: 200, headers: {'content-type': 'application/json'}, body: JSON.stringify(response) } }`

Google Cloud Function

`js var grant = require('grant').gcloud({ config: {/configuration - see below/}, session: {secret: 'grant'} })

exports.handler = async (req, res) => { var {response} = await grant(req, res) if (response) { res.statusCode = 200 res.setHeader('content-type', 'application/json') res.end(JSON.stringify(response)) } }`

Vercel

`js var grant = require('grant').vercel({ config: {/configuration - see below/}, session: {secret: 'grant'} })

module.exports = async (req, res) => { var {response} = await grant(req, res) if (response) { res.statusCode = 200 res.setHeader('content-type', 'application/json') res.end(JSON.stringify(response)) } }`

`$3`

> __[express][examples] / [koa][examples] / [hapi][examples] / [fastify][examples] / [aws][grant-aws] / [azure][grant-azure] / [gcloud][grant-gcloud] / [vercel][grant-vercel]__

> _ES Modules and TypeScript_

---

`Configuration`

`Configuration: Basics`

`json { "defaults": { "origin": "http://localhost:3000", "transport": "session", "state": true }, "google": { "key": "...", "secret": "...", "scope": ["openid"], "nonce": true, "custom_params": {"access_type": "offline"}, "callback": "/hello" }, "twitter": { "key": "...", "secret": "...", "callback": "/hi" } }`

- defaults - default configuration for all providers - origin - where your client server can be reachedhttp://localhost:3000 | https://site.com... - transport - a transport used to deliver the response data in yourcallbackroute - state - generate random state string - provider - any supported providergoogle | twitter... - key -consumer_key or client_idof your OAuth app - secret -consumer_secret or client_secretof your OAuth app - scope - array of OAuth scopes to request - nonce - generate random nonce string (OpenID Connect only) - custom_params - custom authorization parameters - callback - relative route or absolute URL to receive the response data/hello | https://site.com/hey ...

`Configuration: Description`

`Configuration: Values`

Key | Location | Value :- | :-: | :-: Authorization Server |request_url | [oauth.json] | 'https://api.twitter.com/oauth/request_token'authorize_url | [oauth.json] | 'https://api.twitter.com/oauth/authenticate'access_url | [oauth.json] | 'https://api.twitter.com/oauth/access_token'oauth | [oauth.json] | 2 1scope_delimiter | [oauth.json] | ',' ' 'token_endpoint_auth_method | [provider] | 'client_secret_post' 'client_secret_basic' 'private_key_jwt'token_endpoint_auth_signing_alg | [provider] | 'RS256' 'ES256' 'PS256'Client Server |origin | defaults | 'http://localhost:3000' https://site.comprefix | defaults | '/connect' /oauth ''state | defaults | truenonce | defaults | truepkce | defaults | trueresponse | defaults | ['tokens', 'raw', 'jwt', 'profile']transport | defaults | 'querystring' 'session' 'state'callback | [provider] | '/hello' 'https://site.com/hi'overrides | [provider] | {something: {scope: ['..']}}dynamic | [provider] | ['scope', 'subdomain']Client App |key client_id consumer_key | [provider] | '123'secret client_secret consumer_secret | [provider] | '123'scope | [provider] | ['openid', '..']custom_params | [provider] | {access_type: 'offline'}subdomain | [provider] | 'myorg'public_key | [provider] | '..PEM..' '{..JWK..}'private_key | [provider] | '..PEM..' '{..JWK..}'redirect_uri |generated | 'http://localhost:3000/connect/twitter/callback'Grant |name |generated | name: 'twitter'[provider] |generated | twitter: trueprofile_url | [profile.json] | 'https://api.twitter.com/1.1/users/show.json'

`Configuration: Scopes`

Grant relies on configuration gathered from 6 different places:

1. The first place Grant looks for configuration is the built-in [oauth.json] file located in the config folder.

2. The second place Grant looks for configuration is the defaults key, specified in the user's configuration. These defaults are applied for every provider in the user's configuration.

3. The third place for configuration is the provider itself. All providers in the user's configuration inherit every option defined for them in the [oauth.json] file, and all options defined inside the defaults key. Having [oauth.json] file and a defaults configuration is only a convenience. You can define all available options directly for a provider.

4. The fourth place for configuration are the provider's overrides. The static overrides inherit their parent provider, essentially creating new provider of the same type.

5. The fifth place for configuration is the dynamic state override. The request/response lifecycle state of your HTTP framework of choice can be used to dynamically override configuration.

6. The sixth place for configuration, that _potentially_ can override all of the above, and make all of the above optional, is the dynamic HTTP override.

---

`Connect`

`Connect: Origin`

The origin is where your client server can be reached:

`json { "defaults": { "origin": "http://localhost:3000" } }`

You login by navigating to the /connect/:provider route where :provider is a key in your configuration, usually one of the officially supported ones, but you can define your own as well. Additionally you can login through a static override defined for that provider by navigating to the /connect/:provider/:override? route.

`Connect: Prefix`

By default Grant operates on the following two routes:

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

However, the default /connect prefix can be configured:

`json { "defaults": { "origin": "http://localhost:3000", "prefix": "/oauth" } }`

`Connect: Redirect URI`

The redirect_uri of your OAuth app should follow this format:

`[origin][prefix]/[provider]/callback`

Where origin and prefix have to match the ones set in your configuration, and provider is a provider key found in your configuration.

For example: http://localhost:3000/connect/google/callback

This redirect URI is used internally by Grant. Depending on the transport being used you will receive the response data in the callback route or absolute URL configured for that provider.

`Connect: Custom Parameters`

Some providers may employ custom authorization parameters that you can configure using the custom_params key:

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

`Connect: OpenID Connect`

The openid scope is required, and generating a random nonce string is optional but recommended:

`json { "google": { "scope": ["openid"], "nonce": true } }`

Grant does not verify the signature of the returned id_token by default.

However, the following two claims of the id_token are being validated:

1. aud- is the token intended for my OAuth app? 2.nonce - does it tie to a request of my own?

`Connect: PKCE`

PKCE can be enabled for all providers or for a specific provider only:

`json { "google": { "pkce": true } }`

Providers that do not support PKCE will ignore the additional parameters being sent.

`Connect: Static Overrides`

Provider sub configurations can be configured using the overrides key:

`json { "github": { "key": "...", "secret": "...", "scope": ["public_repo"], "callback": "/hello", "overrides": { "notifications": { "key": "...", "secret": "...", "scope": ["notifications"] }, "all": { "scope": ["repo", "gist", "user"], "callback": "/hey" } } } }`

Navigate to:

- /connect/github to request the public_repo scope-/connect/github/notifications to request the notifications scope using another OAuth App (key and secret) -/connect/github/all to request a bunch of scopes and also receive the response data in another callback route

---

`Callback`

`Callback: Data`

By default the response data will be returned in your callback route or absolute URL encoded as querystring.

Depending on the transport being used the response data can be returned in the session or in the state object instead.

The amount of the returned data can be controlled by using the response configuration.

`$3`

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

The refresh_token is optional. The id_token is returned only for OpenID Connect providers requesting the openid scope.

`$3`

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

`$3`

`js { error: { some: 'error data' } }`

`Callback: Transport`

`$3`

By default Grant will encode the OAuth response data as querystring in your callback route or absolute URL:

`json { "github": { "callback": "https://site.com/hello" } }`

This is useful when using Grant as OAuth Proxy. However this final https://site.com/hello?access_token=... redirect potentially may leak private data in your server logs, especially when sitting behind a reverse proxy.

`$3`

For local callback routes the session transport is recommended:

`json { "defaults": { "transport": "session" }, "github": { "callback": "/hello" } }`

This will make the OAuth response data available in the session object instead:

`js req.session.grant.response // Express ctx.session.grant.response // Koa req.yar.get('grant').response // Hapi req.session.grant.response // Fastify (await session.get()).grant.response // Serverless Function`

`$3`

The request/response lifecycle state can be used as well:

`json { "defaults": { "transport": "state" } }`

In this case a callback route is not needed, and it will be ignored if provided. The response data will be available in the request/response lifecycle state object instead:

`js res.locals.grant.response // Express ctx.state.grant.response // Koa req.plugins.grant.response // Hapi res.grant.response // Fastify var {response} = await grant(...) // Serverless Function`

`Callback: Response`

By default Grant returns all of the available tokens and the raw response data returned by the Authorization server:

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

`$3`

When using the querystring transport it might be a good idea to limit the response data:

`json { "defaults": { "response": ["tokens"] } }`

This will return only the tokens available, without the raw response data.

This is useful when using Grant as OAuth Proxy. Encoding potentially large amounts of data as querystring can lead to incompatibility issues with some servers and browsers, and generally is considered a bad practice.

`$3`

Using the session transport is generally safer, but it also depends on the implementation of your session store.

In case your session store encodes the entire session in a cookie, not just the session ID, some servers may reject the HTTP request because of HTTP headers size being too big.

`json { "google": { "response": ["tokens"] } }`

This will return only the tokens available, without the raw response data.

`$3`

Grant can also return even larger response data by including the decoded JWT for OpenID Connect providers that return id_token:

`json { "google": { "response": ["tokens", "raw", "jwt"] } }`

This will make the decoded JWT available in the response data:

`js { id_token: '...', access_token: '...', refresh_token: '...', raw: { id_token: '...', access_token: '...', refresh_token: '...', some: 'other data' }, jwt: {id_token: {header: {}, payload: {}, signature: '...'}} }`

Make sure you include all of the response keys that you want to be returned when configuring the response data explicitly.

`$3`

Outside of the regular OAuth flow, Grant can also request the user profile:

`json { "google": { "response": ["tokens", "profile"] } }`

Additionaly a profile key will be available in the response data:

`js { access_token: '...', refresh_token: '...', profile: {some: 'user data'} }`

The profile key contains either the raw response data returned by the user profile endpoint or an error message.

Not all of the supported providers have their profile_url set, and some of them might require custom parameters. Usually the user profile endpoint is accessible only when certain scopes were requested.

`Callback: Session`

Grant uses session to persist state between HTTP redirects occurring during the OAuth flow. This session, however, was never meant to be used as persistent storage, even if that's totally possible.

Once you receive the response data in your callback route you are free to destroy that session.

However, there are a few session keys returned in your callback route, that you may find useful:

---

`Dynamic Configuration`

`Dynamic: Instance`

Every Grant instance have a config property attached to it:

`js var grant = Grant(require('./config')) console.log(grant.config)`

You can use the config property to alter the Grant's behavior during runtime without having to restart your server.

This property contains the generated configuration used internally by Grant, and changes made to that configuration affects the entire Grant instance!

`Dynamic: State`

The request/response lifecycle state can be used to alter configuration on every request:

`js var state = {dynamic: {subdomain: 'usershop'}} res.locals.grant = state // Express ctx.state.grant = state // Koa req.plugins.grant = state // Hapi req.grant = state // Fastify await grant(..., state) // Serverless Function`

This is useful in cases when you want to configure Grant dynamically with potentially sensitive data that you don't want to send over HTTP.

The request/response lifecycle state is not controlled by the dynamic configuration, meaning that you can override any configuration key.

Any allowed dynamic configuration key sent through HTTP GET/POST request will override the identical one set using a state override.

`Dynamic: HTTP`

The dynamic configuration allows certain configuration keys to be set dynamically over HTTP GET/POST request.

For example shopify requires your shop name to be embedded into the OAuth URLs, so it makes sense to allow the subdomain configuration key to be set dynamically:

`json { "shopify": { "dynamic": ["subdomain"] } }`

Then you can have a web form on your website allowing the user to specify the shop name:

`html

Making a POST request to the /connect/:provider/:override? route requires a form body parser middleware:

`js .use(require('body-parser').urlencoded({extended: true})) // Express .use(require('koa-bodyparser')()) // Koa .register(require('@fastify/formbody')) // Fastify`

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

`https://awesome.com/connect/shopify?subdomain=usershop`

Any dynamic configuration sent over HTTP GET/POST request overrides any other configuration.

`Dynamic: OAuth Proxy`

In case you really want to, you can allow dynamic configuration override of every configuration key for a provider:

`json { "github": { "dynamic": true } }`

And the most extreme case is allowing even non preconfigured providers to be used dynamically:

`json { "defaults": { "dynamic": true } }`

Essentially Grant is a completely transparent [OAuth Proxy][oauth-like-a-boss].

---

`Misc`

`Misc: Redirect URI`

The origin and the prefix configuration is used to generate the correct redirect_uri that Grant expects:

`json { "defaults": { "origin": "https://mysite.com" }, "google": {}, "twitter": {} }`

The above configuration is identical to:

`json { "google": { "redirect_uri": "https://mysite.com/connect/google/callback" }, "twitter": { "redirect_uri": "https://mysite.com/connect/twitter/callback" } }`

Explicitly specifying the redirect_uri overrides the one generated by default.

`Misc: Custom Providers`

You can define your own provider by adding a key for it in your configuration. In this case all of the required configuration keys have to be specified:

`json { "defaults": { "origin": "http://localhost:3000" }, "awesome": { "authorize_url": "https://awesome.com/authorize", "access_url": "https://awesome.com/token", "oauth": 2, "key": "...", "secret": "...", "scope": ["read", "write"] } }`

Take a look at the [oauth.json] file on how various providers are being configured.

`Misc: Meta Configuration`

You can document your configuration by adding custom keys to it:

`json { "google": { "meta": { "app": "My Awesome OAuth App", "owner": "my_email@gmail.com", "url": "https://url/to/manage/oauth/app" } } }`

Note that meta is arbitrary key, but it cannot be one of the [reserved keys][reserved-keys].

`Misc: Handler Constructors`

Grant supports different ways of instantiation:

`js // Express or any other handler var grant = require('grant').express()(config) var grant = require('grant').express()({config, ...}) var grant = require('grant').express(config) var grant = require('grant').express({config, ...}) var grant = require('grant')({handler: 'express', config, ...})`

Using the new keyword is optional:

`js var Grant = require('grant').express() var grant = Grant(config) var grant = new Grant(config)`

Additionally Hapi accepts the configuration in two different ways:

`js server.register([{plugin: grant(config)}]) server.register([{plugin: grant(), options: config}])`

`Misc: Path Prefix`

You can mount Grant under specific path prefix:

`js // Express app.use('/oauth', grant(config)) // Koa - using koa-mount app.use(mount('/oauth', grant(config))) // Hapi server.register([{routes: {prefix: '/oauth'}, plugin: grant(config)}]) // Fastify server.register(grant(config), {prefix: '/oauth'})`

In this case the prefix configuration should reflect that + any other path parts that you may have:

`json { "defaults": { "origin": "http://localhost:3000", "prefix": "/oauth/login" } }`

In this case you login by navigating to: http://localhost:3000/oauth/login/:provider

And the redirect_uri of your OAuth app should be http://localhost:3000/oauth/login/:provider/callback

Optionally you can prefix your callback routes as well:

`json { "github": { "callback": "/oauth/login/hello" } }`

`Misc: Request`

The underlying [HTTP client] can be configured using the request option:

`js var grant = require('grant').express({ config, request: {agent, timeout: 5000} })`

Fancy [request logs] are available too:

`bash npm i --save-dev request-logs DEBUG=req,res,json node app.js`

`Misc: ES Modules and TypeScript`

Import Grant in your .mjs files:

`js import express from 'express' import session from 'express-session' import grant from 'grant' import config from './config.json'

express() .use(session({})) .use(grant.express(config))`

Importing a .json file may require additional flag:

`bash node --experimental-json-modules app.mjs`

Grant ships with extensive [type definitions][type-definitions] for TypeScript. Additonal type definitions and examples can be found [here][grant-types].

`Misc: OAuth Quirks`

`$3`

Some providers have dynamic URLs containing bits of user information embedded into them. Inside the main [oauth.json] configuration file such URLs contain a [subdomain] token embedded in them.

The subdomain option can be used to specify your company name, server region etc:

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

Then Grant will generate the correct OAuth URLs:

`json "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 authorize_url and access_url in your configuration.

`$3`

Some providers may have Sandbox URLs to use while developing your app. To use them just override the entire request_url, authorize_url and access_url in your configuration (notice the sandbox bits):

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

`$3`

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

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

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

In this case you'll have to redirect the user to the [origin][prefix]/[provider]/callback route that Grant uses to execute the last step of the OAuth flow:

`js 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)}) } })`

As usual you will receive the response data in your final callback route.

`$3`

> Ebay

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

`json "ebay": { "redirect_uri": "RUNAME" }`

> Flickr, Freelancer, Optimizely

Some providers are using custom authorization parameter to pass the requested scopes - Flickr perms, Freelancer advanced_scopes, Optimizely scopes, but you can use the regular scope option instead:

`json "flickr": { "scope": ["write"] }, "freelancer": { "scope": ["1", "2"] }, "optimizely": { "scope": ["all"] }`

> Mastodon

Mastodon requires the entire domain of your server to be embedded in the OAuth URLs. However you should use the subdomain option:

`json "mastodon": { "subdomain": "mastodon.cloud" }`

> Openstreetmap

Openstreetmap OAuth 2.0 applications have to use theopenstreetmap2 provider:

`json "openstreetmap2": { "state": true, "scope": [ "openid", "read_prefs" ] }`

> SurveyMonkey

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

`json "surveymonkey": { "key": "MASHERY_USER_NAME", "secret": "CLIENT_SECRET", "custom_params": {"api_key": "CLIENT_ID"} }`

> Twitter

Twitter OAuth 1.0a custom scope parameter can be specified in two ways:

`json "twitter": { "custom_params": {"x_auth_access_type": "read"} } "twitter": { "scope": ["read"] }`

Twitter OAuth 2.0 applications have to use the twitter2 provider:

`json "twitter2": { "state": true, "pkce": true, "scope": [ "users.read", "tweet.read" ] }`

> VisualStudio

Set your Client Secret as secret not the App Secret:

`json "visualstudio": { "key": "APP_ID", "secret": "CLIENT_SECRET instead of APP_SECRET" }``

---

[npm-version]: https://img.shields.io/npm/v/grant.svg?style=flat-square (NPM Version)
[test-ci-img]: https://img.shields.io/github/actions/workflow/status/simov/grant/test.yml?style=flat-square (Build Status)
[test-cov-img]: https://img.shields.io/coveralls/simov/grant.svg?style=flat-square (Test Coverage)
[snyk-vulnerabilities]: https://img.shields.io/badge/vulnerabilities-0-geen?style=flat-square (Vulnerabilities)

[npm]: https://www.npmjs.com/package/grant
[test-ci-url]: https://github.com/simov/grant/actions/workflows/test.yml
[test-cov-url]: https://coveralls.io/r/simov/grant?branch=master
[snyk]: https://snyk.io/test/npm/grant

[grant-oauth]: https://grant.outofindex.com
[oauth-like-a-boss]: https://dev.to/simov/oauth-like-a-boss-2m3b
[http client]: https://github.com/simov/request-compose
[request logs]: https://github.com/simov/request-logs

[oauth.json]: https://github.com/simov/grant/blob/master/config/oauth.json
[profile.json]: https://github.com/simov/grant/blob/master/config/profile.json
[reserved-keys]: https://github.com/simov/grant/blob/master/config/reserved.json
[examples]: https://github.com/simov/grant/tree/master/examples
[changelog]: https://github.com/simov/grant/blob/master/CHANGELOG.md
[migration]: https://github.com/simov/grant/blob/master/MIGRATION.md

[grant-aws]: https://github.com/simov/grant-aws
[grant-azure]: https://github.com/simov/grant-azure
[grant-gcloud]: https://github.com/simov/grant-gcloud
[grant-vercel]: https://github.com/simov/grant-vercel

[grant-types]: https://github.com/simov/grant-types
[type-definitions]: https://github.com/simov/grant/blob/master/grant.d.ts

Grant

[![npm-version]][npm] [![test-ci-img]][test-ci-url] [![test-cov-img]][test-cov-url] [![snyk-vulnerabilities]][snyk]

> _OAuth Proxy_

200+ Supported Providers / [OAuth Playground][grant-oauth]

$3

----

Handlers

$3

Express

``js var express = require('express') var session = require('express-session') var grant = require('grant').express()

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

Koa

`js var Koa = require('koa') var session = require('koa-session') var grant = require('grant').koa()

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

Hapi

`js var Hapi = require('hapi') var yar = require('yar') var grant = require('grant').hapi()

Fastify

`js var fastify = require('fastify') var cookie = require('@fastify/cookie') var session = require('@fastify/session') var grant = require('grant').fastify()

fastify() .register(cookie) .register(session, {secret: 'grant', cookie: {secure: false}}) .register(grant({/configuration - see below/}))`

`$3`

AWS Lambda

`js var grant = require('grant').aws({ config: {/configuration - see below/}, session: {secret: 'grant'} })

Azure Function

`js var grant = require('grant').azure({ config: {/configuration - see below/}, session: {secret: 'grant'} })

Google Cloud Function

`js var grant = require('grant').gcloud({ config: {/configuration - see below/}, session: {secret: 'grant'} })

Vercel

`js var grant = require('grant').vercel({ config: {/configuration - see below/}, session: {secret: 'grant'} })

`$3`

> __[express][examples] / [koa][examples] / [hapi][examples] / [fastify][examples] / [aws][grant-aws] / [azure][grant-azure] / [gcloud][grant-gcloud] / [vercel][grant-vercel]__

> _ES Modules and TypeScript_

---

`Configuration`

`Configuration: Basics`

`Configuration: Description`

`Configuration: Values`

`Configuration: Scopes`

Grant relies on configuration gathered from 6 different places:

1. The first place Grant looks for configuration is the built-in [oauth.json] file located in the config folder.

2. The second place Grant looks for configuration is the defaults key, specified in the user's configuration. These defaults are applied for every provider in the user's configuration.

4. The fourth place for configuration are the provider's overrides. The static overrides inherit their parent provider, essentially creating new provider of the same type.

5. The fifth place for configuration is the dynamic state override. The request/response lifecycle state of your HTTP framework of choice can be used to dynamically override configuration.

6. The sixth place for configuration, that _potentially_ can override all of the above, and make all of the above optional, is the dynamic HTTP override.

---

`Connect`

`Connect: Origin`

The origin is where your client server can be reached:

`json { "defaults": { "origin": "http://localhost:3000" } }`

`Connect: Prefix`

By default Grant operates on the following two routes:

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

However, the default /connect prefix can be configured:

`json { "defaults": { "origin": "http://localhost:3000", "prefix": "/oauth" } }`

`Connect: Redirect URI`

The redirect_uri of your OAuth app should follow this format:

`[origin][prefix]/[provider]/callback`

Where origin and prefix have to match the ones set in your configuration, and provider is a provider key found in your configuration.

For example: http://localhost:3000/connect/google/callback

This redirect URI is used internally by Grant. Depending on the transport being used you will receive the response data in the callback route or absolute URL configured for that provider.

`Connect: Custom Parameters`

Some providers may employ custom authorization parameters that you can configure using the custom_params key:

`Connect: OpenID Connect`

The openid scope is required, and generating a random nonce string is optional but recommended:

`json { "google": { "scope": ["openid"], "nonce": true } }`

Grant does not verify the signature of the returned id_token by default.

However, the following two claims of the id_token are being validated:

1. aud- is the token intended for my OAuth app? 2.nonce - does it tie to a request of my own?

`Connect: PKCE`

PKCE can be enabled for all providers or for a specific provider only:

`json { "google": { "pkce": true } }`

Providers that do not support PKCE will ignore the additional parameters being sent.

`Connect: Static Overrides`

Provider sub configurations can be configured using the overrides key:

Navigate to:

---

`Callback`

`Callback: Data`

By default the response data will be returned in your callback route or absolute URL encoded as querystring.

Depending on the transport being used the response data can be returned in the session or in the state object instead.

The amount of the returned data can be controlled by using the response configuration.

`$3`

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

The refresh_token is optional. The id_token is returned only for OpenID Connect providers requesting the openid scope.

`$3`

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

`$3`

`js { error: { some: 'error data' } }`

`Callback: Transport`

`$3`

By default Grant will encode the OAuth response data as querystring in your callback route or absolute URL:

`json { "github": { "callback": "https://site.com/hello" } }`

`$3`

For local callback routes the session transport is recommended:

`json { "defaults": { "transport": "session" }, "github": { "callback": "/hello" } }`

This will make the OAuth response data available in the session object instead:

`$3`

The request/response lifecycle state can be used as well:

`json { "defaults": { "transport": "state" } }`

In this case a callback route is not needed, and it will be ignored if provided. The response data will be available in the request/response lifecycle state object instead:

`js res.locals.grant.response // Express ctx.state.grant.response // Koa req.plugins.grant.response // Hapi res.grant.response // Fastify var {response} = await grant(...) // Serverless Function`

`Callback: Response`

By default Grant returns all of the available tokens and the raw response data returned by the Authorization server:

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

`$3`

When using the querystring transport it might be a good idea to limit the response data:

`json { "defaults": { "response": ["tokens"] } }`

This will return only the tokens available, without the raw response data.

`$3`

Using the session transport is generally safer, but it also depends on the implementation of your session store.

In case your session store encodes the entire session in a cookie, not just the session ID, some servers may reject the HTTP request because of HTTP headers size being too big.

`json { "google": { "response": ["tokens"] } }`

This will return only the tokens available, without the raw response data.

`$3`

Grant can also return even larger response data by including the decoded JWT for OpenID Connect providers that return id_token:

`json { "google": { "response": ["tokens", "raw", "jwt"] } }`

This will make the decoded JWT available in the response data:

Make sure you include all of the response keys that you want to be returned when configuring the response data explicitly.

`$3`

Outside of the regular OAuth flow, Grant can also request the user profile:

`json { "google": { "response": ["tokens", "profile"] } }`

Additionaly a profile key will be available in the response data:

`js { access_token: '...', refresh_token: '...', profile: {some: 'user data'} }`

The profile key contains either the raw response data returned by the user profile endpoint or an error message.

`Callback: Session`

Grant uses session to persist state between HTTP redirects occurring during the OAuth flow. This session, however, was never meant to be used as persistent storage, even if that's totally possible.

Once you receive the response data in your callback route you are free to destroy that session.

However, there are a few session keys returned in your callback route, that you may find useful:

---

`Dynamic Configuration`

`Dynamic: Instance`

Every Grant instance have a config property attached to it:

`js var grant = Grant(require('./config')) console.log(grant.config)`

You can use the config property to alter the Grant's behavior during runtime without having to restart your server.

This property contains the generated configuration used internally by Grant, and changes made to that configuration affects the entire Grant instance!

`Dynamic: State`

The request/response lifecycle state can be used to alter configuration on every request:

This is useful in cases when you want to configure Grant dynamically with potentially sensitive data that you don't want to send over HTTP.

The request/response lifecycle state is not controlled by the dynamic configuration, meaning that you can override any configuration key.

Any allowed dynamic configuration key sent through HTTP GET/POST request will override the identical one set using a state override.

`Dynamic: HTTP`

The dynamic configuration allows certain configuration keys to be set dynamically over HTTP GET/POST request.

For example shopify requires your shop name to be embedded into the OAuth URLs, so it makes sense to allow the subdomain configuration key to be set dynamically:

`json { "shopify": { "dynamic": ["subdomain"] } }`

Then you can have a web form on your website allowing the user to specify the shop name:

`html

Making a POST request to the /connect/:provider/:override? route requires a form body parser middleware:

`js .use(require('body-parser').urlencoded({extended: true})) // Express .use(require('koa-bodyparser')()) // Koa .register(require('@fastify/formbody')) // Fastify`

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

`https://awesome.com/connect/shopify?subdomain=usershop`

Any dynamic configuration sent over HTTP GET/POST request overrides any other configuration.

`Dynamic: OAuth Proxy`

In case you really want to, you can allow dynamic configuration override of every configuration key for a provider:

`json { "github": { "dynamic": true } }`

And the most extreme case is allowing even non preconfigured providers to be used dynamically:

`json { "defaults": { "dynamic": true } }`

Essentially Grant is a completely transparent [OAuth Proxy][oauth-like-a-boss].

---

`Misc`

`Misc: Redirect URI`

The origin and the prefix configuration is used to generate the correct redirect_uri that Grant expects:

`json { "defaults": { "origin": "https://mysite.com" }, "google": {}, "twitter": {} }`

The above configuration is identical to:

`json { "google": { "redirect_uri": "https://mysite.com/connect/google/callback" }, "twitter": { "redirect_uri": "https://mysite.com/connect/twitter/callback" } }`

Explicitly specifying the redirect_uri overrides the one generated by default.

`Misc: Custom Providers`

You can define your own provider by adding a key for it in your configuration. In this case all of the required configuration keys have to be specified:

Take a look at the [oauth.json] file on how various providers are being configured.

`Misc: Meta Configuration`

You can document your configuration by adding custom keys to it:

`json { "google": { "meta": { "app": "My Awesome OAuth App", "owner": "my_email@gmail.com", "url": "https://url/to/manage/oauth/app" } } }`

Note that meta is arbitrary key, but it cannot be one of the [reserved keys][reserved-keys].

`Misc: Handler Constructors`

Grant supports different ways of instantiation:

Using the new keyword is optional:

`js var Grant = require('grant').express() var grant = Grant(config) var grant = new Grant(config)`

Additionally Hapi accepts the configuration in two different ways:

`js server.register([{plugin: grant(config)}]) server.register([{plugin: grant(), options: config}])`

`Misc: Path Prefix`

You can mount Grant under specific path prefix:

In this case the prefix configuration should reflect that + any other path parts that you may have:

`json { "defaults": { "origin": "http://localhost:3000", "prefix": "/oauth/login" } }`

In this case you login by navigating to: http://localhost:3000/oauth/login/:provider

And the redirect_uri of your OAuth app should be http://localhost:3000/oauth/login/:provider/callback

Optionally you can prefix your callback routes as well:

`json { "github": { "callback": "/oauth/login/hello" } }`

`Misc: Request`

The underlying [HTTP client] can be configured using the request option:

`js var grant = require('grant').express({ config, request: {agent, timeout: 5000} })`

Fancy [request logs] are available too:

`bash npm i --save-dev request-logs DEBUG=req,res,json node app.js`

`Misc: ES Modules and TypeScript`

Import Grant in your .mjs files:

`js import express from 'express' import session from 'express-session' import grant from 'grant' import config from './config.json'

express() .use(session({})) .use(grant.express(config))`

Importing a .json file may require additional flag:

`bash node --experimental-json-modules app.mjs`

Grant ships with extensive [type definitions][type-definitions] for TypeScript. Additonal type definitions and examples can be found [here][grant-types].

`Misc: OAuth Quirks`

`$3`

Some providers have dynamic URLs containing bits of user information embedded into them. Inside the main [oauth.json] configuration file such URLs contain a [subdomain] token embedded in them.

The subdomain option can be used to specify your company name, server region etc:

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

Then Grant will generate the correct OAuth URLs:

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

`$3`

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

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

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

In this case you'll have to redirect the user to the [origin][prefix]/[provider]/callback route that Grant uses to execute the last step of the OAuth flow:

`js var qs = require('querystring')

As usual you will receive the response data in your final callback route.

`$3`

> Ebay

`json "ebay": { "redirect_uri": "RUNAME" }`

> Flickr, Freelancer, Optimizely

`json "flickr": { "scope": ["write"] }, "freelancer": { "scope": ["1", "2"] }, "optimizely": { "scope": ["all"] }`

> Mastodon

Mastodon requires the entire domain of your server to be embedded in the OAuth URLs. However you should use the subdomain option:

`json "mastodon": { "subdomain": "mastodon.cloud" }`

> Openstreetmap

Openstreetmap OAuth 2.0 applications have to use theopenstreetmap2 provider:

`json "openstreetmap2": { "state": true, "scope": [ "openid", "read_prefs" ] }`

> SurveyMonkey

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

`json "surveymonkey": { "key": "MASHERY_USER_NAME", "secret": "CLIENT_SECRET", "custom_params": {"api_key": "CLIENT_ID"} }`

> Twitter

Twitter OAuth 1.0a custom scope parameter can be specified in two ways:

`json "twitter": { "custom_params": {"x_auth_access_type": "read"} } "twitter": { "scope": ["read"] }`

Twitter OAuth 2.0 applications have to use the twitter2 provider:

`json "twitter2": { "state": true, "pkce": true, "scope": [ "users.read", "tweet.read" ] }`

> VisualStudio

Set your Client Secret as secret not the App Secret:

`json "visualstudio": { "key": "APP_ID", "secret": "CLIENT_SECRET instead of APP_SECRET" }``

---

[grant-types]: https://github.com/simov/grant-types
[type-definitions]: https://github.com/simov/grant/blob/master/grant.d.ts

grant

Grant

200+ Supported Providers / [OAuth Playground][grant-oauth]

Table of Contents

$3

Handlers

$3

$3

$3

Configuration

Configuration: Basics

Configuration: Description

Configuration: Values

Configuration: Scopes

Connect

Connect: Origin

Connect: Prefix

Connect: Redirect URI

Connect: Custom Parameters

Connect: OpenID Connect

Connect: PKCE

Connect: Static Overrides

Callback

Callback: Data

$3

$3

$3

Callback: Transport

$3

$3

$3

Callback: Response

$3

$3

$3

$3

Callback: Session

Dynamic Configuration

Dynamic: Instance

Dynamic: State

Dynamic: HTTP

Dynamic: OAuth Proxy

Misc

Misc: Redirect URI

Misc: Custom Providers

Misc: Meta Configuration

Misc: Handler Constructors

Misc: Path Prefix

Misc: Request

Misc: ES Modules and TypeScript

Misc: OAuth Quirks

$3

$3

$3

$3

grant

Grant

200+ Supported Providers / [OAuth Playground][grant-oauth]

Table of Contents

$3

Handlers

$3

$3

$3

Configuration

Configuration: Basics

Configuration: Description

Configuration: Values

Configuration: Scopes

Connect

Connect: Origin

Connect: Prefix

Connect: Redirect URI

Connect: Custom Parameters

Connect: OpenID Connect

Connect: PKCE

Connect: Static Overrides

Callback

Callback: Data

$3

`$3`

`$3`

`Configuration`

`Configuration: Basics`

`Configuration: Description`

`Configuration: Values`

`Configuration: Scopes`

`Connect`

`Connect: Origin`

`Connect: Prefix`

`Connect: Redirect URI`

`Connect: Custom Parameters`

`Connect: OpenID Connect`

`Connect: PKCE`

`Connect: Static Overrides`

`Callback`

`Callback: Data`

`$3`

`$3`

`$3`

`Callback: Transport`

`$3`

`$3`

`$3`

`Callback: Response`

`$3`

`$3`

`$3`

`$3`

`Callback: Session`

`Dynamic Configuration`

`Dynamic: Instance`

`Dynamic: State`

`Dynamic: HTTP`

`Dynamic: OAuth Proxy`

`Misc`

`Misc: Redirect URI`

`Misc: Custom Providers`

`Misc: Meta Configuration`

`Misc: Handler Constructors`

`Misc: Path Prefix`

`Misc: Request`

`Misc: ES Modules and TypeScript`

`Misc: OAuth Quirks`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Configuration`

`Configuration: Basics`

`Configuration: Description`

`Configuration: Values`

`Configuration: Scopes`

`Connect`

`Connect: Origin`

`Connect: Prefix`

`Connect: Redirect URI`

`Connect: Custom Parameters`

`Connect: OpenID Connect`

`Connect: PKCE`

`Connect: Static Overrides`

`Callback`

`Callback: Data`

`$3`

`$3`

`$3`

`Callback: Transport`

`$3`

`$3`

`$3`

`Callback: Response`

`$3`

`$3`

`$3`

`$3`

`Callback: Session`

`Dynamic Configuration`

`Dynamic: Instance`