Configuration
You can customise Knock Knock’s settings using a PHP configuration file. This is optional: each setting has a default, so you only need to include the values you want to change.
To override a setting, create knock-knock.php in your Craft project’s /config directory and return an array of setting names and values. For example, the following will include the control panel in password protection:
<?php
return [
'enableCpProtection' => true,
];All other settings keep their defaults. Add any further settings you want to change to the same array. The options below explain the available settings and their defaults. You can also manage many of these settings in the control panel under Settings → Knock Knock.
Configuration Options
Whether password protection should be enabled. Useful in multi-environment scenarios.
Whether password protection for the control panel should be enabled. By default, only the front-end is protected.
The password users will need to enter to access the site. Protection fails closed when the effective value is empty, including when an environment variable is missing.
The path to be used when to challenge is shown to the user.
Provide a path to a custom template to be shown instead of the default one.
Provide a URL to be redirected to after the password is accepted. By default, Knock Knock returns each visitor to the protected page they originally requested, but you may want to enforce a specific destination instead.
How long a visitor stays logged in for before being asked for the password again. Accepts a number of seconds, or any duration value Craft supports, like 'P1D' for a day. Set to 0 for access to last until the visitor closes their browser. This is a fixed expiry from the time of login, not an idle timeout. With static caching disabled, changing the duration or effective password invalidates existing access.
With enableStaticCaching enabled, this only sets the browser cookie’s expiry. The static access token has no server-side expiry, and changing the duration does not revoke existing access. See the static caching limitations.
Whether the password prompt and protected pages should be statically cacheable, such as by Craft Cloud (opens new window). By default, Knock Knock prevents its responses from being cached, so a cached password prompt can’t be shown to visitors who have entered the password.
When enabled, visitors who enter the password get an access cookie with the same value, which your static cache must include in its cache keys. Only enable this once your cache rules include the cookie for every protected URL.
This mode relies on browser-only cookie expiry. IP rules and other access exemptions only run when requests reach Craft, and access changes require cache purging. Read the setup instructions and limitations under Static Caching before enabling it.
The name of the access cookie to set when enableStaticCaching is enabled. Cookie names may only contain letters, numbers and the characters !#$%&'*+-^_`|~.
See below on how to configure.
Whether to check and log invalid logins. This will lock IP addresses out of the system in certain circumstances, but can help against brute-force logins.
The amount of time to track invalid login attempts for an IP, for determining if Knock Knock should lock the IP out.
The number of invalid login attempts Knock Knock will allow within the specified duration before the IP gets locked.
Provide IP addresses or CIDR blocks that should bypass the password gate and be exempt from automatic lockouts. An allow rule takes precedence when the same address also matches denyIps.
Provide IP addresses or CIDR blocks that should be locked out of password-protected pages. Denied visitors cannot use an existing access cookie or submit the password, but deliberately unprotected URLs remain public. Matching allowIps rules take precedence.
Whether to use the immediate network peer’s IP address and ignore all forwarded headers. This is the strictest option, but behind a proxy it normally identifies the proxy rather than the visitor.
When this is disabled, Knock Knock still uses the direct peer unless it matches a concrete proxy IP address or CIDR in Craft’s trustedHosts setting and the forwarded header is permitted by that proxy entry and Craft’s ipHeaders setting. Craft’s default trustedHosts value of any is not treated as a trusted proxy boundary for password-gate access.
A list of specific request paths to protect. For exact paths, query strings and fragments are ignored, and paths are compared case-insensitively without leading or trailing slashes. An absolute entry must belong to the current site; its scheme and host are then removed before matching. A rule is recognised as a regular expression when its path contains ( before any unencoded ? or #. Once recognised, the entire expression is preserved, including ? and #, and must match the complete path case-insensitively. For example, /some-channel/(.*) matches /some-channel/news, but not /private/some-channel/news.
A list of specific request paths to leave unprotected. For exact paths, query strings and fragments are ignored, and paths are compared case-sensitively without leading or trailing slashes. An absolute entry must belong to the current site; its scheme and host are then removed before matching. A rule is recognised as a regular expression when its path contains ( before any unencoded ? or #. Once recognised, the entire expression is preserved, including ? and #, and must match the complete path case-insensitively. For example, /some-channel/(.*) matches /some-channel/news, but not /private/some-channel/news.
Multi-Site Configuration
A setting given at the top level of the file applies to every site and overrides the same setting in siteSettings. To use different values for each site, leave those settings out of the top level and set them under siteSettings, keyed by site handle. For example:
<?php
return [
'siteSettings' => [
'siteHandle' => [
'enabled' => true,
'password' => 'superSecretPassword',
],
'anotherSiteHandle' => [
'enabled' => true,
'password' => 'anotherSecretPassword',
],
],
];