Tightening access with a websudo allowlist

Configuring secure administrator sessions

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

To add an extra layer of security to websudo operations, you can configure and enable your own IP address/subnet allowlist for Jira. This means that certain superuser operations can only be performed from pre-approved IP addresses.

This feature is deactivated by default. If you choose to activate it, avoid locking yourself out of your own system by completing the configuration steps in the sequence shown in on this page.

  1. Read the Before You Start section below

  2. Configure your allowlist

  3. Enable the allowlist service

On this page:

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-For header as the source of the client's IP address. However, you can change the name of this header by modifying the server.tomcat.remoteip.remote-ip-header configuration property in the jira-config.properties file.
  • 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.

  1. Navigate to your Jira home directory and take a backup of the jira-config.properties file.
  2. Open your live jira-config.properties file in your preferred text editor.
  3. If you would like to add IP addresses, add the websudo.allowlist.ip property 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:7330
  4. If you would like to add IP address subnets, add the websudo.allowlist.cidr property 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::/64
  5. Check for any errors to ensure your lists won’t be omitted from the service configuration. 

    tip/resting Created with Sketch.

    Look for the following error text:

    Exception while parsing IP/CIDR Pattern {}. Ignoring part {}
  6. 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.

  1. Open your live jira-config.properties file in your preferred text editor.
  2. Search for websudo.allowlist.enabled.
  3. If the string is missing, add it to your file.
  4. Change the string’s value to true.
  5. Save and close your configuration file.
  6. 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.

  1. Open your live jira-config.properties file in your preferred text editor.
  2. Search for websudo.allowlist.enabled.
  3. Change the string’s value to false.
  4. Save and close the configuration file.
  5. 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.



Last modified on Sep 13, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.