Repository files navigation

OAuth Proxy

23andme |500px |acton |acuityscheduling |adobe |aha |alchemer |amazon |angellist |apple |arcgis |asana |assembla |atlassian |auth0 |authentik |authentiq |authing |autodesk |aweber |axosoft |baidu |basecamp |battlenet |beatport |bitbucket |bitly |box |buffer |campaignmonitor |cas |cheddar |clio |cognito |coinbase |concur |constantcontact |coursera |crossid |dailymotion |deezer |delivery |deputy |deviantart |digitalocean |discogs |discord |disqus |docusign |dribbble |dropbox |ebay |echosign |ecwid |edmodo |egnyte |etsy |eventbrite |evernote |eyeem |facebook |familysearch |feedly |figma |fitbit |flickr |formstack |foursquare |freeagent |freelancer |freshbooks |fusionauth |garmin |geeklist |genius |getbase |getpocket |gitbook |github |gitlab |gitter |goodreads |google |groove |gumroad |harvest |hellosign |heroku |homeaway |hootsuite |huddle |ibm |iconfinder |idme |idonethis |imgur |infusionsoft |instagram |intuit |jamendo |jumplead |kakao |keycloak |line |linkedin |live |livechat |logingov |lyft |mailchimp |mailup |mailxpert |mapmyfitness |mastodon |medium |meetup |mendeley |mention |microsoft |mixcloud |moxtra |myob |naver |nest |netlify |nokotime |notion |nylas |okta |onelogin |openstreetmap |optimizely |osu |patreon |paypal |phantauth |pinterest |plurk |podio |procore |producthunt |projectplace |pushbullet |qq |ravelry |redbooth |reddit |runkeeper |salesforce |sellsy |shoeboxed |shopify |skyrock |slack |slice |smartsheet |smugmug |snapchat |snowflake |socialpilot |socrata |soundcloud |spotify |square |stackexchange |stocktwits |stormz |storyblok |strava |stripe |surveymonkey |surveysparrow |thingiverse |ticketbud |tiktok |timelyapp |todoist |trakt |traxo |trello |tripit |trustpilot |tumblr |twitch |twitter |typeform |uber |unbounce |underarmour |unsplash |untappd |upwork |uservoice |vend |venmo |vercel |verticalresponse |viadeo |vimeo |visualstudio |vk |wechat |weekdone |weibo |withings |wordpress |workos |wrike |xero |xing |yahoo |yammer |yandex |zendesk |zoom

• 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 /koa /hapi /fastify /aws /azure /gcloud /vercel
• Changelog

varexpress=require('express')varsession=require('express-session')vargrant=require('grant').express()varapp=express()// REQUIRED: any session store - see /examples/handler-expressapp.use(session({secret:'grant'}))// mount grantapp.use(grant({/*configuration - see below*/}))

varKoa=require('koa')varsession=require('koa-session')vargrant=require('grant').koa()varapp=newKoa()// REQUIRED: any session store - see /examples/handler-koaapp.keys=['grant']app.use(session(app))// mount grantapp.use(grant({/*configuration - see below*/}))

varHapi=require('hapi')varyar=require('yar')vargrant=require('grant').hapi()varserver=newHapi.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*/})}])

varfastify=require('fastify')varcookie=require('@fastify/cookie')varsession=require('@fastify/session')vargrant=require('grant').fastify()fastify().register(cookie).register(session,{secret:'grant',cookie:{secure:false}}).register(grant({/*configuration - see below*/}))

vargrant=require('grant').aws({config:{/*configuration - see below*/},session:{secret:'grant'}})exports.handler=async(event)=>{var{redirect, response}=awaitgrant(event)returnredirect||{statusCode:200,headers:{'content-type':'application/json'},body:JSON.stringify(response)}}

vargrant=require('grant').azure({config:{/*configuration - see below*/},session:{secret:'grant'}})module.exports=async(context,req)=>{var{redirect, response}=awaitgrant(req)returnredirect||{status:200,headers:{'content-type':'application/json'},body:JSON.stringify(response)}}

vargrant=require('grant').gcloud({config:{/*configuration - see below*/},session:{secret:'grant'}})exports.handler=async(req,res)=>{var{response}=awaitgrant(req,res)if(response){res.statusCode=200res.setHeader('content-type','application/json')res.end(JSON.stringify(response))}}

vargrant=require('grant').vercel({config:{/*configuration - see below*/},session:{secret:'grant'}})module.exports=async(req,res)=>{var{response}=awaitgrant(req,res)if(response){res.statusCode=200res.setHeader('content-type','application/json')res.end(JSON.stringify(response))}}

express /koa /hapi /fastify /aws /azure /gcloud /vercel

ES Modules and TypeScript

{"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 - atransport used to deliver theresponse data in yourcallback route
  • state - generate random state string
• provider - anysupported providergoogle |twitter ...
  • key -consumer_key orclient_id of your OAuth app
  • secret -consumer_secret orclient_secret of your OAuth app
  • scope - array of OAuth scopes to request
  • nonce - generate random nonce string (OpenID Connect only)
  • custom_params - customauthorization parameters
  • callback - relative route or absolute URL to receive the response data/hello |https://site.com/hey ...

Grant relies on configuration gathered from6 different places:

1. Thefirst place Grant looks for configuration is the built-inoauth.json file located in the config folder.

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

3. Thethird place for configuration is the provider itself. All providers in the user's configuration inherit every option defined for them in theoauth.json file, and all options defined inside thedefaults key. Havingoauth.json file and adefaults configuration is only a convenience. You can define all available options directly for a provider.

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

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

6. Thesixth place for configuration, thatpotentially can override all of the above, and make all of the above optional, is thedynamic HTTP override.

Theorigin is where your client server can be reached:

{"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 theofficially supported ones, but you can defineyour own as well. Additionally you can login through astatic override defined for that provider by navigating to the/connect/:provider/:override? route.

By default Grant operates on the following two routes:

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

However, the default/connect prefix can be configured:

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

Theredirect_uri of your OAuth app should follow this format:

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

Whereorigin andprefix have to match the ones set in your configuration, andprovider 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 thetransport being used you will receive the response data in thecallback route or absolute URL configured for that provider.

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

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

Theopenid scope is required, and generating a randomnonce string is optional but recommended:

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

Grantdoes not verify the signature of the returnedid_token by default.

However, the following two claims of theid_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?

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

{"google": {"pkce":true  }}

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

Provider sub configurations can be configured using theoverrides key:

{"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_reposcope
• /connect/github/notifications to request the notificationsscope using another OAuth App (key andsecret)
• /connect/github/all to request a bunch ofscopes and also receive the response data in anothercallback route

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

Depending on thetransport being used the response data can be returned in thesession or in thestate object instead.

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

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

Therefresh_token is optional. Theid_token is returned only forOpenID Connect providers requesting theopenid scope.

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

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

By default Grant will encode the OAuthresponse data asquerystring in yourcallback route or absolute URL:

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

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

For localcallback routes the sessiontransport is recommended:

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

This will make the OAuthresponse data available in thesession object instead:

req.session.grant.response// Expressctx.session.grant.response// Koareq.yar.get('grant').response// Hapireq.session.grant.response// Fastify(awaitsession.get()).grant.response// Serverless Function

The request/response lifecyclestate can be used as well:

{"defaults": {"transport":"state"  }}

In this case acallback 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:

res.locals.grant.response// Expressctx.state.grant.response// Koareq.plugins.grant.response// Hapires.grant.response// Fastifyvar{response}=awaitgrant(...)// Serverless Function

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

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

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

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

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

This is useful when using Grant asOAuth 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.

Using the sessiontransport 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.

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

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

Grant can also return even largerresponse data by including the decoded JWT forOpenID Connect providers that returnid_token:

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

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

{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 theresponse data explicitly.

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

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

Additionaly aprofile key will be available in the response data:

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

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

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

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 theresponse data in yourcallback route you are free to destroy that session.

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

Every Grant instance have aconfig property attached to it:

vargrant=Grant(require('./config'))console.log(grant.config)

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

This property contains thegenerated configuration used internally by Grant, and changes made to that configuration affects theentire Grant instance!

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

varstate={dynamic:{subdomain:'usershop'}}res.locals.grant=state// Expressctx.state.grant=state// Koareq.plugins.grant=state// Hapireq.grant=state// Fastifyawaitgrant(...,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 thedynamic configuration, meaning that you can override any configuration key.

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

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

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

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

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

<formaction="/connect/shopify"method="POST"accept-charset="utf-8"><inputtype="text"name="subdomain"value=""/><button>Login</button></form>

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

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

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

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

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

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

{"github": {"dynamic":true  }}

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

{"defaults": {"dynamic":true  }}

Essentially Grant is a completely transparentOAuth Proxy.

Theorigin and theprefix configuration is used to generate the correctredirect_uri that Grant expects:

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

The above configuration is identical to:

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

Explicitly specifying theredirect_uri overrides the one generated by default.

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:

{"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 theoauth.json file on how various providers are being configured.

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

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

Note thatmeta is arbitrary key, but it cannot be one of thereserved keys.

Grant supports different ways of instantiation:

// Express or any other handlervargrant=require('grant').express()(config)vargrant=require('grant').express()({config, ...})vargrant=require('grant').express(config)vargrant=require('grant').express({config, ...})vargrant=require('grant')({handler:'express', config, ...})

Using thenew keyword is optional:

varGrant=require('grant').express()vargrant=Grant(config)vargrant=newGrant(config)

Additionally Hapi accepts the configuration in two different ways:

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

You can mount Grant under specific path prefix:

// Expressapp.use('/oauth',grant(config))// Koa - using koa-mountapp.use(mount('/oauth',grant(config)))// Hapiserver.register([{routes:{prefix:'/oauth'},plugin:grant(config)}])// Fastifyserver.register(grant(config),{prefix:'/oauth'})

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

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

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

And theredirect_uri of your OAuth app should behttp://localhost:3000/oauth/login/:provider/callback

Optionally you can prefix yourcallback routes as well:

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

The underlyingHTTP client can be configured using therequest option:

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

Fancyrequest logs are available too:

npm i --save-dev request-logsDEBUG=req,res,json node app.js

Import Grant in your.mjs files:

importexpressfrom'express'importsessionfrom'express-session'importgrantfrom'grant'importconfigfrom'./config.json'express().use(session({})).use(grant.express(config))

Importing a.json file may require additional flag:

node --experimental-json-modules app.mjs

Grant ships with extensivetype definitions for TypeScript. Additonal type definitions and examples can be foundhere.

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

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

"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 entireauthorize_url andaccess_url in your configuration.

Some providers may have Sandbox URLs to use while developing your app. To use them just override the entirerequest_url,authorize_url andaccess_url in your configuration (notice thesandbox 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"}

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

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

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

varqs=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 finalcallback route.

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 asredirect_uri in Grant:

"ebay": {"redirect_uri":"RUNAME"}

Flickr, Freelancer, Optimizely

Some providers are using custom authorization parameter to pass the requested scopes - Flickrperms, Freelanceradvanced_scopes, Optimizelyscopes, but you can use the regularscope option instead:

"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 thesubdomain option:

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

Openstreetmap

Openstreetmap OAuth 2.0 applications have to use theopenstreetmap2 provider:

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

SurveyMonkey

Set your Mashery user name askey and your application key asapi_key:

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

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

Twitter OAuth 2.0 applications have to use thetwitter2 provider:

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

VisualStudio

Set your Client Secret assecret not the App Secret:

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