Other Options

acceptQueryParamAccessTokens

Several OAuth 2.0 / OIDC profiles prohibit the use of query strings to carry access tokens. This setting either allows (true) or prohibits (false) that mechanism to be used.

default value:

false

acrValues

Array of strings, the Authentication Context Class References that the authorization server supports.

default value:

[]

allowOmittingSingleRegisteredRedirectUri

Allow omitting the redirect_uri parameter when only a single one is registered for a client.

default value:

true

assertJwtClientAuthClaimsAndHeader

Helper function used to validate the JWT Client Authentication Assertion Claims Set and Header beyond what its specification mandates.

default value:

async function assertJwtClientAuthClaimsAndHeader(ctx, claims, header, client) {
  // @param ctx - koa request context
  // @param claims - parsed JWT Client Authentication Assertion Claims Set as object
  // @param header - parsed JWT Client Authentication Assertion Headers as object
  // @param client - the Client instance
}

clockTolerance

A Number value (in seconds) describing the allowed system clock skew for validating client-provided JWTs, e.g. Request Objects, DPoP Proofs and otherwise comparing timestamps

recommendation: Only set this to a reasonable value when needed to cover server-side client and oidc-provider server clock skew.

default value:

15

conformIdTokenClaims

ID Token only contains End-User claims when the requested response_type is id_token

OIDC Core 1.0 - Requesting Claims using Scope Values defines that claims requested using the scope parameter are only returned from the UserInfo Endpoint unless the response_type is id_token.
Despite of this configuration the ID Token always includes claims requested using the scope parameter when the userinfo endpoint is disabled, or when issuing an Access Token not applicable for access to the userinfo endpoint.

default value:

true

discovery

Pass additional properties to this object to extend the discovery document

default value:

{
  claim_types_supported: [
    'normal'
  ],
  claims_locales_supported: undefined,
  display_values_supported: undefined,
  op_policy_uri: undefined,
  op_tos_uri: undefined,
  service_documentation: undefined,
  ui_locales_supported: undefined
}

extraParams

Pass an iterable object (i.e. Array or Set of strings) to extend the parameters recognised by the authorization, device authorization, backchannel authentication, and pushed authorization request endpoints. These parameters are then available in ctx.oidc.params as well as passed to interaction session details.

This may also be a plain object with string properties representing parameter names and values being either a function or async function to validate said parameter value. These validators are executed regardless of the parameters’ presence or value such that this can be used to validate presence of custom parameters as well as to assign default values for them. If the value is null or undefined the parameter is added without a validator. Note that these validators execute near the very end of the request’s validation process and changes to (such as assigning default values) other parameters will not trigger any re-validation of the whole request again.

default value:

[]

(Click to expand) registering an extra origin parameter with its validator

import { errors } from 'oidc-provider';
const extraParams = {
  async origin(ctx, value, client) {
    // @param ctx - koa request context
    // @param value - the `origin` parameter value (string or undefined)
    // @param client - client making the request
    if (hasDefaultOrigin(client)) {
      // assign default
      ctx.oidc.params.origin ||= value ||= getDefaultOrigin(client);
    }
    if (!value && requiresOrigin(ctx, client)) {
      // reject when missing but required
      throw new errors.InvalidRequest('"origin" is required for this request')
    }
    if (!allowedOrigin(value, client)) {
      // reject when not allowed
      throw new errors.InvalidRequest('requested "origin" is not allowed for this client')
    }
  }
}

httpOptions

Function called whenever calls to an external HTTP(S) resource are being made. You can change the request timeout through the signal option, the request agent used, the user-agent string used for the user-agent HTTP header, as well as the dnsLookup resolver function.

default value:

function httpOptions(url) {
  return {
    signal: undefined, // defaults to AbortSignal.timeout(2500)
    agent: undefined, // defaults to node's global agents (https.globalAgent or http.globalAgent)
    dnsLookup: undefined, // defaults to `dns.lookup()` (https://nodejs.org/api/dns.html#dnslookuphostname-options-callback)
    'user-agent': undefined, // defaults to not sending the user-agent HTTP header
  };
}

(Click to expand) To change the request’s timeout

To change all request’s timeout configure the httpOptions as a function like so:

 {
   httpOptions(url) {
     return { signal: AbortSignal.timeout(5000) };
   }
 }

loadExistingGrant

Helper function used to load existing but also just in time pre-established Grants to attempt to resolve an Authorization Request with. Default: loads a grant based on the interaction result consent.grantId first, falls back to the existing grantId for the client in the current session.

default value:

async function loadExistingGrant(ctx) {
  const grantId = (ctx.oidc.result?.consent?.grantId)
    || ctx.oidc.session.grantIdFor(ctx.oidc.client.clientId);
  if (grantId) {
    return ctx.oidc.provider.Grant.find(grantId);
  }
  return undefined;
}

pairwiseIdentifier

Function used by the authorization server when resolving pairwise ID Token and Userinfo sub claim values. See OIDC Core 1.0

recommendation: Since this might be called several times in one request with the same arguments consider using memoization or otherwise caching the result based on account and client ids.

default value:

async function pairwiseIdentifier(ctx, accountId, client) {
  return crypto.createHash('sha256')
    .update(client.sectorIdentifier)
    .update(accountId)
    .update(os.hostname()) // put your own unique salt here, or implement other mechanism
    .digest('hex');
}

renderError

Function used to present errors to the User-Agent

default value:

async function renderError(ctx, out, error) {
  ctx.type = 'html';
  ctx.body = `<!DOCTYPE html>
    <html>
    <head>
      <title>oops! something went wrong</title>
      <style>/* css and html classes omitted for brevity, see lib/helpers/defaults.js */</style>
    </head>
    <body>
      <div>
        <h1>oops! something went wrong</h1>
        ${Object.entries(out).map(([key, value]) => `<pre><strong>${key}</strong>: ${htmlSafe(value)}</pre>`).join('')}
      </div>
    </body>
    </html>`;
}

responseTypes

Array of response_type values that the authorization server supports. The default omits all response types that result in access tokens being issued by the authorization endpoint directly as per RFC9700 - Best Current Practice for OAuth 2.0 Security You can still enable them if you need to.

default value:

[
  'code id_token',
  'code',
  'id_token',
  'none'
]

(Click to expand) Supported values list

These are values defined in OIDC Core 1.0 and OAuth 2.0 Multiple Response Type Encoding Practices

[
  'code',
  'id_token', 'id_token token',
  'code id_token', 'code token', 'code id_token token',
  'none',
]

revokeGrantPolicy

Function called in a number of different context to determine whether an underlying Grant entry should also be revoked or not.
contexts:

• RP-Initiated Logout
• Refresh Token Revocation
• Authorization Code re-use
• Device Code re-use
• Backchannel Authentication Request re-use
• Rotated Refresh Token re-use

default value:

function revokeGrantPolicy(ctx) {
  return true;
}

routes

Routing values used by the authorization server. Only provide routes starting with ”/”

default value:

{
  authorization: '/auth',
  backchannel_authentication: '/backchannel',
  code_verification: '/device',
  device_authorization: '/device/auth',
  end_session: '/session/end',
  introspection: '/token/introspection',
  jwks: '/jwks',
  pushed_authorization_request: '/request',
  registration: '/reg',
  revocation: '/token/revocation',
  token: '/token',
  userinfo: '/me'
}

scopes

Array of additional scope values that the authorization server signals to support in the discovery endpoint. Only add scopes the authorization server has a corresponding resource for. Resource Server scopes don’t belong here, see features.resourceIndicators for configuring those.

default value:

[
  'openid',
  'offline_access'
]

sectorIdentifierUriValidate

Function called to make a decision about whether sectorIdentifierUri of a client being loaded, registered, or updated should be fetched and its contents validated against the client metadata.

default value:

function sectorIdentifierUriValidate(client) {
  // @param client - the Client instance
  return true;
}

subjectTypes

Array of the Subject Identifier types that this authorization server supports. When only pairwise is supported it becomes the default subject_type client metadata value. Valid types are

• public
• pairwise

default value:

[
  'public'
]