- Overview
- Root-level
- Auth module
- Code Freeze module
- Password module
- Rate limit module
- Session module
- absolute_timeout
- absolute_timeout_per_cap
- absolute_timeout_remembered_user
- absolute_timeout_remembered_user_per_cap
- disable_rotation_for_ajax_like_requests_per_cap
- idle_timeout
- idle_timeout_per_cap
- non_sudo_mode_recheck_frequency
- protected_capabilities
- protected_pages
- remember_cookie_name
- rotation_timeout
- rotation_timeout_per_cap
- sudo_mode_timeout
- sudo_mode_timeout_per_cap
- table_name
- Vaults and Pillars module
This document contains a reference to all available configuration options in Fortress; what they mean; and what their default values are.
A JSON schema is available here to provide syntax highlighting, auto-completion, and validation in your favorite IDE:
Below is the JSON representation of the Fortress baseline configuration for a (default) WordPress site:
(The configuration for WordPress multisite is slightly different)
{
"challenges_table_name": null,
"cli_namespace": "fort",
"db_table_namespace": "snicco_fortress",
"modules": [
"password",
"session",
"auth",
"rate_limit",
"vaults_and_pillars",
"code_freeze"
],
"privileged_user_roles": [
"administrator",
"editor"
],
"theme_css_file": null,
"url_namespace": "/snicco-fortress",
"auth": {
"magic_link_allow_requesting_via_http": true,
"magic_link_show_on_wp_login_form": true,
"max_totp_attempts_before_lockout": 5,
"require_2fa_for_roles": [
"administrator",
"editor"
],
"require_2fa_for_roles_before_login": [],
"skip_2fa_setup_duration_seconds": 1800,
"totp_recovery_codes_locked_to_user_id": false,
"totp_secrets_table_name": null,
"totp_sha_algo": "sha1"
},
"code_freeze": {
"enabled": "auto"
},
"password": {
"allow_legacy_hashes": true,
"allow_legacy_hashes_for_non_passwords": true,
"auto_upgrade_hashes": true,
"default_hash_strength": "moderate",
"disable_application_passwords": false,
"disable_web_password_reset_for_roles": [
"administrator",
"editor"
],
"include_pluggable_functions": true,
"password_policy_excluded_roles": [],
"store_hashes_encrypted": false
},
"rate_limit": {
"cache_group": null,
"device_id_burst": 5,
"device_id_cookie_prefix": "device_id",
"device_id_refill_one_token_seconds": 20,
"global_burst": 100,
"global_refill_one_token_seconds": 30,
"ip_burst": 20,
"ip_refill_one_token_seconds": 1800,
"log_to_syslog": true,
"storage": "auto",
"syslog_daemon": "snicco_fortress",
"syslog_facility": 32,
"syslog_flags": 1,
"use_hashed_ips": false,
"username_burst": 5,
"username_refill_one_token_seconds": 900
},
"session": {
"absolute_timeout": 43200,
"absolute_timeout_per_cap": [],
"absolute_timeout_remembered_user": 86400,
"absolute_timeout_remembered_user_per_cap": [],
"disable_rotation_for_ajax_like_requests_per_cap": [],
"idle_timeout": 1800,
"idle_timeout_per_cap": [],
"non_sudo_mode_recheck_frequency": 10,
"protected_capabilities": [
"administrator",
"activate_plugins",
"delete_plugins",
"delete_themes",
"delete_users",
"edit_dashboard",
"edit_files",
"edit_plugins",
"edit_theme_options",
"edit_themes",
"edit_users",
"edit_user",
"export",
"import",
"install_plugins",
"install_themes",
"manage_options",
"promote_users",
"remove_users",
"list_users",
"create_users",
"switch_themes",
"unfiltered_upload",
"update_core",
"update_plugins",
"update_themes",
"manage_categories",
"delete_pages",
"delete_private_pages",
"delete_published_pages",
"delete_others_pages",
"delete_posts",
"delete_private_posts",
"delete_published_posts",
"delete_others_posts",
"view_site_health_checks",
"install_languages",
"edit_comment"
],
"protected_pages": [
"/wp-admin/update-core.php",
"/wp-admin/themes.php",
"/wp-admin/theme-install.php",
"/wp-admin/plugins.php",
"/wp-admin/plugin-install.php",
"/wp-admin/users.php",
"/wp-admin/user-new.php",
"/wp-admin/user-edit.php",
"/wp-admin/profile.php",
"/wp-admin/update.php",
"/wp-admin/options-*",
"/wp-admin/options.php",
"/wp-admin/authorize-application.php",
"/wp-admin/tools.php",
"/wp-admin/import.php",
"/wp-admin/export.php",
"/wp-admin/site-health.php",
"/wp-admin/export-personal-data.php",
"/wp-admin/erase-personal-data.php",
"/wp-admin/theme-editor.php",
"/wp-admin/plugin-editor.php",
"/snicco-fortress/auth/totp/manage*"
],
"remember_cookie_name": "snicco_fortress_remember_me",
"rotation_timeout": 1200,
"rotation_timeout_per_cap": [],
"sudo_mode_timeout": 600,
"sudo_mode_timeout_per_cap": [],
"table_name": null
},
"vaults_and_pillars": {
"option_pillars": [],
"option_vaults": [],
"strict_option_vaults_and_pillars": false
}
}The top-level namespace contains configuration options that apply to Fortress as a whole.
- Type:
null|non-empty-string - Default:
null
Controls the name of the database table where Fortress stores cryptographic challenges.
🚨 This option is deprecated and will be removed in the next major release of Fortress.
- Type:
non-empty-string - Default:
fort
Controls WP-CLI namespace that will
be used to register Fortress's CLI with the wp command.
- Type:
non-empty-string - Default:
snicco_fortress
Controls the prefix that will be used for all database tables created by Fortress.
This value must not include the WordPress table prefix.
- Type:
non-empty-string[] - Default:
["password","session","auth","rate_limit", "vaults_and_pillars", "code_freeze"] - Allowed values:
["password","session","auth","rate_limit", "vaults_and_pillars", "code_freeze"]
Controls which Fortress modules are activated.
Unless you know what you're doing, it's best to leave this option as-is.
- Type:
non-empty-string[] - Default:
["administrator","editor"] - Allowed values: Any valid WordPress user role.
Controls which user roles are considered "highly privileged" by Fortress to apply more strict security controls. Several other options inherit from it by default.
- Type:
non-empty-string - Default:
null
This option can be used to provide a relative path to a custom CSS file that will be loaded on all Fortress pages.
The CSS file will be loaded after Fortress's default templates, allowing you to override any styles, especially the CSS variables that Fortress uses.
The default CSS of Fortress is below:
:root {
--color-primary-light: 99 102 241;
--color-primary: 79 70 229;
--color-primary-dark: 67 56 202;
}To give Fortress's UI a "neon-green" theme:
:root {
--color-primary-light: 163 230 53;
--color-primary: 101 163 13;
--color-primary-dark: 77 124 15;
}- Type:
non-empty-string - Default:
/snicco-fortress
Controls the shared URL prefix of all Fortress routes.
- Configuration namespace:
"auth"
- Type:
bool - Default:
true
Controls whether Fortress's magic links can be requested via the web UI.
If set to false, magic links can only be requested via
the Fortress CLI.
- Type:
bool - Default:
true
Controls whether Fortress shows a link to the custom magic link login page on the default wp-login.php page.
If set to false, the link will not be shown, however,
the magic link login page will still be accessible.
This option is ignored if magic_link_allow_requesting_via_http is set
to false.
- Type:
positive-integer - Default:
5
Controls how many failed 2FA attempts Fortress will allow before locking an account.
- Type:
non-empty-string[] - Default:
privileged_user_roles - Allowed values: Any valid WordPress user role.
Controls which user roles are required to set up 2FA immediately after logging in.
- Type:
non-empty-string[] - Default:
[](empty array) - Allowed values: Any valid WordPress user role.
Controls which user roles must have 2FA enabled even before they can log in.
- Type:
positive-integer - Default:
1800(30 minutes)
Controls the duration that 2FA setup can be skipped for
any user that has one of the roles defined in
require_2fa_for_roles.
The duration has to be provided in seconds.
- Type:
bool - Default:
false
Controls whether a user's 2FA recovery codes are cryptographically locked with an HMAC to their user ID.
🚨 This option exists for backwards compatability reason.
It has no effect if you started
using Fortress after
version 1.0.0-beta.36.
- Type:
null|non-empty-string - Default:
null
Controls the name of the database table where Fortress stores users' TOTP secrets.
🚨 This option is deprecated and will be removed in the next major release of Fortress.
- Type:
"sha1" | "sha256" | "sha512" - Default:
"sha1" - Allowed values:
"sha1" | "sha256" | "sha512"
Controls the hash algorithm that Fortress uses to generate six-digit one-time passwords.
Unless you know what you're doing, don't change this.
The default "sha1" value is what's used by most password manager apps
(1Password, Google Authenticator, etc.).
- Configuration namespace:
"code_freeze"
- Type:
"auto" | "yes" | "no" - Default:
"auto"
Controls whether the Code Freeze is enabled.
The value of "auto" means that Fortress will automatically enable Code Freeze
if WordPress runs in production, and disable it in development/staging/local
environments.
- Configuration namespace:
"password"
- Type:
bool - Default:
true
Controls whether Fortress allows users with non-upgraded legacy hashes to log in.
This option can be safely set to false
after all users have logged in at least once,
or if
you upgraded all hashes via Fortress CLI.
- Type:
bool - Default:
true
Controls where Fortress allows legacy hashes for non-passwords.
A non-password is anything that is passed into wp_verify_password
that is not a password.
This option should only be used if you're building a new site with Fortress since there is no way to automatically upgrade non-password hashes.
- Type:
bool - Default:
true
Controls whether a user's password will automatically be upgraded to Fortress's secure hashing scheme after logging in.
The user's password stays the same—only the hash is upgraded.
- Type:
"interactive" | "moderate" | "sensitive" - Default:
"moderate"
Controls how long the libsodium PHP extension will take to compute the hash of a password.
If you have a powerful server, you might want to set this to "sensitive".
- Type:
bool - Default:
false
Controls whether Fortress will completely disable application passwords.
If your site does not use application passwords, it's best to disable this option because site owners can easily be tricked into created malicious application passwords.
- Type:
non-empty-string[] - Default:
["administrator","editor"] - Allowed values: Any valid WordPress user role.
Controls which user roles will not be able to reset their password via the web UI / frontend.
Refer to the password reset documentation for more information.
- Type:
non-empty-string[] - Default:
[](empty array) - Allowed values: Any valid WordPress user role.
Controls which user roles are excluded from the Fortress password policy.
- Type:
bool - Default:
true
Controls whether Fortress takes over the WordPress password hashing functions.
If you set this option to false, you can still use other functionality of the password module such as the password policies, or password reset restrictions.
- Type:
bool - Default:
false
Controls whether the secure password hashes will be stored encrypted on top of being hashed to provide additional security benefits.
This was previously enabled by default, but is now
disabled because it requires more than 255 characters
to store the final string, which required modification to the
wp_users.user_pass column.
That's not necessarily a problem, but some plugins attempt to reset the user_pass column to 255 characters and thus causing data truncation.
If you use Fortress on a tightly controlled stack, you can enable this option.
You can at any point switch between encrypted and non-encrypted.
Refer to the password hashing documentation for more information.
- Configuration namespace:
"rate_limit"
- Type:
null|non-empty-string - Default:
null
Controls the object cache group that Fortress uses to store rate limit data.
🚨 This option is deprecated and will be removed in the next major release of Fortress.
- Type:
positive-integer - Default:
5
Controls the maximum number of requests that can be made from a single device ID before login throttling is applied.
- Type:
non-empty-string - Default:
"device_id"
Controls the prefix that Fortress uses to set the device ID cookie.
- Type:
positive-integer - Default:
20
Controls the interval in seconds that a user rate-limited by his device ID has to wait before he can make one more login request.
With a value of 20, in the long run, a user can make a request every 20 seconds.
Refer to the implementation details
to learn more about the relation between device_id_burst,
device_id_refill_one_token_seconds,
- Type:
positive-integer - Default:
100
Controls the maximum number of login requests that can be made globally before login throttling is activated for users without device IDs.
- Type:
positive-integer - Default:
30
Controls the interval in seconds that has to pass before another login request can be made for users without device IDs.
With a value of 30, in the long run, there can only be one login request every 30 seconds.
This does not apply to users with device IDs.
- Type:
positive-integer - Default:
20
Controls the maximum number of requests that can be made from a single IP address before login throttling is applied.
- Type:
positive-integer - Default:
1800(30 minutes)
Controls the interval in seconds that a user rate-limited by his IP address has to wait before he can make one more login request.
With a value of 1800, in the long run, a user without device id can make a login request every 30 minutes.
- Type:
bool - Default:
true
Controls whether Fortress will also log request to don't respect active throttling to the syslog.
It can be used to integrate with Fail2Ban.
- Type:
"auto" | "database" - Default:
"auto"
If set to "auth", Fortress will store rate limit data
in the object cache if it's persistent, and in the database
if it's not.
If set to "database", Fortress will always store rate limit data
in the database.
- Type:
non-empty-string - Default:
"snicco_fortress"
Controls the prefix that will be prepended to all messages that Fortress logs to the syslog.
- Type:
positive-integer - Default:
32(LOG_AUTH)
A bitmask, valid options can be found in the openlog manual.
- Type:
positiv-interger - Default:
1(LOG_PID)
A bitmask, valid options can be found in the openlog manual.
- Type:
bool - Default:
false
Controls whether Fortress will hash the IP address before storing it in the database.
🚨 This option is deprecated and will be removed in the next major release of Fortress.
- Type:
positive-integer - Default:
5
Controls the maximum number of requests that can be made from a single username before login throttling is applied.
- Type:
positive-integer - Default:
900(15 minutes)
Controls the interval in seconds that has to pass until another login attempt can be made for a given username.
With a value of 900, in the long run, there
can only be one login request for a given username every 15 minutes.
- JSON namespace:
"session"
- Type:
positive-interger - Default:
43200(12 hours)
Controls the maximum duration in seconds of a user's session. User activity cannot extend this timeout.
This value only applies to users that dit not check the "remember_me" option during login!
For users that checked the "remember_me" option during login, the value
of absolute_timeout_remembered_user applies.
- Type:
array<string,positive-interger - Default:
[] - Allowed values: Any valid WordPress user capability or role.
The absolute_timeout_per_cap option can be used if more fine-grained control of the absolute timeout is needed.
The following configuration sets the absolute timeout to six (60*60*6 = 18,000) hours for users with
the mange_options capability, and to 48 hours (60*60*48 = 172,800) for everybody else.
{
"session": {
"absolute_timeout": 172800,
"absolute_timeout_per_cap": {
"manage_options": 18000
}
}
}This option only applies to users that did not check the "remember_me" option during login.
For users that checked the "remember_me" option during login, the value
of absolute_timeout_remembered_user_per_cap applies.
- Type:
positive-interger - Default:
86400(24 hours)
Controls the maximum duration in seconds of a user's session that checked the "remember_me" option during login.
- Type:
array<string,positive-interger - Default:
[] - Allowed values: Any valid WordPress user capability or role.
This option is the same
as absolute_timeout_per_cap but applies to users that checked the "remember_me"
option during login.
- Type:
non-empty-string[] - Default:
[] - Allowed values: Any valid WordPress user capability or role.
This option can be used to disable the rotation of session tokens for ajax like requests for users with any of the specified capabilities.
The following configuration would prevent rotating session for subscribers and authors for ajax like requests.
{
"session": {
"disable_rotation_for_ajax_like_requests_per_cap": [
"subscriber",
"author"
]
}
}- Type:
positive-interger - Default:
1800(30 minutes)
Controls the timeout in seconds after which a user without any activity is logged out.
- Type:
array<string,positive-interger - Default:
[] - Allowed values: Any valid WordPress user capability or role.
This option can be used if more fine-grained control of the idle timeout is needed for different user roles.
The following configuration sets the idle timeout to 10 (60*6=600) minutes for users with the mange_options
capability, and to six hours (60*60*6 = 18,000) for everybody else.
{
"session": {
"idle_timeout": 18000,
"idle_timeout_per_cap": {
"manage_options": 600
}
}
}- Type:
positive-integer - Default:
10
Controls how often Fortress will make an ajax-request to the backend to check if a user's session has re-entered the sudo mode.
This timeout is only relevant if the user is either about to cross the threshold of not being in sudo mode anymore, or has crossed the sudo timeout already.
A value of 10 means that Fortress would check every ten seconds if the user has confirmed his credentials
AFTER his session had already crossed the sudo timeout.
No checks are made if the user is still in sudo mode.
- Type:
non-empty-string[] - Default:
[ "administrator", "activate_plugins", "delete_plugins", "delete_themes", "delete_users", "edit_dashboard", "edit_files", "edit_plugins", "edit_theme_options", "edit_themes", "edit_users", "edit_user", "export", "import", "install_plugins", "install_themes", "manage_options", "promote_users", "remove_users", "list_users", "create_users", "switch_themes", "unfiltered_upload", "update_core", "update_plugins", "update_themes", "manage_categories", "delete_pages", "delete_private_pages", "delete_published_pages", "delete_others_pages", "delete_posts", "delete_private_posts", "delete_published_posts", "delete_others_posts", "view_site_health_checks", "install_languages", "edit_comment" ]
Represents a list of capabilities that will be removed from a user's session if they're not in sudo mode anymore.
The following configuration would only protect the manage_options capability.
{
"session": {
"protected_capabilities": [
"manage_options"
]
}
}For multisite, the following capabilities are also protected:
[
"create_sites",
"delete_sites",
"manage_network",
"manage_sites",
"manage_network_users",
"manage_network_plugins",
"manage_network_themes",
"manage_network_options",
"upgrade_network",
"setup_network"
]-
Type:
non-empty-string[] -
Default:
[ "/wp-admin/update-core.php", "/wp-admin/themes.php", "/wp-admin/theme-install.php", "/wp-admin/plugins.php", "/wp-admin/plugin-install.php", "/wp-admin/users.php", "/wp-admin/user-new.php", "/wp-admin/user-edit.php", "/wp-admin/profile.php", "/wp-admin/update.php", "/wp-admin/options-*", "/wp-admin/options.php", "/wp-admin/authorize-application.php", "/wp-admin/tools.php", "/wp-admin/import.php", "/wp-admin/export.php", "/wp-admin/site-health.php", "/wp-admin/export-personal-data.php", "/wp-admin/erase-personal-data.php", "/wp-admin/theme-editor.php", "/wp-admin/plugin-editor.php", "/snicco-fortress/auth/totp/manage*" ]
Additionally, for multisite:
[ "/wp-admin/network.php", "/wp-admin/ms-admin.php", "/wp-admin/ms-delete-site.php", "/wp-admin/ms-edit.php", "/wp-admin/ms-options.php", "/wp-admin/ms-sites.php", "/wp-admin/ms-themes.php", "/wp-admin/ms-upgrade-network.php", "/wp-admin/network/*" ]
The
/wp-adminprefix is determined dynamically.
If you're using a Bedrock site, it would be/wp/wp-admin.
Control's URL paths that a user can only access if his session is still in sudo mode.
You can use a * character as a wildcard.
The following configuration would prevent users whose sessions are not in sudo mode anymore from accessing the entire wp-admin area.
{
"session": {
"protected_pages": [
"/wp-admin/*"
]
}
}Refer to the sudo mode documentation for the difference between protected_pages and protected_capabilities.
- Type:
non-empty-string - Default:
"snicco_fortress_remember_me"
Controls the cookie name that Fortress uses to determine if a user wanted to be remembered.
- Type:
positive-interger - Default:
1200(20 minutes)
The rotation_timeout is the interval after which the user's session token
is rotated.
- Type:
array<string,positive-interger - Default:
[] - Allowed values: Any valid WordPress user capability or role.
This option can be used if more fine-grained control of the rotation timeout is needed per user role or capability.
The following configuration sets the rotation timeout to 10 (60*6=600) minutes for users with the mange_options
capability, and to six hours (60*60*6 = 18,000) for everybody else.
{
"session": {
"rotation_timeout": 18000,
"rotation_timeout_per_cap": {
"manage_options": 600
}
}
}- Type:
positive-integer - Default:
600(10 minutes)
Controls the interval in seconds during which Fortress will consider a session to be in sudo mode after logging in.
- Type:
array<string,positive-interger - Default:
[] - Allowed values: Any valid WordPress user capability or role.
This option can be used if more fine-grained control of the sudo mode timeout is needed per user role or capability.
The following configuration sets the sudo mode timeout to 10 (60*6=600) minutes for users with the mange_options
capability, and to six hours (60*60*6 = 18,000) for everybody else.
{
"session": {
"sudo_mode_timeout": 18000,
"sudo_mode_timeout_per_cap": {
"manage_options": 600
}
}
}- Type:
null|non-empty-string - Default:
null
Controls the name of the database table where Fortress stores user sessions.
🚨 This option is deprecated and will be removed in the next major release of Fortress.
- Configuration namespace:
"vaults_and_pillars"
- Type:
array<non-empty-string,array> - Default:
{}
Defines all Pillars for WordPress Options.
The exact required structure is documented here and in the Fortress schema.json:
{
"option_pillars": {
"type": "object",
"default": {},
"patternProperties": {
"^.*$": {
"type": "object",
"properties": {
"expand_key": {
"type": "boolean",
"default": true
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "array"
},
{
"type": "object"
}
]
},
"env_var": {
"type": "string"
}
},
"additionalProperties": false,
"oneOf": [
{
"required": [
"value"
]
},
{
"required": [
"env_var"
]
}
]
}
}
}
}- Type:
array<non-empty-string,array> - Default:
{}
Defines all Vaults for WordPress Options.
The exact required structure is documented here and in the Fortress schema.json:
{
"option_vaults": {
"type": "object",
"default": {},
"patternProperties": {
"^.*$": {
"type": "object",
"properties": {
"expand_key": {
"type": "boolean",
"default": true
}
},
"additionalProperties": false
}
}
}
}- Type:
boolean - Default:
false
Controls whether the Vaults & Pillars Strict Mode is enabled for WordPress options.