Luis-Miguel Alventosa's Blog

Monday September 25, 2006

Authentication and Authorization in JMX RMI connectors

The aim of this blog entry is to explain to you all the possible ways of configuring the JMX RMI connectors to perform authentication and authorization by walking through the following use cases.

• Use Case 1


• Authentication: "jmx.remote.x.password.file" environment property
• Authorization: "jmx.remote.x.access.file" environment property

This configuration can be used when authentication can be based on a properties file containing name/value pairs corresponding to role/password pairs and authorization can be also based on a properties file containing name/value pairs corresponding to role/access pairs where access can be any of readonly access which grants access to any remote operation defined in the MBeanServerConnection interface except createMBean, unregisterMBean, setAttribute, setAttributes and invoke, and readwrite access which grants access to any MBeanServerConnection operation.

Let's define a password file named my.password.file with the following entries:

monitorRole mrpasswd controlRole crpasswd

And an access file named my.access.file with the following entries:

monitorRole readonly controlRole readwrite

The server-side code snippet to initialize the JMXConnectorServer would look something like:

... MBeanServer mbs = ...; JMXServiceURL url = ...; Map env = ...; env.put("jmx.remote.x.password.file", "my.password.file"); env.put("jmx.remote.x.access.file", "my.access.file"); JMXConnectorServer cs = JMXConnectorServerFactory.newJMXConnectorServer(url, env, mbs); cs.start(); ...

The client-side code snippet to connect to the JMXConnectorServer with the identity monitorRole would look something like:

... JMXServiceURL url = ...; Map env = ...; String[] creds = {"monitorRole", "mrpasswd"}; env.put(JMXConnector.CREDENTIALS, creds); JMXConnector cc = JMXConnectorFactory.connect(url, env); MBeanServerConnection mbsc = cc.getMBeanServerConnection(); ...



• Use Case 2


• Authentication: "jmx.remote.x.password.file" environment property
• Authorization: Custom MBeanServerForwarder

This configuration can be used when authentication can be based on a properties file but you want to implement finer-grained authorization, i.e. the readonly/readwrite access supplied by the jmx.remote.x.access.file environment property doesn't fulfil your requirements and you don't want to go through a Security Manager and Java Policy File configuration.

For example, you could write an MBeanServerForwarder that restricts access to any user to the calls createMBean and unregisterMBean, but lets role1 perform any other given MBeanServerConnection operation, and lets role2 perform getAttribute on the MBeanServerDelegate MBean only.

Let's define a password file named my.password.file with the following entries:

role1 role1passwd role2 role2passwd role3 role3passwd

The server-side code that implements the custom MBeanServerForwarder as an inner class using proxies and invocation handlers and initializes the JMXConnectorServer with it would look something like:

... public class Agent { public static class MBSFInvocationHandler implements InvocationHandler { public static MBeanServerForwarder newProxyInstance() { final InvocationHandler handler = new MBSFInvocationHandler(); final Class[] interfaces = new Class[] {MBeanServerForwarder.class}; Object proxy = Proxy.newProxyInstance( MBeanServerForwarder.class.getClassLoader(), interfaces, handler); return MBeanServerForwarder.class.cast(proxy); } public Object invoke(Object proxy, Method method, Object[] args) throws Throwable { final String methodName = method.getName(); if (methodName.equals("getMBeanServer")) { return mbs; } if (methodName.equals("setMBeanServer")) { if (args[0] == null) throw new IllegalArgumentException("Null MBeanServer"); if (mbs != null) throw new IllegalArgumentException("MBeanServer object " + "already initialized"); mbs = (MBeanServer) args[0]; return null; } // Retrieve Subject from current AccessControlContext AccessControlContext acc = AccessController.getContext(); Subject subject = Subject.getSubject(acc); // Allow operations performed locally on behalf of the connector server itself if (subject == null) { return method.invoke(mbs, args); } // Restrict access to "createMBean" and "unregisterMBean" to any user if (methodName.equals("createMBean") || methodName.equals("unregisterMBean")) { throw new SecurityException("Access denied"); } // Retrieve JMXPrincipal from Subject Set<JMXPrincipal> principals = subject.getPrincipals(JMXPrincipal.class); if (principals == null || principals.isEmpty()) { throw new SecurityException("Access denied"); } Principal principal = principals.iterator().next(); String identity = principal.getName(); // "role1" can perform any operation other than "createMBean" and "unregisterMBean" if (identity.equals("role1")) { return method.invoke(mbs, args); } // "role2" can only call "getAttribute" on the MBeanServerDelegate MBean if (identity.equals("role2") && methodName.equals("getAttribute") && MBeanServerDelegate.DELEGATE_NAME.equals(args[0])) { return method.invoke(mbs, args); } throw new SecurityException("Access denied"); } private MBeanServer mbs; } public static void main (String args[]) throws Exception { ... MBeanServer mbs = ...; JMXServiceURL url = ...; Map env = ...; env.put("jmx.remote.x.password.file", "my.password.file"); JMXConnectorServer cs = JMXConnectorServerFactory.newJMXConnectorServer(url, env, mbs); MBeanServerForwarder mbsf = MBSFInvocationHandler.newProxyInstance(); cs.setMBeanServerForwarder(mbsf); cs.start(); ... } }

The client-side code snippet to connect to the JMXConnectorServer with the identity role1 would look something like:

... JMXServiceURL url = ...; Map env = ...; String[] creds = {"role1", "role1passwd"}; env.put(JMXConnector.CREDENTIALS, creds); JMXConnector cc = JMXConnectorFactory.connect(url, env); MBeanServerConnection mbsc = cc.getMBeanServerConnection(); ...

For example,

• calling mbsc.createMBean() or mbsc.unregisterMBean() on a role1, role2, or role3 authenticated connection will throw a SecurityException.
• calling mbsc.invoke() on a given MBean on a role1 authenticated connection will succeed whereas calling the same operation on a role2 or role3 authenticated connection will throw a SecurityException.
• calling mbsc.getAttribute(MBeanServerDelegate.DELEGATE_NAME, "MBeanServerId") on a role1 or role2 authenticated connection will succeed whereas calling the same operation on a role3 authenticated connection will throw a SecurityException.


• Use Case 3


• Authentication: Custom JAAS LoginModule (e.g. the LDAP LoginModule in JDK 6)
• Authorization: "jmx.remote.x.access.file" environment property

This configuration can be used when authentication based on a properties file is not appropriate because the environment where the application is to be deployed already has its own authentication backend and a JAAS LoginModule already exists for it or you want to implement your own JAAS LoginModule, and it is acceptable to have authorization based on the readonly/readwrite access rights specified in a properties file.

The aim here is not to show you how to implement a JAAS LoginModule but how to configure the JMXConnectorServer to use it. For this purpose, the JAAS LDAP LoginModule that is part of JDK 6 will be used. Have a look at the JAAS LDAP LoginModule javadoc for more detailed info.

Let's define an access file named my.access.file with the following entries:

monitorRole readonly controlRole readwrite

And a JAAS configuration file named ldap.config which defines a JAAS configuration entry named SunConfig that tells which JAAS LoginModules need to be invoked. The SunConfig configuration entry specifies just one login module, the LdapLoginModule.

SunConfig { com.sun.security.auth.module.LdapLoginModule REQUIRED userProvider="ldap://sun-ds/ou=people,dc=sun,dc=com" userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))" authzIdentity=monitorRole useSSL=false; };

Use the environment property jmx.remote.x.login.config to tell the JMX agent which JAAS configuration entry in the JAAS configuration file must be used. The server-side code snippet to initialize the JMXConnectorServer with the SunConfig configuration entry would look something like:

... MBeanServer mbs = ...; JMXServiceURL url = ...; Map env = ...; env.put("jmx.remote.x.login.config", "SunConfig"); env.put("jmx.remote.x.access.file", "my.access.file"); JMXConnectorServer cs = JMXConnectorServerFactory.newJMXConnectorServer(url, env, mbs); cs.start(); ...

Use the system property java.security.auth.login.config to specify the JAAS configuration file to load in the command-line:

java -Djava.security.auth.login.config=ldap.config Agent

The client-side code snippet to connect to the JMXConnectorServer with the LDAP user duke (that will get mapped to monitorRole by the JAAS LDAP LoginModule for authorization purposes) would look something like:

... JMXServiceURL url = ...; Map env = ...; String[] creds = {"duke", "dukepasswd"}; env.put(JMXConnector.CREDENTIALS, creds); JMXConnector cc = JMXConnectorFactory.connect(url, env); MBeanServerConnection mbsc = cc.getMBeanServerConnection(); ...



• Use Case 4


• Authentication: Custom JMXAuthenticator
• Authorization: "jmx.remote.x.access.file" environment property

This configuration can be used when authentication based on a properties file is not appropriate because the environment where the application is to be deployed already has its own authentication backend or, there is no JAAS LoginModule for it and you don't want to implement your own JAAS LoginModule, or the default NameCallback and PasswordCallback callbacks used by the default JMXAuthenticator implementation don't fulfil your requirements, and it is acceptable to have authorization based on the readonly/readwrite access rights specified in a properties file.

For example, you could write a JMXAuthenticator that performs authentication based on a (username, password, realm) tuple.

Let's define an access file named my.access.file with the following entries:

monitorRole readonly controlRole readwrite

The server-side code that implements the custom JMXAuthenticator as an inner class and initializes the JMXConnectorServer with it would look something like:

... public class Agent { public static class RealmJMXAuthenticator implements JMXAuthenticator { public Subject authenticate(Object credentials) { // Verify that credentials is of type String[]. // if (!(credentials instanceof String[])) { // Special case for null so we get a more informative message if (credentials == null) { throw new SecurityException("Credentials required"); } throw new SecurityException("Credentials should be String[]"); } // Verify that the array contains three elements (username/password/realm). // final String[] aCredentials = (String[]) credentials; if (aCredentials.length != 3) { throw new SecurityException("Credentials should have 3 elements"); } // Perform authentication // String username = (String) aCredentials[0]; String password = (String) aCredentials[1]; String realm = (String) aCredentials[2]; ... perform authentication based on the (username/password/realm) tuple ... if (authentication-ok) { return new Subject(true, Collections.singleton(new JMXPrincipal(username)), Collections.EMPTY_SET, Collections.EMPTY_SET); } else { throw new SecurityException("Invalid credentials"); } } } public static void main (String args[]) throws Exception { ... MBeanServer mbs = ...; JMXServiceURL url = ...; Map env = ...; env.put(JMXConnectorServer.AUTHENTICATOR, new RealmJMXAuthenticator()); env.put("jmx.remote.x.access.file", "my.access.file"); JMXConnectorServer cs = JMXConnectorServerFactory.newJMXConnectorServer(url, env, mbs); cs.start(); ... } }

The client-side code snippet to connect to the JMXConnectorServer with username monitorRole, password mrpasswd, and realm FileRealm would look something like:

... JMXServiceURL url = ...; Map env = ...; String[] creds = {"monitorRole", "mrpasswd", "FileRealm"}; env.put(JMXConnector.CREDENTIALS, creds); JMXConnector cc = JMXConnectorFactory.connect(url, env); MBeanServerConnection mbsc = cc.getMBeanServerConnection(); ...



• Use Case 5


• Authentication: "jmx.remote.x.password.file" environment property
• Authorization: Security Manager and Java Policy File

This configuration can be used when authentication can be based on a properties file but you want to implement finer-grained authorization based on an installed Security Manager and a Java Policy File.

Let's define a password file named my.password.file with the following entries:

monitorRole mrpasswd controlRole crpasswd

And a java policy file named java.policy which grants access to user monitorRole to getAttribute and getAttributes operations on MBeans under the com.example domain and full MBean server access to user controlRole.

grant codeBase "file:<agent-codebase>" { ... permissions required by the agent to start the connector server ... in JDK 5.0 and JDK 6: use the JDK 5.0 permission checking approach, i.e. you have to grant to the "creator" of the connector server all the permissions needed for each single remote operation performed by every single remote user over this connector. This means you have to specify the union of the set of permissions granted to every remote user. Thus for this use case the permission to be granted would be: permission javax.management.MBeanPermission "*", "*"; - or - in JDK 6 only: use the new JDK 6 permission checking approach, i.e. instead of having to grant all the permissions needed for each single remote operation performed by every single remote user over this connector to the "creator" of the connector server you just specify a SubjectDelegationPermission for every remote user. This new approach avoids granting to the "creator" of the connector server more permissions than he/she needs to, i.e. the specific permissions for the remote MBean server operations performed by each individual remote user are now only granted in each remote user principal grant clause. Thus for this use case the permissions to be granted would be: permission javax.management.remote.SubjectDelegationPermission "javax.management.remote.JMXPrincipal.monitorRole"; permission javax.management.remote.SubjectDelegationPermission "javax.management.remote.JMXPrincipal.controlRole"; ... }; grant principal javax.management.remote.JMXPrincipal "monitorRole" { permission javax.management.MBeanPermission "[com.example:*]", "getAttribute, getAttributes"; }; grant principal javax.management.remote.JMXPrincipal "controlRole" { permission javax.management.MBeanPermission "*", "*"; };

The server-side code snippet to initialize the JMXConnectorServer would look something like:

... MBeanServer mbs = ...; JMXServiceURL url = ...; Map env = ...; env.put("jmx.remote.x.password.file", "my.password.file"); JMXConnectorServer cs = JMXConnectorServerFactory.newJMXConnectorServer(url, env, mbs); cs.start(); ...

Supply the system properties java.security.manager and java.security.policy in the command-line to install a security manager and specify a java policy file, respectively :

java -Djava.security.manager -Djava.security.policy=java.policy Agent

The client-side code snippet to connect to the JMXConnectorServer with the identity monitorRole would look something like:

... JMXServiceURL url = ...; Map env = ...; String[] creds = {"monitorRole", "mrpasswd"}; env.put(JMXConnector.CREDENTIALS, creds); JMXConnector cc = JMXConnectorFactory.connect(url, env); MBeanServerConnection mbsc = cc.getMBeanServerConnection(); ...



• Use Case 6


• Any other valid combination of the Authentication and Authorization mechanisms explained above