Managing the IP Whitelist

Multiple sessions open from multiple distinct IP addresses

When XNAT detects that a single XNAT account has more than one session open from one or more IP addresses, it displays a warning message at the top of the page:

This can be useful for detecting unauthorized activity, but can be very distracting when the additional sessions are legitimate. The IP whitelist lets you declare particular IP addresses to remain "uncounted" against XNAT user accounts. This is used to prevent false warnings about multiple logins from multiple IP addresses. This is useful when a user's account is used for authenticating some sort of automated access to XNAT, e.g., running pipelines or scripts that access XNAT via REST.

It's worth noting that access for a particular account is not limited to a particular username, but is tied to the primary XNAT account. For example, you may be able to login via XNAT login or an LDAP ID associated with the same XNAT login. Also, the pipeline engine in XNAT 1.6 no longer uses the user account credentials directly, but instead uses alias tokens, limited use proxies for user authentication credentials. These would all tie into the primary XNAT user account and so, if used simultaneously from machines not on the IP whitelist, would appear as multiple logins from multiple IP addresses.

Managing the IP Whitelist

Currently there is no GUI tool for managing the IP whitelist. This is a fairly simple configuration to manage, however, so you can accomplish what you need with your browser for reading the IP and curl or a GUI REST client for modifying the IP whitelist.

You must use an administrator account to retrieve or set the IP whitelist.

Default IP Whitelist

The default IP whitelist consists of the IPv4 and IPv6 synonyms for localhost, as well as the primary IP address of the host server. This keeps simple host-based tasks, such as the auto-run pipeline, from showing up as additional sessions.

Getting the IP Whitelist

You can get the currently configured IP whitelist by doing a GET operation on the appropriate REST API function:


This returns a whitespace-separated list of whitelisted IP addresses. Any sessions connecting from those IP addresses are not counted against the total number of sessions for the current XNAT account. Here's a sample of how your IP whitelist might look:

Note that two of those addresses are within common private subnet ranges of 10.28.x.y. This is likely to be the most common use case, where other machines on the same private subnet are doing background processing on data contained within the XNAT.

Setting the IP Whitelist

You can set the IP whitelist by doing a PUT operation on the appropriate REST API function:


This REST API function takes the body of the call and uses that as the IP whitelist. This should be any whitelisted IPs separated by commas and whitespace. You can verify acceptance of your updated whitelist by making a GET call to the same address as described above.