repository·master·Indexed 26 days ago
https://github.com/simov/grantAn OAuth proxy supporting over 200 providers, designed to simplify OAuth flow integration. Grant provides standardized handlers for Node.js frameworks including Express, Koa, Hapi, and Fastify, as well as serverless environments such as AWS Lambda, Azure Functions, Google Cloud Functions, and Vercel. Version 5.4.24.
config.json file in the project root.Grant uses specific URL patterns for the OAuth flow.
Login Route:
Navigate to [origin][prefix]/:provider to initiate login. If using static overrides, use [origin][prefix]/:provider/:override?.
Callback Route:
Grant expects a callback at [origin][prefix]/:provider/callback.
Setting the Redirect URI in your OAuth App:
Your OAuth provider must be configured with a Redirect URI following this format:
[origin][prefix]/[provider]/callback
Example: If origin is http://localhost:3000 and prefix is /connect, the redirect URI for Google would be http://localhost:3000/connect/google/callback.
To add a provider not natively supported by Grant, add a new key to your configuration object. You must specify all required configuration keys, including authorize_url, access_url, oauth (the protocol version), key, secret, and scope.
{
"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"]
}
}The path configuration key used in Grant v4 for setting a path prefix is deprecated. In Grant v5, use the prefix key instead. Note that the prefix should typically include the /connect suffix if you are following standard patterns.
{
"defaults": {
"origin": "http://localhost:3000",
"prefix": "/oauth/connect"
}
}When using the Grant examples to test OAuth 2.0 (e.g., Google) or OAuth 1.0a (e.g., Twitter) flows, you must configure your OAuth provider's dashboard with the following redirect URIs:
http://localhost:3000/connect/google/callbackhttp://localhost:3000/connect/twitter/callbackGrant provides specialized handlers for popular Node.js HTTP frameworks. When using these handlers, you must ensure a session store is configured as Grant relies on sessions for state management.
// Express
var express = require('express')
var session = require('express-session')
var grant = require('grant').express()
var app = express()
app.use(session({secret: 'grant'}))
app.use(grant({/*configuration*/}))
// Koa
var Koa = require('koa')
var session = require('koa-session')
var grant = require('grant').koa()
var app = new Koa()
app.keys = ['grant']
app.use(session(app))
app.use(grant({/*configuration*/}))
// Hapi
var Hapi = require('hapi')
var yar = require('yar')
var grant = require('grant').hapi()
var server = new Hapi.Server()
server.register([
{plugin: yar, options: {cookieOptions: {password: 'grant', isSecure: false}}},
{plugin: grant({/*configuration*/})}
])
// Fastify
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*/}))Some providers (like Shopify or Mastodon) require dynamic URLs. Use the subdomain option in your provider config to inject values into the authorize_url and access_url.
To use a provider's sandbox environment, override the request_url, authorize_url, and access_url in your configuration with the sandbox-specific endpoints.
If a provider (like Feedly) restricts the allowed redirect_uri in sandbox mode, you may need to manually redirect the user to Grant's internal callback route after the provider redirects them back to your origin.
// Subdomain example
"shopify": {
"subdomain": "mycompany"
}
// Sandbox example
"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"
}To use Grant in .mjs files, import it directly. If you are importing a .json configuration file in an ES module, you may need to run Node with the --experimental-json-modules flag. Grant includes built-in TypeScript definitions.
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))The transport setting determines how response data is delivered to your application:
querystring (Default): Encodes data as a query string in the redirect URL. Best for OAuth Proxies, but can leak data in logs.session: Recommended for local routes. Stores data in the session object.req.session.grant.responsectx.session.grant.responsereq.session.grant.responsestate: Uses the request/response lifecycle state. No callback route is needed.res.locals.grant.responsectx.state.grant.responseres.grant.responsevar {response} = await grant(...){
"defaults": {
"transport": "session"
},
"github": {
"callback": "/hello"
}
}In Grant v5, the id_token is returned as a raw string by default. In Grant v4, it was returned as a decoded object containing header, payload, and signature.
Grant v5 default format:
{
id_token: 'abc.abc.abc',
access_token: '...',
refresh_token: '...'
}Once the server is running, you can trigger the OAuth flows by navigating to these specific endpoints in your browser:
http://localhost:3000/connect/googlehttp://localhost:3000/connect/twitter