Configuration parameters passed to the auth() middleware.

issuerBaseURL, baseURL, clientID and secret are required but can be configured with environmental variables. clientSecret is not required but can also be configured this way.

# Required

# Not required


  • ConfigParams


afterCallback?: ((req, res, session, decodedState) => Session | Promise<Session>)

Type declaration

    • (req, res, session, decodedState): Session | Promise<Session>
    • Function for custom callback handling after receiving and validating the ID Token and before redirecting. This can be used for handling token storage, making userinfo calls, claim validation, etc.

      afterCallback: async (req, res, session, decodedState) => {
      const userProfile = await request(`${issuerBaseURL}/userinfo`);
      return {
      userProfile // access using `req.appSession.userProfile`


      Returns Session | Promise<Session>

attemptSilentLogin?: boolean

Attempt silent login (prompt: 'none') on the first unauthenticated route the user visits. For protected routes this can be useful if your Identity Provider does not default to prompt: 'none' and you'd like to attempt this before requiring the user to interact with a login prompt. For unprotected routes this can be useful if you want to check the user's logged in state on their IDP, to show them a login/logout button for example. Default is false

auth0Logout?: boolean

Boolean value to enable idpLogout with an Auth0 custom domain

authRequired?: boolean

Require authentication for all routes.

authorizationParams?: AuthorizationParameters

URL parameters used when redirecting users to the authorization server to log in.

If this property is not provided by your application, its default values will be:

response_type: 'id_token',
response_mode: 'form_post',
scope: 'openid profile email'

New values can be passed in to change what is returned from the authorization server depending on your specific scenario.

For example, to receive an access token for an API, you could initialize like the sample below. Note that response_mode can be omitted because the OAuth2 default mode of query is fine:

authorizationParams: {
response_type: 'code',
scope: 'openid profile email read:reports',
audience: 'https://your-api-identifier',

Additional custom parameters can be added as well:

authorizationParams: {
// Note: you need to provide required parameters if this object is set.
response_type: "id_token",
response_mode: "form_post",
scope: "openid profile email"
// Additional parameters
acr_value: "tenant:test-tenant",
custom_param: "custom-value"
backchannelLogout?: boolean | BackchannelLogoutOptions

Set to true to enable Back-Channel Logout in your application. This will set up a web hook on your app at routes.backchannelLogout On receipt of a Logout Token the webhook will store the token, then on any subsequent requests, will check the store for a Logout Token that corresponds to the current session. If it finds one, it will log the user out.

In order for this to work you need to specify a, which can be any express-session compatible store, or you can reuse if you are using one already.


baseURL?: string

REQUIRED. The root URL for the application router, eg https://localhost Can use env key BASE_URL instead.

Note: In the event that the URL has a path at the end, the auth middleware will need to be bound relative to that path. I.e

app.use('/some/path', auth({
baseURL: ""
clientAssertionSigningAlg?: "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES256K" | "ES384" | "ES512" | "EdDSA"

The algorithm to sign the client assertion JWT. Uses one of token_endpoint_auth_signing_alg_values_supported if not specified. If the Authorization Server discovery document does not list token_endpoint_auth_signing_alg_values_supported this property will be required.

clientAssertionSigningKey?: KeyObject | KeyInput | JSONWebKey

Private key for use with 'private_key_jwt' clients.

Can be a PEM:

clientAssertionSigningKey: '-----BEGIN PRIVATE KEY-----\nMIIEo...PgCaw\n-----END PRIVATE KEY-----',


clientAssertionSigningKey: {
kty: 'RSA',
n: 'u2fhZ...XIqhQ',
e: 'AQAB',
d: 'Cmvt9...g__Jw',
p: 'y5iuh...dIMwM',
q: '66Rex...IZcdc',
dp: 'GVGVc...La4a0',
dq: 'SyER8...Dnaes',
qi: 'JTtu5...P2HMw'

Or KeyObject:

clientAssertionSigningKey: crypto.createPrivateKey({ key: '-----BEGIN PRIVATE KEY-----\nMIIEo...PgCaw\n-----END PRIVATE KEY-----' }),
clientAuthMethod?: string

String value for the client's authentication method. Default is none when using response_type='id_token', private_key_jwt when using a clientAssertionSigningKey, otherwise client_secret_basic.

clientID?: string

REQUIRED. The Client ID for your application. Can use env key CLIENT_ID instead.

clientSecret?: string

The Client Secret for your application. Required when requesting access tokens. Can use env key CLIENT_SECRET instead.

clockTolerance?: number

Integer value for the system clock's tolerance (leeway) in seconds for ID token verification.` Default is 60

discoveryCacheMaxAge?: number

Maximum time (in milliseconds) to wait before fetching the Identity Provider's Discovery document again. Default is 600000 (10 minutes).

enableTelemetry?: boolean

To opt-out of sending the library and node version to your authorization server via the Auth0-Client header. Default is `true

errorOnRequiredAuth?: boolean

Throw a 401 error instead of triggering the login process for routes that require authentication. Default is false

getLoginState?: ((req, options) => object)

Type declaration

    • (req, options): object
    • Function that returns an object with URL-safe state values for res.oidc.login(). Used for passing custom state parameters to your authorization server.

      getLoginState(req, options) {
      return {
      returnTo: options.returnTo || req.originalUrl,
      customState: 'foo'


      Returns object

httpAgent?: {
    http?: false | Agent;
    http2?: unknown;
    https?: false | Agent;

Specify an Agent or Agents to pass to the underlying http client

An object representing http, https and http2 keys for http.Agent, https.Agent and http2wrapper.Agent instance.


For a proxy agent see

Type declaration

  • Optional http?: false | Agent
  • Optional http2?: unknown
  • Optional https?: false | Agent
httpTimeout?: number

Http timeout for oidc client requests in milliseconds. Default is 5000. Minimum is 500.

httpUserAgent?: string

Optional User-Agent header value for oidc client requests. Default is express-openid-connect/{version}.

idTokenSigningAlg?: string

String value for the expected ID token algorithm. Default is 'RS256'

identityClaimFilter?: string[]

Array value of claims to remove from the ID token before storing the cookie session. Default is ['aud', 'iss', 'iat', 'exp', 'nbf', 'nonce', 'azp', 'auth_time', 's_hash', 'at_hash', 'c_hash' ]

idpLogout?: boolean

Boolean value to log the user out from the identity provider on application logout. Default is false

issuerBaseURL?: string

REQUIRED. The root URL for the token issuer with no trailing slash. Can use env key ISSUER_BASE_URL instead.

legacySameSiteCookie?: boolean

Set a fallback cookie with no SameSite attribute when response_mode is form_post. Default is true

logoutParams?: {
    [key: string]: any;

Additional custom parameters to pass to the logout endpoint.

Type declaration

  • [key: string]: any
pushedAuthorizationRequests?: boolean

Perform a Pushed Authorization Request at the issuer's pushed_authorization_request_endpoint at login.

routes?: {
    backchannelLogout?: string;
    callback?: string | false;
    login?: string | false;
    logout?: string | false;
    postLogoutRedirect?: string;

Configuration for the login, logout, callback and postLogoutRedirect routes.

Type declaration

  • Optional backchannelLogout?: string

    Relative path to the application's Back-Channel Logout web hook.

  • Optional callback?: string | false

    Relative path to the application callback to process the response from the authorization server.

  • Optional login?: string | false

    Relative path to application login.

  • Optional logout?: string | false

    Relative path to application logout.

  • Optional postLogoutRedirect?: string

    Either a relative path to the application or a valid URI to an external domain. This value must be registered on the authorization server. The user will be redirected to this after a logout has been performed.

secret?: string | string[]

REQUIRED. The secret(s) used to derive an encryption key for the user identity in a stateless session cookie, to sign the transient cookies used by the login callback and to sign the custom session store cookies if {@Link signSessionStoreCookie} is true. Use a single string key or array of keys. If an array of secrets is provided, only the first element will be used to sign or encrypt the values, while all the elements will be considered when decrypting or verifying the values.

Can use env key SECRET instead.

Object defining application session cookie attributes.

tokenEndpointParams?: TokenParameters

Additional request body properties to be sent to the token_endpoint during authorization code exchange or token refresh.

transactionCookie?: Pick<CookieConfigParams, "sameSite"> & {
    name?: string;

Configuration parameters used for the transaction cookie.

Type declaration

  • Optional name?: string