The JNDI Service Provider Interface

The JNDI architecture supports pluggable modules referred to as Service Provider Interfaces ( SPIs ), as illustrated earlier in Figure 14.1. They are responsible for implementing the client-side protocol for a specific naming service. JNDI provides a common API to the client independent of the selected SPI.

The Java application chooses which JNDI SPI it wants to use through the javax.naming.Context interface. Each SPI implements an InitialContextFactory that creates an instance of an object that implements the Context interface. The context factory is responsible for creating an instance of a JNDI Context for its particular protocol. A hash table is passed to the InitialContextFactory that contains properties used to customize the SPI. This hash table is referred to as the JNDI context environment. The javax.naming.Context interface defines constants that are used as the key value of the hash table, as listed in Table 14.1.

Table 14.1. The Context Environment Defines Property Names for Configuring the Hashtable

Property	Comment
Context.INITIAL_CONTEXT_FACTORY	Specifies the class name that is being used for the SPI context factory.
Context.PROVIDER_URL	Specifies the URL of the service provider. The format of the URL is protocol://hostname:port
Context.SECURITY_AUTHENTICATION	Specifies the security level to use. It may be set to one of "none", "simple", or "strong". If the level is unspecified, the behavior is set by the SPI.
Context.SECURITY_PRINCIPAL	Specifies the name of the user who has authentication privileges on the server.
Context.SECURITY_CREDENTIALS	Specifies the password for the user specified by the SECURITY_PRINCIPAL property. This property may also be used to pass an object that implements secure user information that is service provider specific.

Note

The WebLogic JNDI allows the SECURITY_CREDENTIAL to be passed as an object that implements the weblogic.security.acl.UserInfo interface which is the weblogic.security.acl.DefaultUserInfoImpl class. However, this has been deprecated by the WebLogic 7.0 rules-based LDAP Authentication Provider in the Pluggable Security Infrastructure. The recommended security is provided by the Java Authentication and Authorizaton Service (JAAS). Refer to the "LDAP Security Considerations" later in this chapter for further information.

Examples of using the LDAP, RMI, COS, and WebLogic SPIs are discussed in the following sections.

Using the LDAP SPI

The InitialContextFactory class for the LDAP SPI is com.sun.jndi.ldap.LdapCtxFactory . The PROVIDER_URL is constructed with a protocol , hostname , and port . The protocol is ldap , and the hostname is the name of the host where the LDAP server is running. If the LDAP server is running on the same system as the Java application, you can use localhost as the hostname. The default port for LDAP is 389, but the LDAP server may be running on another port. A sample PROVIDER_URL for LDAP is

 ldap://localhost:389 

The example in Listing 14.2 creates a javax.naming.Context for the LDAP SPI. The context environment specifies com.sun.jndi.ldap.LdapCtxFactory as the InitialContextFactory . The PROVIDER_URL defines the hostname and port of the LDAP server. The SECURITY_AUTHENTICATION , SECURITY_PRINCIPAL , and SECURITY_CREDENTIALS are used to authorize access to the root distinguished node of the LDAP database.

Note

See the next section, "LDAP Security Considerations," for further information on LDAP security.

Listing 14.2 The JNDI SPI Is Configured Through the LdapCtxFactory for LDAP

 /** Create JNDI Context for LDAP @param rootDN LDAP root distinguished name @param rootPW LDAP root password @returns JNDI Context @exception NamingException */ private Context createLdapContext( String rootDN, String rootPW ) throws NamingException { Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory" ); env.put( Context.PROVIDER_URL, "ldap://localhost:389" ); env.put( Context.SECURITY_AUTHENTICATION, "simple" ); env.put( Context.SECURITY_PRINCIPAL, rootDN ); env.put( Context.SECURITY_CREDENTIALS, rootPW ); Context ctx = new InitialContext( env ); return ctx; } 

LDAP Security Considerations

LDAP security properties are determined by the configuration of the LDAP server. Typically, no security credentials are required for lookup or search operations. To protect the contents of the LDAP server, security is enforced for bind, rebind, and unbind operations. If the LDAP server is configured with simple clear-text passwords, set the SECURITY_PRINCIPAL to the root-distinguished name, and set the SECURITY_CREDENTIALS to the root password. Listing 14.2 provided an example using the root distinguished name with a root password.

In addition to simple text passwords, the WebLogic server provides the capability to configure an LDAP Authentication Provider containing users and groups. This is configured through the Security Realms on the WebLogic Administrator Console. From the configuration of a security realm, the LDAP Authentication Provider is selected and configured. The WebLogic LDAP Authentication provides a fully compatible Java Authentication and Authorization Service (JAAS). A working JAAS sample is provided with the WebLogic Server software. The sample is located in the SAMPLES_HOME\server\src\examples\security\jaas directory provided with WebLogic Server.

For further information on security see Chapter 26, "Managing the WebLogic Security Service," p. 889 .

Using the RMI SPI

The InitialContextFactory class for the RMI SPI is com.sun.jndi.rmi.registry.RegistryContextFactory . The PROVIDER_URL is constructed with a protocol , hostname , and port . The protocol is rmi , and the hostname is the name of the host where the rmiregistry is running. If the rmiregistry is running on the same system as the Java application, you can use localhost as the hostname. The default port for RMI is 1099, but the rmiregistry may be running on another port. A sample PROVIDER_URL for RMI is

 rmi://localhost:1099 

The example in Listing 14.3 creates a javax.naming.Context for the RMI SPI. The context environment specifies com.sun.jndi.rmi_registry.RegistryContextFactory as the InitialContextFactory . The PROVIDER_URL defines the hostname and port of the RMI server. The context environment for RMI requires the RMISecurityManager to be specified.

Note

Refer to the next section, "RMI Security Considerations" for further information on RMI security.

Listing 14.3 JNDI Context for RMI

 /** Create JNDI Context for RMI @returns JNDI Context @exception NamingException */ private Context createRmiContext() throws NamingException { Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.rmi.registry.RegistryContextFactory" ); env.put( Context.PROVIDER_URL, "rmi://localhost:1099" ); env.put( "java.naming.rmi.security.manager", "RMISecurityManager" ); Context ctx = new InitialContext( env ); return ctx; } 

RMI Security Considerations

RMI requires that you install a security manager to load objects from a remote server. The RMI SPI uses the java.naming.rmi.security.manager property to indicate that it should attempt to install the RMISecurityManager . This property can be set to any value to request that the security manager be installed.

Using the COS SPI

The InitialContextFactory class for the COS SPI is com.sun.jndi.cosnaming.CNCtxFactory . The PROVIDER_URL for the Common Object Services is slightly more complex than the other Service Provider Interfaces. The URL is constructed with a protocol , hostname , port , and the name of the CosNaming service. For COS, the URL is used to configure the root-naming context and/or the Object Request Broker (ORB). The protocol can be either iiop or iiopname . The iiop protocol specifies a single hostname, and the iiopname protocol specifies an addr_list , which is a list of hostnames. The default port for iiop is 900, and the default port for iiopname is 9999. Examples of the two forms for the PROVIDER_URL are:

 iiop://localhost:900/<cosnaming_name> iiopname://<addr_list>:9999/<cosnaming_name> 

The example in Listing 14.4 creates a javax.naming.Context for the COS SPI. The context environment specifies com.sun.jndi.cosnaming.CNContextFactory as the InitialContextFactory . The PROVIDER_URL defines the hostname and port of the CosNaming service. The COS SPI does not specify SECURITY_CREDENTIALS as it uses the Java Security Manager.

Note

Refer to the next section "COS Security Considerations" for further information on COS security.

Listing 14.4 JNDI Context for COS

 /** Create JNDI Context for COS @returns JNDI Context @exception NamingException */ private Context createCosContext() throws NamingException { Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.cosnaming.CNCtxFactory" ); env.put( Context.PROVIDER_URL, "iiop://localhost:900" ); Context ctx = new InitialContext( env ); return ctx; } 

COS Security Considerations

COS security is monitored by the installed security manager. This chapter specifically focuses on JNDI; details of the Java Security Manager are not covered in this chapter. However, as a brief overview, when a security manager has been installed, you must grant to the application using JNDI and the COS naming service provider the following permissions:

 permission java.net.SocketPermission "host[:port]", "connect"; 

To grant permissions with the Java Security Manager, you add the permission entry to the file being administered by the java.security.policy property.

Using the WebLogic SPI

The InitialContextFactory class for the WebLogic SPI is weblogic.jndi.WLInitialContextFactory . The URL is constructed with a protocol , hostname , and port . The protocol is t3 , and the hostname is the name of the host where WebLogic Server is running. If WebLogic Server is running on the same system as the Java application, you can use localhost as the hostname. The default port for the WebLogic name service is 7001, but it may be running on another port. A sample PROVIDER_URL for the WebLogic name service is

 t3://localhost:7001 

WebLogic Security Considerations

WebLogic security properties are determined by the WebLogic Server security realm. The SECURITY_PRINCIPAL property is used to specify a user for authentication purposes. The default user is "guest" . The SECURITY_CREDENTIALS property is overloaded; the value can be either the password for the user or an object that implements the weblogic.security.acl.UserInfo interface. If a UserInfo object is passed, the PROVIDER_URL property is ignored.

Creating the Context Environment for WebLogic

The WebLogic SPI provides both the traditional context environment configuration using a Hashtable , as well as the WebLogic Environment class. The Environment class offers the convenience of a Java Bean API using set methods to configure the properties. This mechanism provides compile-time type checking of the parameters that cannot be done by the Hashtable . The default constructor for the Environment class initializes a set of default values. Table 14.2 shows the attributes of the Environment class with the corresponding default value. You do not need to set a value if the default matches your needs.

Table 14.2. The Environment Class Attributes That Control the Configuration of the Context Environment

Environment Attribute	Default Value
InitialContextFactory	WLInitialContextFactory
ProviderURL	"t3://localhost:7001"
SecurityPrincipal	"guest"
SecurityCredentials	"guest_password"

The example in Listing 14.5 shows the traditional Hashtable implementation. Listing 14.6 shows an example using the WebLogic Environment class to configure the context. Both examples perform identical initialization of the JNDI Context.

Listing 14.5 JNDI Context for WebLogic: Traditional Hashtable Implementation

 /** Create JNDI Context for WebLogic @param user User in WebLogic Server security realm @param password Password for user @returns JNDI Context @exception NamingException */ private Context createWebLogicContext( String user, String password ) { Hashtable env = new Hashtable(); env.put(Context.INITIAL_CONTEXT_FACTORY, "weblogic.jndi.WLInitialContextFactory" ); env.put( Context.PROVIDER_URL, "t3://localhost:7001" ); env.put( Context.SECURITY_AUTHENTICATION, "simple" ); env.put( Context.SECURITY_PRINCIPAL, user ); env.put( Context.SECURITY_CREDENTIALS, password ); Context ctx = new InitialContext( env ); return ctx; } 

Listing 14.6 JNDI Context for WebLogic: Using the Environment Object

 /** Create JNDI Context for WebLogic @param user User in WebLogic Server security realm @param password Password for user @returns JNDI Context @exception NamingException */ private Context createWebLogicContext( String user, String password ) { try { // Create the WebLogic Environment // use default value: WLInitialContextFactory, "t3://localhost:7001, Environment env = new Environment(); env.setSecurityPrincipal( user ); env.setSecurityCredentials( password ); // in this case, we get the InitialContext from the Environment object Context ctx = env.getInitialContext(); // use ctx to lookup JNDI services } catch( NamingException x ) { System.err.println( x.toString() ); } }