Other Options

acceptQueryParamAccessTokens

Query Parameter Access Tokens

Controls whether access tokens may be transmitted via URI query parameters. Several OAuth 2.0 and OpenID Connect profiles require that access tokens be transmitted exclusively via the Authorization header. When set to false, the authorization server shall reject requests attempting to transmit access tokens via query parameters.

default value:

false

acrValues

Authentication Context Class References

An array of strings representing the Authentication Context Class References that this authorization server supports.

default value:

[]

allowOmittingSingleRegisteredRedirectUri

Redirect URI Parameter Omission for Single Registered URI

Specifies whether clients may omit the redirect_uri parameter in authorization requests when only a single redirect URI is registered in their client metadata. When enabled, the authorization server shall automatically use the sole registered redirect URI for clients that have exactly one URI configured.

When disabled, all authorization requests MUST explicitly include the redirect_uri parameter regardless of the number of registered redirect URIs.

default value:

true

assertJwtClientAuthClaimsAndHeader

JWT Client Authentication Assertion Validation

Specifies a helper function that shall be invoked to perform additional validation of JWT Client Authentication assertion Claims Set and Header beyond the requirements mandated by the specification. This function enables enforcement of deployment-specific security policies and extended validation logic for private_key_jwt and client_secret_jwt client authentication methods according to authorization server requirements.

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
  if (ctx.oidc.isFapi('2.0') && claims.aud !== ctx.oidc.issuer) {
    throw new errors.InvalidClientAuth(
      'audience (aud) must equal the issuer identifier url',
    );
  }
}

clockTolerance

Clock Skew Tolerance

Specifies the maximum acceptable clock skew tolerance (in seconds) for validating time-sensitive operations, including JWT validation for Request Objects and other timestamp-based security mechanisms.

recommendation: This value should be kept as small as possible while accommodating expected clock drift between the authorization server and client systems.

default value:

conformIdTokenClaims

ID Token Claims Conformance

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

Extending the Discovery Document

Pass additional properties to this object to extend the discovery document.

Note: Standard discovery properties derived from the provider’s configuration cannot be overridden through this object.

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
}

enableHttpPostMethods

HTTP POST Method Support

Specifies whether HTTP POST method support shall be enabled at the Authorization Endpoint and the Logout Endpoint (if enabled). When enabled, the authorization server shall accept POST requests at these endpoints in addition to the standard GET requests. This configuration may only be used when the cookies.long.sameSite configuration value is none.

default value:

false

extraParams

Additional Authorization Request Parameters

Specifies additional parameters that shall be recognized by the authorization, device authorization, backchannel authentication, and pushed authorization request endpoints. These extended parameters become available in ctx.oidc.params and are passed to interaction session details for processing.

This configuration accepts either an iterable object (array or Set of strings) for simple parameter registration, or a plain object with string properties representing parameter names and values being validation functions (synchronous or asynchronous) for the corresponding parameter values.

Parameter validators are executed regardless of the parameter’s presence or value, enabling validation of parameter presence as well as assignment of default values. When the value is null or undefined, the parameter is registered without validation constraints.

Note: These validators execute during the final phase of the request validation process. Modifications to other parameters (such as assigning default values) will not trigger re-validation of the entire request.

default value:

[]

Example: (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')
    }
  }
}

fetch

Fetching External Resources

Specifies a function that shall be invoked whenever the authorization server needs to make calls to external HTTPS resources. The interface and expected return value shall conform to the Fetch API specification fetch() standard.

Before each invocation the authorization server sets the following fetch options:

signal to AbortSignal.timeout(2500)
headers to a new Headers instance with the user-agent header set to an empty string in order to remove the default one
dispatcher to a custom undici.Agent that rejects connections to private, loopback, and other non-globally-routable IP addresses, preventing Server-Side Request Forgery (SSRF)

default value:

(url, options) => globalThis.fetch(url, options)

fetchResponseBodyLimits

Fetch Response Body Size Limits

Specifies per-purpose maximum response body size limits (in bytes) for external HTTPS resource fetches. When a limit is defined for a given purpose, the authorization server will bail out early on Content-Length header values exceeding the limit and will also abort reading the response body when the accumulated size exceeds the limit. Purposes with a limit of Infinity will not enforce any size restriction.

default value:

{
  'client_id metadata document': 5120,
  jwks_uri: Infinity,
  sector_identifier_uri: Infinity
}

loadExistingGrant

Loading Existing Grants

Helper function invoked to load existing authorization grants that may be used to resolve an Authorization Request without requiring additional end-user interaction. The default implementation attempts to load grants based on the interaction result’s consent.grantId property, falling back to the existing grantId for the requesting 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

Pairwise Subject Identifier Generation

Specifies a helper function that shall be invoked to generate pairwise subject identifier values for ID Tokens and UserInfo responses, as specified in OpenID Connect Core 1.0. This function enables privacy-preserving subject identifier generation that provides unique identifiers per client while maintaining consistent identification for the same end-user across requests to the same client.

recommendation: Implementations should employ memoization or caching mechanisms when this function may be invoked multiple times with identical arguments within a single request.

default value:

async function pairwiseIdentifier(ctx, accountId, client) {
  throw new Error('pairwiseIdentifier not implemented');
}

renderError

Error Response Rendering

Specifies a function that shall be invoked to present error responses to the User-Agent during authorization server operations. This function enables customization of error presentation according to deployment-specific user interface requirements.

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

Supported response_type Values

Specifies the response_type values supported by this authorization server. In accordance with RFC 9700 (OAuth 2.0 Security Best Current Practice), the default configuration excludes response types that result in access tokens being issued directly by the authorization endpoint.

default value:

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

Example: (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

Grant Revocation Policy

Specifies a helper function that shall be invoked to determine whether an underlying Grant entry shall be revoked in addition to the specific token or code being processed. This function enables enforcement of grant revocation policies according to authorization server security requirements. The function is invoked in the following contexts:

RP-Initiated Logout
Opaque Access Token Revocation
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) {
  if (ctx.oidc.route === 'revocation' && ctx.oidc.entities.AccessToken) {
    return false;
  }
  return true;
}

routes

Endpoint URL Paths

Defines the URL path mappings for authorization server endpoints. All route values are relative and shall begin with a forward slash (”/”) character.

default value:

{
  authorization: '/auth',
  backchannel_authentication: '/backchannel',
  challenge: '/challenge',
  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

Supported OAuth 2.0 Scope Values

Specifies additional OAuth 2.0 scope values that this authorization server shall support and advertise in its discovery document. Resource Server-specific scopes shall be configured via the features.resourceIndicators mechanism.

default value:

[
  'openid',
  'offline_access'
]

sectorIdentifierUriValidate

Sector Identifier URI Validation

Specifies a function that shall be invoked to determine whether the 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

Subject Identifier Types

Specifies the array of Subject Identifier types that this authorization server shall support for end-user identification purposes. When only pairwise is supported, it shall become the default subject_type client metadata value. Supported identifier types shall include:

public - provides the same subject identifier value to all clients
pairwise - provides a unique subject identifier value per client to enhance privacy

default value:

[
  'public'
]