• Public
  • Public/Protected
  • All

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



Optional afterCallback

afterCallback: (req: OpenidRequest, res: OpenidResponse, session: Session, decodedState: {}) => Promise<Session> | 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`

Type declaration

Optional attemptSilentLogin

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

Optional auth0Logout

auth0Logout: boolean

Boolean value to enable idpLogout with an Auth0 custom domain

Optional authRequired

authRequired: boolean

Require authentication for all routes.

Optional authorizationParams

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"

Optional baseURL

baseURL: string

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

Optional clientAssertionSigningAlg

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.

Optional clientAssertionSigningKey

clientAssertionSigningKey: KeyInput | KeyObject | 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-----' }),

Optional clientAuthMethod

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.

Optional clientID

clientID: string

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

Optional clientSecret

clientSecret: string

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

Optional clockTolerance

clockTolerance: number

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

Optional enableTelemetry

enableTelemetry: boolean

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

Optional errorOnRequiredAuth

errorOnRequiredAuth: boolean

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

Optional getLoginState

getLoginState: (req: OpenidRequest, options: LoginOptions) => 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'

Type declaration

Optional httpTimeout

httpTimeout: number

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

Optional httpUserAgent

httpUserAgent: string

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

Optional idTokenSigningAlg

idTokenSigningAlg: string

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

Optional identityClaimFilter

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

Optional idpLogout

idpLogout: boolean

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

Optional issuerBaseURL

issuerBaseURL: string

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

Optional legacySameSiteCookie

legacySameSiteCookie: boolean

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

Optional logoutParams

logoutParams: {}

Additional custom parameters to pass to the logout endpoint.

Type declaration

  • [key: string]: any

Optional routes

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

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

Type declaration

  • Optional callback?: string

    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.

Optional secret

secret: string | Array<string>

REQUIRED. The secret(s) used to derive an encryption key for the user identity in a session cookie and to sign the transient cookies used by the login callback. Use a single string key or array of keys for an encrypted session cookie. Can use env key SECRET instead.

Optional session

Object defining application session cookie attributes.

Optional tokenEndpointParams

tokenEndpointParams: TokenParameters

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

Optional transactionCookie

transactionCookie: Pick<CookieConfigParams, "sameSite">

Configuration parameters used for the transaction cookie.