Writing a WebLogic Enterprise Enterprise JavaBean That Implements Security

 

This topic includes the following sections:

• Before You Begin

• How Authentication Works with WebLogic Enterprise EJBs

• Development Steps

• Step 1: Define Security Roles for the Methods of the WebLogic Enterprise EJB

• Step 2: Specify Security Roles in the Deployment Descriptor of the EJB

• Step 3: Define the JNDI Environment Properties

• Step 4: Establish the InitialContext

• Step 5: Use Home to Get a WebLogic Enterprise EJB

• Step 6: Use the getCallerPrincipal Method to Authenticate a WebLogic Enterprise EJB

 

---

Before You Begin

This topic describes the BEA implementation of the Security feature. The information in this topic supplements the Sun Microsystems, Inc. Enterprise JavaBeans Specification 1.1.

Note: Before proceeding with the remainder of this topic, you should be familiar with the entire content of Sun's specification, particularly Chapter 15, "Security Management."

This topic describes only the integrating security into WebLogic Enterprise EJBs. For a complete description of developing an EJB using the WebLogic Enterprise product, see Getting Started in the WebLogic Enterprise online documentation.

Note: An EJB in the WebLogic Enterprise domain that issues a callback to a remote J2EE client application cannot propagate the security context of that client application in the callback.

 

---

How Authentication Works with WebLogic Enterprise EJBs

From the perspective of an EJB container, EJBs are nontrusted entities that require authentication. The WebLogic Enterprise product uses a JNDI implementation that runs within the EJB container's trusted environment. Using the WLEInitialContextFactory JNDI factory with security environment properties establishes the security context for the WebLogic Enterprise client application. The WebLogic Enterprise client application authenticates itself with the WebLogic Enterprise domain when establishing the JNDI Initial context.

 

---

Development Steps

Table 12-1 lists the development steps required to implement security in a WebLogic Enterprise EJB.

Table 12-1 Development Steps for Implementing Security in a WebLogic Enterprise EJB

Step	Description
1	Define security roles for the methods of the WebLogic Enterprise EJB.
2	Specify security roles in the Deployment Descriptor of the EJB.
3	Define the JNDI environment properties.
4	Establish the InitialContext.
5	Use Home to get the WebLogic Enterprise EJB.
6	Use the getCallerPrincipal method to authenticate the WebLogic Enterprise EJB.

Step 1: Define Security Roles for the Methods of the WebLogic Enterprise EJB

During the assembly and deployment of an EJB package, you define security roles and associate roles with methods in the deployment descriptor. Security roles are mapped to groups of users in the WebLogic Enterprise security environment. You can use any of the techniques described in the Security Management chapter of the Enterprise JavaBeans 1.1 Specification to define security roles for the methods of a WebLogic Enterprise EJB.

It is possible that two methods with the same name or name/signature appear in both the bean's home and remote interfaces. To handle this case, the optional <method-intf> element may further restrict the selection to either Home or Remote interface methods.

In a mandatory access control environment, any method invocation not specifically authorized is denied. Sometimes a method does not have a defined <method-permission> element. If the SECURITY parameter in the RESOURCES section of the UBBCONFIG file is set to MANDATORY_ACL access on a method without an associated <method-permission> element, access is denied. This is the recommended setting for production environments. For all other settings of the SECURITY parameter, access to a method without an associated <method-permission> element is allowed.

There may be methods that should be available to everyone, even in a mandatory access control environment. The WebLogic Enterprise system defines a special role name * which means everyone has access to the method.

Note: ACL is the only WebLogic Enterprise security level that gives the expected EJB behavior. The MANDATORY_ACL security level rejects user access on a method when no <method-permission> element is defined for the specified method. The USER_AUTH security level fails requests on methods with a <method-permission> element defined because that level of security Other.

Table 12-2 describes different combinations of the WebLogic Enterprise security levels (as defined by the SECURITY parameter in the UBBCONFIG file) and the definition of <method-permission> element on an EJB.

• Yes indicates access to the method is granted.

• No means acces to the method is not granted.

• Check indicates access to the method is granted if a role is defined in the ejb-jar.xml file. Otherwise, access to the method is denied.

  Table 12-2 Combinations of WebLogic Enterprise Security Levels and EJB <method-permissions>

  Setting for WebLogic Enterprise Security Level	Setting for <method-permission> element	Is the method accessible?
  None	No	Yes
  	Yes	No
  APP_PW	No	Yes
  	Yes	No
  USER_AUTH	No	Yes
  	Yes	Yes, if the role name of the method is other
  ACL	No	Yes
  	Yes	Check
  MANDATORY_ACL	No	No
  	Yes	Check

Step 2: Specify Security Roles in the Deployment Descriptor of the EJB

You specify security roles for the methods of an EJB in the deployment descriptor of the bean. In the WebLogic Enterprise product, there is a one-to-one association between the security roles defined in the deployment descriptor of the EJB and the groups defined with the tpgrpadd commands. Role names may be referenced in deployment descriptors before the corresponding group exists. At run time, if a bean's deployment descriptor references a role that does not have a corresponding group, the role is ignored.

Role names are restricted to any alphanumeric characters, a dash (-), an underscore
( _), the at-sign (@), and a period ( .). The maximum length of a role name is 30 characters. If the name of a security role does not conform to these limitations, it will not be possible for users to have the defined security role.

Listing 12-1 includes code that defines a security role.

Listing 12-1 Defining a Security Role for a Method in an EJB

---

...
<assembly-descriptor>
   <security-role>
     <description>
       "teller" is a role name
     </description>
   </security-role>

	<method-permission>
         <role-name>teller</role-name>
	  <method>
		<ejb-name>Accounting</ejb-name>
		<method-name>withdraw</methodname>
	  </method>
		...
	</method-permission>
	...
</assembly-descriptor>
...

Step 3: Define the JNDI Environment Properties

The following sections describe the JNDI environment properties that must be set to enable either Username/Password or certificate-based authentication.

WLEContext.INITIAL_CONTEXT_FACTORY Property

The class com.beasys.jndi.WLEInitialContextFactory is the JNDI Service Provider Interface (SPI). This initial context provides an entry point into the WebLogic Enterprise domain. Set WLEContext.INITIAL_CONTEXT_FACTORY to com.beasys.jndi.WLEInitialContextFactory to access the WebLogic Enterprise domain.

Listing 12-2 includes code that defines the WLEContext.INITIAL_CONTEXT_FACTORY property for the WebLogic Enterprise environment.

Listing 12-2 WLEContext.INITIAL_CONTEXT_FACTORY Property

---

Hashtable env = new Hashtable();
/*
*Specify the initial context implementation to use.
*The service provider supplies the factory class.
*/
env.put(WLEContext.INITIAL_CONTEXT_FACTORY,
        "com.beasys.jndi.WLEInitialContextFactory");
...

WLEContext.PROVIDER_URL Property

Specifies the entry point into the WebLogic Enterprise domain. The value should reflect the host and port of the IIOP Listener/Handler of the target WebLogic Enterprise domain. Use one of the following URL address formats when specifying the location of the IIOP Listener/Handler:

• corbaloc://hostname:portnumber

  Indicates that the IIOP/RMI protocol is to be used to communicate with the WebLogic Enterprise domain. This URL address format only supports Username/Password authentication.

• corbalocs://hostname:portnumber

  Indicates that the SSL protocol is to be used to communicate with the WebLogic Enterprise domain. This URL address format supports both Username/Password and certificate-based authentication.

The host and port combination in the URL must match the ISL parameter in the WebLogic Enterprise application's UBBCONFIG file. The format of the host and port combination as well as the capitalization must match. If the addresses do not match, communication with the WebLogic Enterprise domain fails.

Listing 12-3 includes code that defines the WLEContext.PROVIDER_URL property for the WebLogic Enterprise environment.

Listing 12-3 WLEContext.PROPERTY_URL Property

---

...

env.put(WLEContext.PROVIDER_URL,
         "corbaloc://"myhost:1000");

...

A WebLogic Enterprise server application that acts as a client application (referred to as a joint client/server application) must set the WLEContext.PROPERTY_URL as an empty or null string. The joint client/server application connects to the current application in which it was booted.

WLEContext.SECURITY_AUTHENTICATION Property

Set this property to indicate the type of authentication to be used. The valid values for this property are as follows:

• None-indicates that no authentication is performed

• Simple-indicates that Username/Password authentication is performed

• Strong-indicates that certificate-based authentication is performed

See Table 12-3 for additional keys that need to be specified to use Username/Password or certificate-based authentication.

Listing 12-4 includes code that defines the WLEContext.SECURITY_AUTHENTICATION property for the WebLogic Enterprise environment.

Listing 12-4 WLEContext.SECURITY_AUTHENTICATION Property

---

...

env.put(WLEContext.SECURITY_AUTHENTICATION, "strong");

...

Table 12-3 WebLogic Enterprise Property Keys for Security

Property Key	Meaning
WLEContext.SECURITY_PRINCIPAL	Specifies the identity of the principal used when authenticating the caller to the WebLogic Enterprise domain.
WLEContext.SECURITY_CREDENTIALS	Specifies the credentials of the principal when authenticating the caller to the WebLogic Enterprise domain. For certificate-based authentication enabled via SECURITY_AUTHENTICATION="strong", it specifies the pass phrase used to access the private key and certificate for the EJB. For password-based authentication enabled via SECURITY_AUTHENTICATION="simple", it specifies a string that is the user's password or an arbitrary object user_data used by the authentication server (AUTHSVR) to verify the credentials of the EJB.
WLEContext.CLIENT_NAME	Specifies the name of the EJB defined by the -c option of the tpusradd command. For more information, see "Defining Authorized Users" on page 7-3.
WLEContext.SYSTEM_PASSWORD	The system password. Required only when using Username/Password authentication.

Listing 12-5 includes the WebLogic Enterprise keys used to define Username/Password authentication.

Listing 12-5 WebLogic Enterprise Keys for Username/Password Authentication

---

...
   Hashtable env = new Hashtable();
   env.put(Context.PROVIDER_URL, "corbalocs://"myhost:1000")

env.put(Context.INITIAL_CONTEXT_FACTORY,
                  "com.beasys.jndi.WLEInitialContextFactory");

//Password-Based Authentication 
env.put(WLEContext.SECURITY_PRINCIPAL, "milozzi");
env.put(WLEContext.SYSTEM_CREDENTIALS, "mypassword");
env.put(WLEContext.CLIENT_NAME, "writers");
env.put(WLEContext.SECURITY_AUTHENTICATION, "simple");
env.put(WLEContext.SYSTEM_PASSWORD, "password");
...

Listing 12-6 includes the WebLogic Enterprise keys used to define certificate-based authentication.

Listing 12-6 WebLogic Enterprise Keys for Certificate-based Authentication

---

...
//Certificate-Based Authentication 
env.put(WLEContext.SECURITY_AUTHENTICATION, "strong");
env.put(WLEContext.SYSTEM_PASSWORD, "SSL");
env.put(WLEContext.SECURITY_PRINCIPAL, "milozzi");
env.put(WLEContext.SECURITY_CREDENTIALS, "credentials");
...

Step 4: Establish the InitialContext

To access a WebLogic Enterprise EJB using JNDI, you establish an InitialContext using the following code:

Context ctx = new InitialContext(env);

Specifying env as com.beasys.com.jndi.WLEInitialContextFactory. After the context is created, the client application has access to bean homes in the WebLogic Enterprise domain using WebLogic Enterprise as the name service provider.

A WebLogic Enterprise EJB is implicitly associated with the security context specified when the WLEContext object is created. To specify a new security context, the EJB needs to close the current security context and establish a new security context with new security attributes. Use the following code to close the current security context:

ctx.close();

Step 5: Use Home to Get a WebLogic Enterprise EJB

Client applications use the bean's home interface to create or find beans. The beans's home is obtained by using the lookup method on the InitialContext.

Step 6: Use the getCallerPrincipal Method to Authenticate a WebLogic Enterprise EJB

Use the getCallerPrincipal method on the javax.ejb.EJBContext associated with a WebLogic Enterprise EJB to authenticate the principal. You can also use the isCallerInRole method to determine the role of the client application invoking methods on the EJB. The default principal is IIOP Client.

 

---

Limitations and Restrictions

It is possible to deploy the same EJB more than once with different deployment descriptors that set different access control policies. In this case access control is based on the deployment descriptor from which a particular bean is loaded. Security policies are not considered when the WebLogic Enterprise system has a choice of how to route a request to any particular bean or container.

 

---

Example of Using Security in a WebLogic Enterprise EJB

Listing 12-7 illustrates using Username/Password authentication in a WebLogic Enterprise EJB.

Note: The code example in Listing 12-7 uses the corbalocs URL address format so that the SSL protocol is used to protect the integrity of the communications.

Listing 12-7 Username/Password Authentication in a WebLogic Enterprise EJB

---

static public Context getInitialContext() throws Exception {
  Hashtable env = new Hashtable ();
  env.put(WLEContext.INITIAL_CONTEXT_FACTORY,
           "com.beasys.jndi.WLEInitialContextFactory");

  env.put(WLEContext.PROVIDER_URL, corbalocs://myhost:7002);

return new InitialContext(env);

  //Password-Based Authentication 
env.put(WLEContext.SECURITY_AUTHENTICATION, "simple");
env.put(WLEContext.SYSTEM_PASSWORD, "RMI");
env.put(WLEContext.SECURITY_PRINCIPAL, "milozzi);
env.put(WLEContext.CLIENT_NAME, "writers);
env.put(WLEContext.SECURITY_CREDENTIALS, "password");

Listing 12-8 illustrates using certificate-based authentication in a WebLogic Enterprise EJB.

Listing 12-8 Certificate-based Authentication in a WebLogic Enterprise EJB

---

...
  Hashtable env = new Hashtable ();
  env.put(WLEContext.INITIAL_CONTEXT_FACTORY,
           "com.beasys.jndi.WLEInitialContextFactory");

  env.put(WLEContext.PROVIDER_URL, corbalocs://myhost:7002);

return new InitialContext(env);

//Certificate-Based Authentication 
env.put(WLEContext.SECURITY_AUTHENTICATION, "strong");
env.put(WLEContext.SECURITY_PRINCIPAL, "[e-mail]");
env.put(WLEContext.CLIENT_NAME, "writers);
env.put(WLEContext.SYSTEM_PASSWORD, "SSL");
env.put(WLEContext.SECURITY_CREDENTIALS, "credentials");