Security

Overall access can be granted based on the IP address of an HTTP client. These restrictions are specified within a <remote> section, which contains one or more <host> elements. The source can be given either as an IP address, a host name, or a netmask given in CIDR format (e.g. 10.0.0.0/16 for all clients coming from the 10.0 network). The following allows access from localhost and all clients whose IP addresses start with "10.0". For all other IP addresses access is denied. IPv6 addresses are also supported.

Starting with Jolokia 2.6.1, the client IP address can be detected even if Jolokia runs behind a reverse proxy. Typical NGinx reverse proxy setup uses:

Jolokia can obtain the client IP address from the incoming X-Forwarded-For header, but headers like X-Real-IP and Forwarded (from RFC 7239) are also checked. From security perspective, the incoming headers should not be trusted blindly, so Jolokia always checks the actual incoming client IP address (whether it’s a browser address or the address of a reverse proxy).

In a complex scenario, where the actual user connects through multiple reverse proxies, X-Forwarded-For and Forwarded headers may contain a list of "remote addresses" for each hop along the route.

There’s a special configuration option named trustProxyHeaders (defaults to false) which can be used to declare that there’s a trusted reverse proxy which set a correct client (or untrusted reverse proxy) IP address as the "most external known remote address". By default the entire list of addresses is validated and if any of the addresses fails to match a pattern from <remote>/<host> list, the request is rejected.

This section specifies the Jolokia commands for which access is generally granted. For each command in the list, access can be further restricted within the <deny> part and each command missing in the list, which is forbidden globally, can be selectively enabled for certain MBeans in the <allow> section. If the <commands> section is missing completely, access to all commands is allowed.

All Jolokia commands described in Jolokia Protocol can be used in this section:

In the following example, access is granted to the read, list, search and version command, but not to write, notification and exec operations.

Within an <allow> section, access to MBeans can be granted regardless of the operations specified in the <commands> section. The reverse is true for the <deny> section: It rejects access to the MBeans specified here. Both sections contain one or more <mbean> elements which have a format like:

Within the <name> section the name of the MBean is specified. This can be either a complete ObjectName or a MBean pattern containing wildcards. The value given here must conform to the JMX specification for a valid ObjectName. On this MBean (or MBeans if name is a pattern), attributes are specified within one or more <attribute> elements and operations within one or more <operation> elements. The content can also be a pattern, which uses a wildcard *. e.g. <attribute>*</attribute> specifies all attributes on the given MBean. If for an <attribute> element the XML attribute mode="read" is given, then this attribute can be accessed only read-only.

Finally, access can be restricted based on the HTTP method with which an Jolokia request was received with the <http> element. Method allowed (post or get) are specified with an <method> inner element. The following example restricts the access to POST requests only:

It the <http> section is missing completely, any HTTP method can be used.

Jolokia (since version 1.0.3) supports the WHATWG (formerly W3C) specification for Cross-Origin Resource Sharing (also known as "CORS") which allows browser to access resources which are located on a different server than the calling script is loaded from. This specification provides a controlled way to come around the same origin policy. Most contemporary browsers support CORS.

Jolokia does not provide any web application even if it provides a JavaScript client that can be used in a web application. What’s also important is that Jolokia may be configured with authentication, but never uses server side sessions to keep the state (including the authentication state).
This means that Jolokia by itself never requires any CORS response headers. Tools like curl, wget or other non-browser HTTP clients are never involved in the CORS protocol.

However Jolokia JavaScript client library can be used in any web application. Because this library uses fetch() API, Jolokia server has to support CORS protocol.

Jolokia provides CORS configuration for two distinct scenarios:

Here’s a more detailed explanation of the protection provided by CORS protocol:

Even if the attacker could trick a real user to navigate to a malicious page which could call the remote Jolokia agent, fetch() API does not allow to replace or remove the Origin header being sent. There’s no way to disable CORS protocol at this level. Unless Jolokia responds with Access-Control-Allow-Origin: http://evil.com, the attacker can not read the data.

And to make the server protected too (remember - CORS is for protecting the client from allowing the data to be stolen), Jolokia may use <strict-checking> option, so the sent Origin (which can not be forged by an attacker) leads to a proper HTTP response with HTTP status code 403 (Forbidden).

By default, when no restrictor is specified, Jolokia allows cross origin access from any host. This can be limited to certain hosts by using <allow-origin> sections within a <cors> sections. These tags can contain the origin URL provided by browsers with the Origin: header literally or a wildcard specification that uses * to match any number of characters. When the browser application is accessible at a non-standard port number, the Origin header will include it, so the patterns used must take this into account.

Since Jolokia 2.1.3 we also support IPv6 origins. These have to be specified with bracket notation like [::ffff:7f00:1].

Next two subsections provide more details about these two interpretations of "cross origin request handling" by Jolokia. Some information may be repeated, but with more details.

Using <filter> element we can filter out results of list and search operations (even if search parameters include such MBean names). It’s not preventing users to access given MBeans unless specific <deny> element is present, but it may be used to make list/search results shorter.

Here’s the example:

The pattern format is not exactly the same as the patter used for javax.management.MBeanServerConnection.queryNames(). Here’s a summary of rules:

Jolokia uses the above patterns individually for each ObjectName and uses these methods:

For performance purposes there are some restrictions for using * within a pattern:

The following complete example applies various access restrictions:

But how do the agents lookup the policy file? By default, the agents will lookup for a policy file top-level in the classpath under the name jolokia-access.xml. Hence for the war agent, the policy file must be packaged within the war at WEB-INF/classes/jolokia-access.xml, for all other agents at /jolokia-access.xml. The location can be overwritten with the configuration parameter policyLocation, which has to be set differently depending on the agent type. Please refer to Agents for more details. The value of this init parameter can be any URL which can loaded by the JVM. A special case is an URL with the scheme classpath: which results in a lookup of the policy file within the classpath. As stated above, the default value of this parameter is classpath:/jolokia-access.xml. If a non-classpath URL is provided with this parameter, and the target policy file could not be found then access is completely denied. If a classpath lookup fails then access is globally granted and a warning is given on standard output.

Starting from Jolokia 2.6.1, Jolokia handles (by default, but it can be turned off using useFetchMetadata global option) the set of HTTP headers known as Fetch Metadata. There are 4 headers that modern browsers send in secure contexts:

While this is not a one-stop solution for security, Jolokia can restrict access when it is not a proper one. Definitely Jolokia URLs should not be valid when used beyond fetch() API or direct user navigation.