Tightening access with a websudo allowlist
Before you begin
Before enabling your websudo allowlist, your system must be set up to run it correctly. Read and understand the following sections on best practice and other useful info to avoid running into any problems.
Best practice
- Make sure you can’t lock yourself out by including more than one single IP address in your allowlist.
- Configure your allowlist based on VPN settings.
- For long allowlists, we recommend using CIDR notation, and/or patterns with wildcards (for IPV4 addresses only — for example,
103.12.*.*). - Keep your allowlist restricted to reduce security concerns. For example, including
*.*.*.*is equivalent to switching off the allowlist restrictions altogether. - Take a backup of your config file. You will need this if you lock yourself out.
Other useful info
- The websudo allowlist is a comma-separated list.
- Any server or service responsible for handling connections from the internet should include the client's IP address as a header in the HTTP request. This header will then be forwarded to internal servers/nodes for processing. By default, this feature uses the
X-Forwarded-Forheader as the source of the client's IP address. However, you can change the name of this header by modifying theserver.tomcat.remoteip.remote-ip-headerconfiguration property in thejira-config.propertiesfile. - If any strings in the allowlist contain an error, such as a typo, or an invalid character, that configuration portion will be omitted from the service configuration. Although unlikely, it is possible that no IP addresses would be allowed for this feature, resulting in no one being able to use websudo. In such cases, you must change the specified properties to provide correct values before enabling the allowlist.
You must utilize a reverse proxy or gateway, positioned in front of the instance to accurately identify client IPs. This is a mandatory prerequisite for the feature to work correctly. The responsibility of accurately determining the client IP rests with the external system, not the instance itself.
Configure your websudo allowlist
Your websudo allowlist is configurable as comma-separated lists of IP addresses and CIDR addresses within your Jira configuration file (jira-config.properties). Follow the steps below to configure your allowlist.
- Navigate to your Jira home directory and take a backup of the
jira-config.propertiesfile. - Open your live
jira-config.propertiesfile in your preferred text editor. If you would like to add IP addresses, add the
websudo.allowlist.ipproperty to your file, and add your comma-separated list of IP addresses.For example:
websudo.allowlist.ip=172.29.143.247,2001:0db8:85a3:0000:0000:8a2e:0370:7330If you would like to add IP address subnets, add the
websudo.allowlist.cidrproperty to your file, and add your comma-separated list of CIDR addresses.For example:
websudo.allowlist.cidr=8.8.8.1/24,0:0:0:1::/64Check for any errors to ensure your lists won’t be omitted from the service configuration.
Look for the following error text:
Exception while parsing IP/CIDR Pattern {}. Ignoring part {}- Save your configuration file.
Activate the websudo allowlist service
After you've configured your allowlist and you’re certain your address details are included in the allowlist, you can enable it. Follow the steps below.
- Open your live
jira-config.propertiesfile in your preferred text editor. - Search for
websudo.allowlist.enabled. - If the string is missing, add it to your file.
- Change the string’s value to
true. - Save and close your configuration file.
- Restart Jira for the changes to take effect.
If Jira fails to start, reinstate your backup copy of jira-config.properties and start over.
Deactivate the websudo allowlist service
If you wish to stop using the websudo allowlist service, you can do so if you’re using any of the addresses listed in the allowlist. Follow the steps below.
- Open your live
jira-config.propertiesfile in your preferred text editor. - Search for
websudo.allowlist.enabled. - Change the string’s value to
false. - Save and close the configuration file.
- Restart Jira for the changes to take effect.
An alternative method to deactivate the allowlist is to remove the entire line containing websudo.allowlist.enabled from the configuration file. It lessens the chance of the option being set back to true.