Optional afterFunction 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.
app.use(auth({
...
afterCallback: async (req, res, session, decodedState) => {
const userProfile = await request(`${issuerBaseURL}/userinfo`);
return {
...session,
userProfile // access using `req.appSession.userProfile`
};
}
}))
``
Optional attemptAttempt 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 auth0Boolean value to enable idpLogout with an Auth0 custom domain
Optional authRequire authentication for all routes.
Optional authorizationURL 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:
app.use(
auth({
authorizationParams: {
response_type: 'code',
scope: 'openid profile email read:reports',
audience: 'https://your-api-identifier',
},
})
);
Additional custom parameters can be added as well:
app.use(auth({
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 backchannelSet 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 ConfigParams.backchannelLogout.store,
which can be any express-session compatible store, or you can
reuse SessionConfigParams.store if you are using one already.
See: https://openid.net/specs/openid-connect-backchannel-1_0.html
Optional baseURLREQUIRED. 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: "https://example.com/some/path"
[...]
})
Optional clientThe 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 clientPrivate key for use with 'private_key_jwt' clients.
Can be a PEM:
app.use(auth({
...
clientAssertionSigningKey: '-----BEGIN PRIVATE KEY-----\nMIIEo...PgCaw\n-----END PRIVATE KEY-----',
}))
Or JWK:
app.use(auth({
...
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:
app.use(auth({
...
clientAssertionSigningKey: crypto.createPrivateKey({ key: '-----BEGIN PRIVATE KEY-----\nMIIEo...PgCaw\n-----END PRIVATE KEY-----' }),
}))
Optional clientString 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 clientIDREQUIRED. The Client ID for your application. Can use env key CLIENT_ID instead.
Optional clientThe Client Secret for your application. Required when requesting access tokens. Can use env key CLIENT_SECRET instead.
Optional clockInteger value for the system clock's tolerance (leeway) in seconds for ID token verification.` Default is 60
Optional discoveryMaximum time (in milliseconds) to wait before fetching the Identity Provider's Discovery document again. Default is 600000 (10 minutes).
Optional enableTo opt-out of sending the library and node version to your authorization server
via the Auth0-Client header. Default is `true
Optional errorThrow a 401 error instead of triggering the login process for routes that require authentication.
Default is false
Optional getFunction that returns an object with URL-safe state values for res.oidc.login().
Used for passing custom state parameters to your authorization server.
app.use(auth({
...
getLoginState(req, options) {
return {
returnTo: options.returnTo || req.originalUrl,
customState: 'foo'
};
}
}))
``
Optional httpSpecify an Agent or Agents to pass to the underlying http client https://github.com/sindresorhus/got/
An object representing http, https and http2 keys for http.Agent,
https.Agent and http2wrapper.Agent instance.
See https://github.com/sindresorhus/got/blob/v11.8.6/readme.md#agent
For a proxy agent see https://www.npmjs.com/package/proxy-agent
Optional http?: false | AgentOptional http2?: unknownOptional https?: false | AgentOptional httpHttp timeout for oidc client requests in milliseconds. Default is 5000. Minimum is 500.
Optional httpOptional User-Agent header value for oidc client requests. Default is express-openid-connect/{version}.
Optional idString value for the expected ID token algorithm. Default is 'RS256'
Optional identityArray 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 idpBoolean value to log the user out from the identity provider on application logout. Default is false
Optional issuerREQUIRED. The root URL for the token issuer with no trailing slash. Can use env key ISSUER_BASE_URL instead.
Optional legacySet a fallback cookie with no SameSite attribute when response_mode is form_post. Default is true
Optional logoutAdditional custom parameters to pass to the logout endpoint.
Optional pushedPerform a Pushed Authorization Request at the issuer's pushed_authorization_request_endpoint at login.
Optional routesConfiguration for the login, logout, callback and postLogoutRedirect routes.
Optional backchannelRelative path to the application's Back-Channel Logout web hook.
Optional callback?: string | falseRelative path to the application callback to process the response from the authorization server.
Optional login?: string | falseRelative path to application login.
Optional logout?: string | falseRelative path to application logout.
Optional postEither 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 secretREQUIRED. 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.
Optional sessionObject defining application session cookie attributes.
Optional tokenAdditional request body properties to be sent to the token_endpoint during authorization code exchange or token refresh.
Optional transactionConfiguration parameters used for the transaction cookie.
Optional name?: string
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.