This chapter is from the book
This chapter is from the book
This chapter is from the book
The JBossNS Architecture
The JBossNS architecture is a Java socket/RMI-based implementation of the javax.naming.Context interface. It is a client/server implementation that can be accessed remotely. The implementation is optimized so that access from within the same VM in which the JBossNS server is running does not involve sockets. Same-VM access occurs through an object reference that is available as a global singleton. Figure 3.1 illustrates some of the key classes in the JBossNS implementation and their relationships.
)
Figure 3.1 Key components in the JBossNS architecture.
Let's start with the NamingService MBean. The NamingService MBean provides the JNDI naming service. This is a key service that is used pervasively by the J2EE technology components. The configurable attributes for the NamingService MBean are as follows:
-
Port—The jnp protocol listening port for the NamingService. If it is not specified, the default is 1099—the same as the RMI registry default port.
-
RmiPort—The RMI port on which the RMI Naming implementation will be exported. If it is not specified, the default is 0, which means use any available port.
-
BindAddress—The specific address the NamingService listens on. This can be used on a multi-homed host for a java.net.ServerSocket that will accept connect requests only on one of its addresses.
-
RmiBindAddress—The specific address the RMI server portion of the NamingService listens on. This can be used on a multi-homed host for a java.net.ServerSocket that will accept connect requests only on one of its addresses. If this is not specified and the BindAddress is, the RmiBindAddress defaults to the BindAddress value.
-
Backlog—The maximum queue length for incoming connection indications (a request to connect), set to the Backlog parameter. If a connection indication arrives when the queue is full, the connection is refused.
-
ClientSocketFactory—An optional custom java.rmi.server.RMIClientSocketFactory implementation classname. If it is not specified, the default RMIClientSocketFactory is used.
-
ServerSocketFactory—An optional custom java.rmi.server.RMIServerSocketFactory implementation classname. If it is not specified, the default RMIServerSocketFactory is used.
-
JNPServerSocketFactory—An optional custom javax.net.ServerSocketFactory implementation classname. This is the factory for the ServerSocket that is used to bootstrap the download of the JBoss Naming interface. If it is not specified, the javax.net.ServerSocketFactory.getDefault() method value is used.
NamingService also creates the java:comp context such that access to this context is isolated based on the context class loader of the thread that accesses the java:comp context. This provides the application component private ENC that is required by the J2EE specs. This segregation is accomplished by binding a javax.naming.Reference to a context that uses org.jboss.naming.ENCFactory as its javax.naming.ObjectFactory. When a client performs a lookup of java:comp or any subcontext, the ENCFactory checks the thread context ClassLoader and performs a lookup into a map, using the ClassLoader as the key.
If a context instance does not exist for the class loader instance, one is created and associated with that class loader in the ENCFactory map. Thus, correct isolation of an application component’s ENC relies on each component receiving a unique ClassLoader that is associated with the component threads of execution.
The NamingService delegates its functionality to an org.jnp.server.Main MBean. Duplicate MBeans are needed because JBossNS started out as a standalone JNDI implementation and can still be run as such. The NamingService MBean embeds the Main instance into the JBoss server so that usage of JNDI with the same VM as the JBoss server does not incur any socket overhead. The configurable attributes of the NamingService are really the configurable attributes of the JBossNS Main MBean. The setting of any attributes on the NamingService MBean simply sets the corresponding attributes on the Main MBean that the NamingService contains. When the NamingService is started, it starts the contained Main MBean to activate the JNDI naming service.
In addition, the NamingService exposes the Naming interface operations through a JMX detyped invoke operation. This allows the naming service to be accessed via JMX adaptors for arbitrary protocols. We will look at an example of how HTTP can be used to access the naming service using the invoke operation later in this chapter.
The details of threads and the thread context class loader are beyond the scope of this book, but the JNDI tutorial provides a concise discussion that is applicable. See http://java.sun.com/products/jndi/tutorial/beyond/misc/classloader.html for the details.
When the Main MBean is started, it performs the following tasks:
Instantiates an org.jnp.naming.NamingService instance and sets it as the local VM server instance. This is used by any org.jnp.interfaces.NamingContext instances that are created within the JBoss server VM to avoid RMI calls over TCP/IP.
Exports the NamingServer instance’s org.jnp.naming.interfaces.Naming RMI interface, using the configured RmiPort, ClientSocketFactory, and ServerSocketFactoryattributes.
Creates a socket that listens on the interface given by the BindAddress and Port attributes.
Spawns a thread to accept connections on the socket.
The Naming InitialContext Factories
The JBoss JNDI provider currently supports several different InitialContext factory implementations. The most commonly used factory is the org.jnp.interfaces.NamingContextFactory implementation. Its properties include the following:
-
java.naming.factory.initial—The name of the environment property for specifying the initial context factory to use. The value of the property should be the fully qualified classname of the factory class that will create an initial context. If it is not specified, a javax.naming.NoInitialContextException will be thrown when an InitialContext object is created.
-
java.naming.provider.url—The name of the environment property for specifying the location of the JBoss JNDI service provider that the client will use. The NamingContextFactory class uses this information to determine which JBossNS server to connect to. The value of the property should be a URL string. For JBossNS, the URL format is jnp://host:port/[jndi_path]. The jnp: portion of the URL is the protocol and refers to the socket/RMI-based protocol used by JBoss. The jndi_path portion of the URL is an optional JNDI name relative to the root context (for example, apps or apps/tmp). Everything but the host component is optional. The following examples are equivalent because the default port value is 1099:
-
java.naming.factory.url.pkgs—The name of the environment property for specifying the list of package prefixes to use when loading URL context factories. The value of the property should be a colon-separated list of package prefixes for the classname of the factory class that will create a URL context factory. For the JBoss JNDI provider, this must be org.jboss.naming:org.jnp.interfaces. This property is essential for locating the jnp: and java: URL context factories of the JBoss JNDI provider.
-
jnp.socketFactory—The fully qualified classname of the javax.net.SocketFactory implementation to use to create the bootstrap socket. The default value is org.jnp.interfaces.TimedSocketFactory. TimedSocketFactory is a simple SocketFactory implementation that supports the specification of a connection and read timeout. These two properties are specified by the following:
-
jnp.timeout—The connection timeout, in milliseconds. The default value is 0, which means the connection will block until the VM TCP/IP layer times out.
-
jnp.sotimeout—The connected socket read timeout, in milliseconds. The default value is 0, which means reads will block. This is the value passed to Socket.setSoTimeout on the newly connected socket.
jnp://www.jboss.org:1099/
http://www.jboss.org:1099
http://www.jboss.org
When a client creates an InitialContext with these JBossNS properties available, the org.jnp.interfaces.NamingContextFactory object is used to create the Context instance that will be used in subsequent operations. The NamingContextFactory is the JBossNS implementation of the javax.naming.spi.InitialContextFactory interface. When the NamingContextFactory class is asked to create a context, it creates an org.jnp. interfaces.NamingContext instance with the InitialContext environment and the name of the context in the global JNDI namespace. The NamingContext instance actually performs the task of connecting to the JBossNS server and implements the Context interface. The Context.PROVIDER_URL information from the environment indicates from which server to obtain a NamingServer RMI reference.
The association of the NamingContext instance to a NamingServer instance is done in a lazy fashion on the first Context operation that is performed. When a Context operation is performed and the NamingContext has no NamingServer associated with it, it looks to see if its environment properties define a Context.PROVIDER_URL. A Context.PROVIDER_URL defines the host and port of the JBossNS server the Context is to use. If there is a provider URL, the NamingContext first checks whether a Naming instance keyed by the host and port pair has already been created by checking a NamingContext class static map. It simply uses the existing Naming instance if one for the host/port pair has already been obtained. If no Naming instance has been created for the given host and port, the NamingContext connects to the host and port by using a java.net.Socket, and it retrieves a Naming RMI stub from the server by reading a java.rmi.MarshalledObject from the socket and invoking its get method. The newly obtained Naming instance is cached in the NamingContext server map under the host/port pair. If no provider URL is specified in the JNDI environment associated with the context, the NamingContext simply uses the in-VM Naming instance set by the Main MBean.
The NamingContext implementation of the Context interface delegates all operations to the Naming instance associated with the NamingContext. The NamingServer class that implements the Naming interface uses a java.util.Hashtable as the Context store. There is one unique NamingServer instance for each distinct JNDI name for a given JBossNS server. At any given moment, zero or more active transient NamingContext instances refer to a NamingServer instance. The purpose of the NamingContext is to act as a context to the Naming interface adaptor that manages translation of the JNDI names passed to the NamingContext. Because a JNDI name can be relative or a URL, it needs to be converted into an absolute name in the context of the JBossNS server to which it refers. This translation is a key function of the NamingContext.
Naming Discovery in Clustered Environments
When running in a clustered JBoss environment, you can choose not to specify a Context.PROVIDER_URL value and let the client query the network for available naming services. This only works with JBoss servers running with the all configuration or an equivalent configuration that has org.jboss.ha.framework.server.ClusterPartition and org.jboss.ha.jndi.HANamingService services deployed. The discovery process consists of sending a multicast request packet to the discovery address/port and waiting for any node to respond. The response is an HA-RMI version of the Naming interface. The following InitialContext properties affect the discovery configuration:
-
jnp.partitionName—The name of the cluster partition that discovery should be restricted to. If you are running in an environment that has multiple clusters, you might want to restrict the naming discovery to a particular cluster. There is no default value, meaning that any cluster response will be accepted.
-
jnp.discoveryGroup—The multicast IP/address to which the discovery query is sent. The default is 230.0.0.4.
-
jnp.discoveryPort—The port to which the discovery query is sent. The default is 1102.
-
jnp.discoveryTimeout—The time, in milliseconds, to wait for a discovery query response. The default value is 5000 (5 seconds).
-
jnp.disableDiscovery—A flag that indicates whether the discovery process should be avoided. Discovery occurs when either no Context.PROVIDER_URL is specified or no valid naming service can be located among the URLs specified. If the jnp.disableDiscovery flag is true, then discovery will not be attempted.
The HTTP InitialContext Factory Implementation
The JNDI naming service can be accessed over HTTP. From a JNDI client’s perspective, this is a transparent change because the client continues to use the JNDI Context interface. Operations through the Context interface are translated into HTTP posts to a servlet that passes the request to the NamingService, using its JMX invoke operation. Advantages of using HTTP as the access protocol include better access through firewalls and proxies set up to allow HTTP, as well as the ability to secure access to the JNDI service, using standard servlet role-based security.
To access JNDI over HTTP, you use org.jboss.naming.HttpNamingContextFactory as the factory implementation. The following is the complete set of support InitialContext environment properties for this factory:
-
java.naming.factory.initial—This is the name of the environment property for specifying the initial context factory, which must be org.jboss.naming.HttpNamingContextFactory.
-
java.naming.provider.url (or Context.PROVIDER_URL)—This must be set to the HTTP URL of the JMX invoker servlet. It depends on the configuration of the http-invoker.sar and its contained WAR, but the default setup places the JMX invoker servlet under /invoker/JMXInvokerServlet. The full HTTP URL would be the public URL of the JBoss servlet container plus /invoker/JMXInvokerServlet. The following are some examples:
-
java.naming.factory.url.pkgs—For all JBoss JNDI providers, this must be org.jboss.naming:org.jnp.interfaces. This property is essential for locating the jnp: and java: URL context factories of the JBoss JNDI provider.
http://www.jboss.org:8080/invoker/JMXInvokerServlet
http://www.jboss.org/invoker/JMXInvokerServlet
https://www.jboss.org/invoker/JMXInvokerServlet
The first example accesses the servlet, using port 8080. The second uses the standard HTTP port 80, and the third uses an SSL-encrypted connection to the standard HTTPS port 443.
The JNDI Context implementation returned by the HttpNamingContextFactory is a proxy that delegates invocations made on it to a bridge servlet, which forwards the invocation to the NamingService through the JMX bus and marshals the reply back over HTTP. The proxy needs to know what the URL of the bridge servlet is in order to operate. This value may have been bound on the server side if the JBoss web server has a well-known public interface. If the JBoss web server is sitting behind one or more firewalls or proxies, the proxy cannot know what URL is required. In this case, the proxy will be associated with a system property value that must be set in the client VM. For more information on the operation of JNDI over HTTP, see the section "Accessing JNDI over HTTP," later in this chapter.
The Login InitialContext Factory Implementation
JAAS is the preferred method for authenticating a remote client to JBoss. However, for simplicity and to ease the migration from other application server environments that do not use JAAS, JBoss allows the security credentials to be passed through the InitialContext. JAAS is still used under the covers, but there is no manifest use of the JAAS interfaces in the client application.
The factory class that provides this capability is org.jboss.security.jndi.LoginInitialContextFactory.
The following is the complete set of support InitialContext environment properties for this factory:
-
java.naming.factory.initial—This is the name of the environment property for specifying the initial context factory, which must be org.jboss.security.jndi.LoginInitialContextFactory.
-
java.naming.provider.url—This must be set to a NamingContextFactory provider URL. LoginInitialContext is really just a wrapper around NamingContextFactory that adds a JAAS login to the existing NamingContextFactory behavior.
-
java.naming.factory.url.pkgs—For all JBoss JNDI providers, this must be org.jboss.naming:org.jnp.interfaces. This property is essential for locating the jnp: and java: URL context factories of the JBoss JNDI provider.
-
java.naming.security.principal (or Context.SECURITY_PRINCIPAL)—These are the principal to authenticate. This may be either a java.security.Principal implementation or a string that represents the name of a principal.
-
java.naming.security.credentials (or Context.SECURITY_CREDENTIALS)—These are the credentials that should be used to authenticate the principal (for example, password, session key, and so on).
-
java.naming.security.protocol (or Context.SECURITY_PROTOCOL)—This gives the name of the JAAS login module to use for the authentication of the principal and credentials.
Accessing JNDI over HTTP
In addition to the legacy RMI/JRMP with a socket bootstrap protocol, JBoss provides support for accessing its JNDI naming service over HTTP. This capability is provided by http-invoker.sar. The following is the structure of http-invoker.sar:
http-invoker.sar +- META-INF/jboss-service.xml +- invoker.war | +- WEB-INF/jboss-web.xml | +- WEB-INF/classes/org/jboss/invocation/http/servlet/InvokerServlet.class | +- WEB-INF/classes/org/jboss/invocation/http/servlet/NamingFactoryServlet.class | +- WEB-INF/classes/org/jboss/invocation/http/servlet/ReadOnlyAccessFilter.class | +- WEB-INF/classes/roles.properties | +- WEB-INF/classes/users.properties | +- WEB-INF/web.xml | +- META-INF/MANIFEST.MF +- META-INF/MANIFEST.MF
The jboss-service.xml descriptor defines the HttpInvoker and HttpInvokerHA MBeans. These services handle the routing of method invocations that are sent via HTTP to the appropriate target MBean on the JMX bus.
The http-invoker.war web application contains servlets that handle the details of the HTTP transport. NamingFactoryServlet handles creation requests for the JBoss JNDI naming service javax.naming.Context implementation. InvokerServlet handles invocations made by RMI/HTTP clients. ReadOnlyAccessFilter allows you to secure the JNDI naming service while making a single JNDI context available for read-only access by unauthenticated clients.
Before looking at the configurations, let’s look at the operation of the http-invoker services. Figure 3.2 shows a logical view of the structure of a JBoss JNDI proxy and its relationship to the JBoss server-side components of the http-invoker. The proxy is obtained from the NamingFactoryServlet, using an InitialContext with the Context.INITIAL_CONTEXT_FACTORY property set to org.jboss.naming.HttpNamingContextFactory and the Context.PROVIDER_URL property set to the HTTP URL of the NamingFactoryServlet. The resulting proxy is embedded in an org.jnp.interfaces.NamingContext instance that provides the Context interface implementation.
)
Figure 3.2 The HTTP invoker proxy/server structure for a JNDI context.
The proxy is an instance of org.jboss.invocation.http.interfaces.HttpInvokerProxy, and it implements the org.jnp.interfaces.Naming interface. Internally, the HttpInvokerProxy contains an invoker that marshals the Naming interface method invocations to the InvokerServlet via HTTP posts. The InvokerServlet translates these posts into JMX invocations to the NamingService and returns the invocation response back to the proxy in the HTTP post response.
Several configuration values need to be set to tie all these components together, and Figure 3.3 illustrates the relationship between configuration files and the corresponding components.
)
Figure 3.3 The relationship between configuration files and JNDI/HTTP component.
The http-invoker.sar/META-INF/jboss-service.xml descriptor defines the HttpProxyFactory that creates the HttpInvokerProxy for the NamingService. The attributes that need to be configured for the HttpProxyFactory include the following:
-
InvokerName—The JMX ObjectName of the NamingService defined in the conf/jboss-service.xml descriptor. The standard setting used in the JBoss distributions is jboss:service=Naming.
-
InvokerURL or InvokerURLPrefix + InvokerURLSuffix + UseHostName—You can specify the full HTTP URL to the InvokerServlet by using the InvokerURL attribute, or you can specify the hostname-independent parts of the URL and have the HttpProxyFactory fill them in. An example of an InvokerURL value might be http://jbosshost1.dot.com:8080/invoker/JMXInvokerServlet. This can be broken down into the following:
-
InvokerURLPrefix—The URL prefix prior to the hostname. Typically, this will be http:// or https://, if SSL is to be used.
-
InvokerURLSuffix—The URL suffix after the hostname. This will include the port number of the web server as well as the deployed path to the InvokerServlet. For the sample InvokerURL value, the InvokerURLSuffix would be :8080/invoker/JMXInvokerServlet. The port number is determined by the web container service settings. The path to the InvokerServlet is specified in the http-invoker.sar/invoker.war/WEB-INF/web.xml descriptor.
-
UseHostName—A flag that indicates whether the hostname should be used in place of the host IP address when building the hostname portion of the full InvokerURL. If it is true, the InetAddress.getLocalHost().getHostName() method is used. Otherwise, the InetAddress.getLocalHost().getHostAddress() method is used.
-
ExportedInterface—The org.jnp.interfaces.Naming interface the proxy will expose to clients. The actual client of this proxy is the JBoss JNDI implementation NamingContext class, which a JNDI client obtains from InitialContext lookups when using the JBoss JNDI provider.
-
JndiName—The name in JNDI under which the proxy is bound. This needs to be set to a blank/empty string to indicate that the interface should not be bound into JNDI. You can't use the JNDI to bootstrap itself. That is the role of the NamingFactoryServlet.
The http-invoker.sar/invoker.war/WEB-INF/web.xml descriptor defines the mappings of NamingFactoryServlet and InvokerServet along with their initialization parameters. The configuration of the NamingFactoryServlet relevant to JNDI/HTTP is the JNDIFactory entry, which defines the following:
A namingProxyMBean initialization parameter that maps to the HttpProxyFactory MBean name. This is used by the NamingFactoryServlet to obtain the Naming proxy, which it returns in response to HTTP posts. For the default http-invoker.sar/ META-INF/jboss-service.xml settings, the name is jboss:service=invoker,type=http,target=Naming.
A proxy initialization parameter that defines the name of the namingProxyMBean attribute to query for the Naming proxy value. This defaults to the attribute name Proxy.
The servlet mapping for the JNDIFactory configuration. The default setting for the unsecured mapping is /JNDIFactory/*. This is relative to the context root of the http-invoker.sar/invoker.war, which by default is the WAR name minus the .war suffix.
The configuration of the InvokerServlet relevant to JNDI/HTTP is the JMXInvokerServlet, which defines the servlet mapping of the InvokerServlet. The default setting for the unsecured mapping is /JMXInvokerServlet/*. This is relative to the context root of the http-invoker.sar/invoker.war, which by default is the WAR name minus the .war suffix.
Accessing JNDI over HTTPS
To be able to access JNDI over HTTP/SSL, you need to enable an SSL connector on the web container. The details of this are covered in Chapter 9, "Web Applications." This section demonstrates the use of HTTPS with a simple sample client that uses an HTTPS URL as the JNDI provider URL. This example includes an SSL connector configuration, so unless you are interested in the details of the SSL connector setup, the example is self-contained.
This example also provides a configuration of the HttpProxyFactory setup to use an HTTPS URL. The following shows the section of the http-invoker.sar jboss-service. xml descriptor that the example installs to provide this configuration:
<!-- Expose the Naming service interface via HTTPS -->
<mbean code="org.jboss.invocation.http.server.HttpProxyFactory"
name="jboss:service=invoker,type=https,target=Naming">
<!-- The Naming service we are proxying -->
<attribute name="InvokerName">jboss:service=Naming</attribute>
<!-- Compose the invoker URL from the cluster node address -->
<attribute name="InvokerURLPrefix">https://</attribute>
<attribute name="InvokerURLSuffix">:8443/invoker/JMXInvokerServlet </attribute>
<attribute name="UseHostName">true</attribute>
<attribute name="ExportedInterface">org.jnp.interfaces.Naming </attribute>
<attribute name="JndiName"/>
<attribute name="ClientInterceptors">
<interceptors>
<interceptor>org.jboss.proxy.ClientMethodInterceptor </interceptor>
<interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>
<interceptor>org.jboss.naming.interceptors.ExceptionInterceptor
</interceptor>
<interceptor>org.jboss.invocation.InvokerInterceptor </interceptor>
</interceptors>
</attribute>
</mbean>
All that has changed relative to the standard HTTP configuration are the InvokerURLPrefix and InvokerURLSuffix attributes, which set up an HTTPS URL by using the 8443 port.
At a minimum, for a JNDI client using HTTPS, you need to set up an HTTPS URL protocol handler. This example uses Java Secure Socket Extension (JSSE) for HTTPS. The JSSE documentation does a good job of describing what is necessary in order to use HTTPS. You need to follow these steps to configure the sample client shown in Listing 3.16:
-
You need to make available to Java a protocol handler for HTTPS URLs. The JSSE release includes an HTTPS handler in the com.sun.net.ssl.internal.http://www.protocol package. To enable the use of HTTPS URLs, you include this package in the standard URL protocol handler search property, java.protocol.handler.pkgs. You set the java.protocol.handler.pkgs property in the Ant script.
-
You install the JSSE security provider in order for SSL to work. You can do this either by installing the JSSE JARs as an extension package or programmatically. This example uses the programmatic because it is the less intrusive method.
-
The JNDI provider URL must use HTTPS as the protocol. Lines 24–25 of the ExClient code specify an HTTP/SSL connection to the localhost on port 8443. The hostname and port are defined by the web container SSL connector.
-
You disable the validation of the HHTPS URL hostname against the server certificate. By default, the JSSE HTTPS protocol handler employs a strict validation of the hostname portion of the HTTPS URL against the common name of the server certificate. This is the same check that web browsers do when you connect to a secured website. The example in Listing 3.16 uses a self-signed server certificate that uses the common name "Chapter 8 SSL Example" rather than a particular hostname, and this is likely to be common in development environments or intranets. The JBoss HttpInvokerProxy will override the default hostname checking if a org.jboss.security.ignoreHttpsHost system property exists and has a value of true. You set the org.jboss.security.ignoreHttpsHost property to true in the Ant script.
Listing 3.16 A JNDI Client That Uses HTTPS as the Transport
package org.jboss.chap3.ex1;
import java.security.Security;
import java.util.Properties;
import javax.naming.Context;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[]) throws Exception
{
Properties env = new Properties();
env.setProperty(Context.INITIAL_CONTEXT_FACTORY,
"org.jboss.naming.HttpNamingContextFactory");
env.setProperty(Context.PROVIDER_URL,
"https://localhost:8443/invoker/JNDIFactorySSL");
Context ctx = new InitialContext(env);
System.out.println("Created InitialContext, env=" + env);
Object data = ctx.lookup("jmx/invoker/RMIAdaptor");
System.out.println("lookup(jmx/invoker/RMIAdaptor): " + data);
}
}
To test the client, you first build the Chapter 3 example to create the chap3 configuration file set:
[examples]$ ant -Dchap=chap3 config example
Next, you start the JBoss server, using the chap3 configuration file set:
[bin]$ sh run.sh -c chap3
Finally, you run the ExClient by using the following:
[examples]$ ant -Dchap=chap3 -Dex=1 run-example ... run-example1: [java] Created InitialContext,
Securing Access to JNDI over HTTP
One benefit to accessing JNDI over HTTP is that it is easy to secure access to the JNDI InitialContext factory as well as the naming operations, using standard web declarative security. This is possible because the server-side handling of the JNDI/HTTP transport is implemented with two servlets. These servlets are included in the http-invoker.sar/invoker.war directory found in the default and all configuration deploy directories, as shown previously. To enable secured access to JNDI, you need to edit the invoker.war/WEB-INF/web.xml descriptor and remove all unsecured servlet mappings. For example, the web.xml descriptor shown in Listing 3.17 allows access to the invoker.war servlets only if the user has been authenticated and has the role HttpInvoker.
Listing 3.17 An Example of a web.xml Descriptor for Secured Access to the JNDI Servlets
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<!-- ### Servlets -->
<servlet>
<servlet-name>JMXInvokerServlet</servlet-name>
<servlet-class>
org.jboss.invocation.http.servlet.InvokerServlet
</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet> <servlet>
<servlet-name>JNDIFactory</servlet-name>
<servlet-class>
org.jboss.invocation.http.servlet.NamingFactoryServlet
</servlet-class>
<init-param>
<param-name>namingProxyMBean</param-name>
<param-value>jboss:service=invoker,type=http,target=Naming
</param-value>
</init-param>
<init-param>
<param-name>proxyAttribute</param-name>
<param-value>Proxy</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
<!-- ### Servlet Mappings -->
<servlet-mapping>
<servlet-name>JNDIFactory</servlet-name>
<url-pattern>/restricted/JNDIFactory/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>JMXInvokerServlet</servlet-name>
<url-pattern>/restricted/JMXInvokerServlet/*</url-pattern>
</servlet-mapping> <security-constraint>
<web-resource-collection>
<web-resource-name>HttpInvokers</web-resource-name>
<description>An example security config that only allows users with
the role HttpInvoker to access the HTTP invoker servlets
</description>
<url-pattern>/restricted/*</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>HttpInvoker</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>JBoss HTTP Invoker</realm-name>
</login-config> <security-role>
<role-name>HttpInvoker</role-name>
</security-role>
</web-app>
The web.xml descriptor only defines which servlets are secured and which roles are allowed to access the secured servlets. You must additionally define the security domain that will handle the authentication and authorization for the WAR. You do this through the jboss-web.xml descriptor. The following example uses the http-invoker security domain:
<jboss-web> <security-domain>java:/jaas/http-invoker</security-domain> </jboss-web>
The security-domain element defines the name of the security domain that will be used for the JAAS login module configuration used for authentication and authorization.
See Chapter 8, "Security on JBoss," for additional details on the meaning and configuration of the security domain name.
Securing Access to JNDI with a Read-only Unsecured Context
Another feature that is available for the JNDI/HTTP naming service is the ability to define a context that can be accessed by unauthenticated users in read-only mode. This can be important for services used by the authentication layer. For example, the SRPLoginModule needs to look up the SRP server interface used to perform authentication. Let’s now walk through how read-only JNDI works in JBoss.
First, the ReadOnlyJNDIFactory is declared in invoker.sar/WEB-INF/web.xml. It will be mapped to /invoker/ReadOnlyJNDIFactory:
<servlet>
<servlet-name>ReadOnlyJNDIFactory</servlet-name>
<description>A servlet that exposes the JBoss JNDI Naming service stub
through http, but only for a single read-only context. The return content
is serialized MarshalledValue containing the org.jnp.interfaces.Naming
stub.
</description>
<servlet-class>org.jboss.invocation.http.servlet.NamingFactoryServlet
</servlet-class>
<init-param>
<param-name>namingProxyMBean</param-name>
<param-value>jboss:service=invoker,type=http,target=Naming,readonly=true</param-value>
</init-param>
<init-param>
<param-name>proxyAttribute</param-name>
<param-value>Proxy</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
<!-- ... -->
<servlet-mapping>
<servlet-name>ReadOnlyJNDIFactory</servlet-name>
<url-pattern>/ReadOnlyJNDIFactory/*</url-pattern>
</servlet-mapping>
The factory only provides a JNDI stub which needs to be connected to an invoker. Here the invoker is jboss:service=invoker,type=http,target=Naming,readonly=true. This invoker is declared in the http-invoker.sar/META-INF/jboss-service.xml file:
<mbean code="org.jboss.invocation.http.server.HttpProxyFactory"
name="jboss:service=invoker,type=http,target=Naming,readonly=true">
<attribute name="InvokerName">jboss:service=Naming</attribute>
<attribute name="InvokerURLPrefix">http://</attribute>
<attribute name="InvokerURLSuffix">:8080/invoker/readonly/JMXInvokerServlet
</attribute>
<attribute name="UseHostName">true</attribute>
<attribute name="ExportedInterface">org.jnp.interfaces.Naming</attribute>
<attribute name="JndiName"></attribute>
<attribute name="ClientInterceptors">
<interceptors>
<interceptor>org.jboss.proxy.ClientMethodInterceptor</interceptor>
<interceptor>org.jboss.proxy.SecurityInterceptor</interceptor>
<interceptor>org.jboss.naming.interceptors.ExceptionInterceptor
</interceptor>
<interceptor>org.jboss.invocation.InvokerInterceptor</interceptor>
</interceptors>
</attribute>
</mbean>
The proxy on the client side needs to talk back to a specific invoker servlet on the server side. The configuration here has the actual invocations going to /invoker/readonly/JMXInvokerServlet. This is actually the standard JMXInvokerServlet with a read-only filter attached:
<filter>
<filter-name>ReadOnlyAccessFilter</filter-name>
<filter-class>org.jboss.invocation.http.servlet.ReadOnlyAccessFilter
</filter-class>
<init-param>
<param-name>readOnlyContext</param-name>
<param-value>readonly</param-value>
<description>The top level JNDI context the filter will enforce
read-only access on. If specified only Context.lookup operations
will be allowed on this context. Other operations or
lookups on any other context will fail. Do not associate this
filter with the JMXInvokerServlets if you want unrestricted
access. </description>
</init-param>
<init-param>
<param-name>invokerName</param-name>
<param-value>jboss:service=Naming</param-value>
<description>The JMX ObjectName of the naming service mbean
</description>
</init-param>
</filter>
<filter-mapping>
<filter-name>ReadOnlyAccessFilter</filter-name>
<url-pattern>/readonly/*</url-pattern>
</filter-mapping>
<!-- ... -->
<!-- A mapping for the JMXInvokerServlet that only allows invocations
of lookups under a read-only context. This is enforced by the
ReadOnlyAccessFilter
-->
<servlet-mapping>
<servlet-name>JMXInvokerServlet</servlet-name>
<url-pattern>/readonly/JMXInvokerServlet/*</url-pattern>
</servlet-mapping>
The readOnlyContext parameter is set to readonly, which means that when you access JBoss through the ReadOnlyJNDIFactory, you will only be able to access data in the readonly context. Here is a code fragment that illustrates the usage:
Properties env = new Properties();
env.setProperty(Context.INITIAL_CONTEXT_FACTORY,
"org.jboss.naming.HttpNamingContextFactory");
env.setProperty(Context.PROVIDER_URL,
"http://localhost:8080/invoker/ReadOnlyJNDIFactory");
Context ctx2 = new InitialContext(env);
Object data = ctx2.lookup("readonly/data");
Attempts to look up any objects outside the readonly context will fail. Note that JBoss doesn't ship with any data in the readonly context, so the readonly context won't be bound usable unless you create it.
Additional Naming MBeans
In addition to the NamingService MBean that configures an embedded JBossNS server within JBoss, there are three other MBean services related to naming that ship with JBoss: ExternalContext, NamingAlias, and JNDIView.
The org.jboss.naming.ExternalContext MBean
The ExternalContext MBean allows you to federate external JNDI contexts into the JBoss server JNDI namespace. The term external refers to any naming service external to the JBossNS naming service running inside the JBoss server VM. You can incorporate LDAP servers, file systems, DNS servers, and so on, even if the JNDI provider root context is not serializable. The federation can be made available to remote clients if the naming service supports remote access.
To incorporate an external JNDI naming service, you have to add a configuration of the ExternalContext MBean service to the jboss-service.xml configuration file. The configurable attributes of the ExternalContext service are as follows:
-
JndiName—The JNDI name under which the external context is to be bound.
-
RemoteAccess—A Boolean flag that indicates whether the external InitialContext should be bound using a Serializable form that allows a remote client to create the external InitialContext. When a remote client looks up the external context via the JBoss JNDI InitialContext, the client effectively creates an instance of the external InitialContext, using the same env properties passed to the ExternalContext MBean. This works only if the client can do a new InitialContext (env) remotely. This requires that the Context.PROVIDER_URL value of env be resolvable in the remote VM that is accessing the context. This should work for the LDAP example. For the file system example, this most likely won't work unless the file system path refers to a common network path. If this property is not given, it defaults to false.
-
CacheContext—The cacheContext flag. When it is set to true, the external context is created only when the MBean is started, and then it is stored as an in-memory object until the MBean is stopped. If cacheContext is set to false, the external Context is created on each lookup, using the MBean properties and InitialContext class. When a client looks up the uncached context, the client should invoke close() on the context to prevent resource leaks.
-
InitialContext—The fully qualified classname of the InitialContext implementation to use. It must be one of these: javax.naming.InitialContext, javax.naming.directory.InitialDirContext, or javax.naming.ldap.InitialLdapContext. In the case of InitialLdapContext, a null Controls array is used. The default is javax.naming.InitialContext.
-
Properties—The JNDI properties for the external InitialContext. The input should be the text equivalent of what would go into a jndi.properties file.
-
PropertiesURL—The jndi.properties information for the external InitialContext from an external properties file. This is either a URL, a string, or a classpath resource name. The following are some examples:
file:///config/myldap.properties
http://config.mycompany.com/myldap.properties
/conf/myldap.properties
myldap.properties
The following MBean definition shows a binding to an external LDAP context into the JBoss JNDI namespace under the name external/ldap/jboss:
<!-- Bind a remote LDAP server -->
<mbean code="org.jboss.naming.ExternalContext"
name="jboss.jndi:service=ExternalContext,jndiName=external/ldap/jboss">
<attribute name="JndiName">external/ldap/jboss</attribute>
<attribute name="Properties">
java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
java.naming.provider.url=ldap://ldaphost.jboss.org:389/o=jboss.org
java.naming.security.principal=cn=Directory Manager
java.naming.security.authentication=simple
java.naming.security.credentials=secret
</attribute>
<attribute name="InitialContext"> javax.naming.ldap.InitialLdapContext </attribute>
<attribute name="RemoteAccess">true</attribute>
</mbean>
With this configuration, you can access the external LDAP context located at ldap://ldaphost.jboss.org:389/o=jboss.org from within the JBoss VM by using the following code fragment:
InitialContext iniCtx = new InitialContext();
LdapContext ldapCtx = iniCtx.lookup("external/ldap/jboss");
Using the same code fragment outside the JBoss server VM would work in this case because the RemoteAccess property is set to true. If it were set to false, it would not work because the remote client would receive a Reference object with an ObjectFactory that would not be able to re-create the external InitialContext:
<!-- Bind the /usr/local file system directory -->
<mbean code="org.jboss.naming.ExternalContext"
name="jboss.jndi:service=ExternalContext,jndiName=external/fs/usr/local">
<attribute name="JndiName">external/fs/usr/local</attribute>
<attribute name="Properties">
java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory
java.naming.provider.url=file:///usr/local
</attribute>
<attribute name="InitialContext">javax.naming.InitialContext</attribute>
</mbean>
This configuration describes binding a local file system directory /usr/local into the JBoss JNDI namespace under the name external/fs/usr/local.
With this configuration, you can access the external file system context located at the file ///usr/local from within the JBoss VM, using the following code fragment:
InitialContext iniCtx = new InitialContext();
Context ldapCtx = iniCtx.lookup("external/fs/usr/local");
Note that this code uses one of the Sun JNDI service providers, which must be downloaded from http://java.sun.com/products/jndi/serviceproviders.html. The provider JARs should be placed in the server configuration lib directory.
The org.jboss.naming.NamingAlias MBean
The NamingAlias MBean is a simple utility service that allows you to create an alias in the form of a JNDI javax.naming.LinkRef from one JNDI name to another. This is similar to a symbolic link in the Unix file system. To an alias you add a configuration of the NamingAlias MBean to the jboss-service.xml configuration file.
The configurable attributes of the NamingAlias service are as follows:
-
FromName—The location where the LinkRef is bound under JNDI.
-
ToName—The to name of the alias. This is the target name to which the LinkRef refers. The name is a URL, or a name to be resolved relative to the InitialContext; or if the first character of the name is a dot (.), the name is relative to the context in which the link is bound.
The following example provides a mapping of the JNDI name QueueConnectionFactory to the name ConnectionFactory:
<mbean code="org.jboss.naming.NamingAlias"
name="jboss.mq:service=NamingAlias,fromName=QueueConnectionFactory">
<attribute name="ToName">ConnectionFactory</attribute>
<attribute name="FromName">QueueConnectionFactory</attribute>
</mbean>
The org.jboss.naming.JNDIView MBean
The JNDIView MBean allows the user to view the JNDI namespace tree as it exists in the JBoss server, using the JMX agent view interface. To view the JBoss JNDI namespace using the JNDIView MBean, you connect to the JMX Agent view, using the HTTP interface. The default settings put this at http://localhost:8080/jmx-console/. On this page you see a section that lists the registered MBeans, sorted by domain. It should look something like what is shown in Figure 3.4.
Selecting the JNDIView link takes you to the JNDIView MBean view, which shows a list of the JNDIView MBean operations. This view should look similar to the one shown in Figure 3.5.
)
Figure 3.4 The JMX Console view of the configured JBoss MBeans.
)
Figure 3.5 The JMX Console view of the JNDIView MBean.
The list operation dumps out the JBoss server JNDI namespace as an HTML page, using a simple text view. For example, invoking the list operation produces the view shown in Figure 3.6.
)
Figure 3.6 The JMX Console view of the JNDIView list operation output.