diff --git a/docs/README.md b/docs/README.md index 9fadf6db..9967a98d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -445,12 +445,13 @@ Performs Dynamic Client Read Request to retrieve a Client instance. - [Customizing HTTP requests](#customizing-http-requests) +- [Customizing individual HTTP requests](#customizing-individual-http-requests) - [Customizing clock skew tolerance](#customizing-clock-skew-tolerance) --- -#### Customizing HTTP Requests +#### Customizing HTTP requests The following are default [`got`][got-library] request [options](https://github.com/sindresorhus/got/tree/v9.6.0#options) that openid-client sets for all @@ -466,7 +467,21 @@ const DEFAULT_HTTP_OPTIONS = { }; ``` -You can change these options by assigning a function to +You may change these global options like so: + +```js +const { custom } = require('openid-client'); + +custom.setHttpOptionsDefaults({ + timeout: 5000, +}); +``` + +This is meant to change global request options such as `timeout` or the default `User-Agent` header. + +#### Customizing individual HTTP requests + +You change options on a per-request basis by assigning a function to - `Issuer` constructor to override the following request's options - discovery @@ -481,7 +496,7 @@ You can change these options by assigning a function to - introspection endpoint requests - revocation endpoint requests -This function will then be called before executing each and every request. +This function will then be called before executing each and every request on the instance or constructor. ```js const { custom } = require('openid-client'); @@ -492,6 +507,9 @@ client[custom.http_options] = function (options) { } ``` +This is meant to change request options on per-request basis should there be a specific IdP quirk +you need to work around, e.g. adding custom headers or body payload parameters. +
Example (Click to expand) providing mutual-TLS client certificate and key diff --git a/lib/helpers/request.js b/lib/helpers/request.js index 9a5e658a..f1bae8c3 100644 --- a/lib/helpers/request.js +++ b/lib/helpers/request.js @@ -1,4 +1,4 @@ -const got = require('got'); +const Got = require('got'); const { defaultsDeep } = require('lodash'); const pkg = require('../../package.json'); @@ -6,15 +6,21 @@ const pkg = require('../../package.json'); const isAbsoluteUrl = require('./is_absolute_url'); const { HTTP_OPTIONS } = require('./consts'); -const USER_AGENT = `${pkg.name}/${pkg.version} (${pkg.homepage})`; +let DEFAULT_HTTP_OPTIONS; +let got; -const DEFAULT_HTTP_OPTIONS = { +const setDefaults = (options) => { + DEFAULT_HTTP_OPTIONS = defaultsDeep(options, DEFAULT_HTTP_OPTIONS); + got = Got.extend(DEFAULT_HTTP_OPTIONS); +}; + +setDefaults({ followRedirect: false, - headers: { 'User-Agent': USER_AGENT }, + headers: { 'User-Agent': `${pkg.name}/${pkg.version} (${pkg.homepage})` }, retry: 0, timeout: 2500, throwHttpErrors: false, -}; +}); module.exports = function request(options, { mTLS = false } = {}) { const { url } = options; @@ -24,7 +30,7 @@ module.exports = function request(options, { mTLS = false } = {}) { if (optsFn) { opts = optsFn.call(this, defaultsDeep(options, DEFAULT_HTTP_OPTIONS)); } else { - opts = defaultsDeep(options, DEFAULT_HTTP_OPTIONS); + opts = options; } if (mTLS && (!opts.key || !opts.cert)) { @@ -32,3 +38,5 @@ module.exports = function request(options, { mTLS = false } = {}) { } return got(opts); }; + +module.exports.setDefaults = setDefaults; diff --git a/lib/index.js b/lib/index.js index f3f113d0..3d35d6be 100644 --- a/lib/index.js +++ b/lib/index.js @@ -5,6 +5,7 @@ const Strategy = require('./passport_strategy'); const TokenSet = require('./token_set'); const { CLOCK_TOLERANCE, HTTP_OPTIONS } = require('./helpers/consts'); const generators = require('./helpers/generators'); +const { setDefaults } = require('./helpers/request'); module.exports = { Issuer, @@ -16,6 +17,7 @@ module.exports = { RPError, }, custom: { + setHttpOptionsDefaults: setDefaults, http_options: HTTP_OPTIONS, clock_tolerance: CLOCK_TOLERANCE, },