PK
+Hoa, mimetypeapplication/epub+zipPK +H META-INF/container.xml
This chapter describes how to establish and configure the specific set of JMX services that are to be available within a WebLogic Server domain. For example, in a production environment you can disable the WebLogic Server editing service and therefore prevent most run-time changes to the domain.
This chapter includes the following sections:
Within a WebLogic domain, you can specify which JMX services are available.
The following attributes of JMXMBean
determine which JMX services are available in a domain (see "JMXMBean" in MBean Reference for Oracle WebLogic Server):
EditMBeanServerEnabled
controls whether JMX clients, including utilities such as the WebLogic Server Administration Console and the WebLogic Scripting Tool, can modify a domain's configuration.
DomainMBeanServerEnabled
controls whether JMX clients can access all run-time MBeans and read-only configuration MBeans through a single connection to the Domain Runtime MBean Server.
RuntimeMBeanServerEnabled
controls whether JMX clients can access a specific server's run-time MBeans and read-only configuration MBeans through the server's Runtime MBean Server.
PlatformMBeanServerEnabled
controls whether all WebLogic Server instances initialize the JDK platform MBean server. PlatformMBeanServerUsed
controls whether all WebLogic server instances start their Runtime MBean Servers as the JDK platform MBean server. This makes it possible to access WebLogic Server MBeans and the JVM platform MBeans from a single MBean server.
CompatibilityMBeanServerEnabled
enables JMX clients to use the deprecated weblogic.management.MBeanHome
interface to access WebLogic Server MBeans.
ManagementEJBEnabled
controls whether the current WebLogic Server domain supports the Java EE Management APIs.
The following example uses the WebLogic Scripting Tool (WLST) to set the JMXMBean
EditMBeanServerEnabled
attribute to false
. It assumes that you are running WLST on a Windows computer, that you created a domain under c:\mydomain
, and that you have not deleted the scripts that WebLogic Server creates along with your domain.
Note: The following steps prevent JMX clients (including the WebLogic Server Administration Console and the WebLogic Scripting Tool in online mode) from modifying the domain's configuration. You can still modify the domain configuration through the offline editing feature of WebLogic Scripting Tool. These steps do not prevent JMX clients from deploying or undeploying modules because the WebLogic Server deployment service does not use JMX. |
Start the domain's Administration Server.
In a command prompt, set up the required environment by running the following script:
c:\mydomain\setDomainEnv.cmd
In the same command prompt, enter the following commands:
java weblogic.WLST
connect('weblogic','weblogic')
edit()
startEdit()
cd('JMX/mydomain')
set('EditMBeanServerEnabled','false')
activate()
exit()
This chapter describes how to use JMX to monitor MBeans. JMX provides two ways to monitor MBeans: MBeans can emit notifications when specific events occur (such as a change in an attribute value), or a special type of MBean called a monitor MBean can poll another MBean and periodically emit notifications to describe an attribute value. You create Java classes called listeners that listen for these notifications and respond appropriately. For example, your management utility can include a listener that receives notifications when applications are deployed, undeployed, or redeployed. All WebLogic Server configuration MBeans emit notifications when attribute values change, and some run-time MBeans do.
This chapter includes the following sections:
Best Practices: Listening or Monitoring WebLogic Server Runtime Statistics
Listening for Notifications from WebLogic Server MBeans: Main Steps
If the MBean that you want to monitor emits notifications, you can choose whether to create a listener object that listens for changes in the MBean or a monitor MBean that periodically polls the MBean and emits notifications only when its attributes change in specific ways. The technique that you choose depends mostly on the complexity of the situations in which you want to receive notifications.
If your requirements are simple, registering a listener directly with an MBean is the preferred technique because the MBean pushes its notifications to your listener and you are notified of a change almost immediately. However, the base classes that you implement for a listener and optional filter (javax.management.NotificationListener
and NotificationFilter
) provide few facilities for comparing values with thresholds and other values. (See the javax.management
package in the Java SE 7 API Specification at http://docs.oracle.com/javase/7/docs/api/javax/management/package-summary.html
.)
If your notification requirements are sufficiently complex, or if you want to monitor a group of changes that are not directly associated with a single change in the value of an MBean attribute, use a monitor MBean. (See the javax.management.monitor
package in the Java SE 7 API Specification at http://docs.oracle.com/javase/7/docs/api/javax/management/monitor/package-summary.html
.) The monitor MBeans provide a rich set of tools for comparing data and sending notifications only under specific circumstances. However, the monitor periodically polls the observed MBean for changes in attribute value and you are notified of a change only as frequently as the polling interval that you specify.
The WebLogic Server JMX agent and WebLogic Server MBeans emit different types of notification objects for different types of events. Many event types trigger multiple MBeans to emit notifications at different points within the event process. Table 7-1 describes common event types and recommends the MBean with which a JMX monitoring application should register to listen for notifications.
Note: Each JMX notification object contains an attribute named The All JMX notification objects extend the |
Table 7-1 Events and Notification Objects
Event | Listening Recommendation |
---|---|
A WebLogic Server instance starts or stops |
To receive a notification when a server starts or stops, register a listener with each server's Each server in a domain provides its own For an example of such a listener and filter, see Listening for Notifications from WebLogic Server MBeans: Main Steps. Note: This recommendation assumes that you start a domain's Administration Server before starting Managed Servers. If a Managed Server starts before the Administration Server, a listener in the Domain Runtime MBean Server (which runs only on the Administration Server) will not be initialized at the time the Managed Server's |
A WebLogic Server resource is created or destroyed |
When you create a resource such as a server or a JDBC data source, WebLogic Server registers the resource's configuration MBean in the MBean server. When you delete a resource, WebLogic Server unregisters the configuration MBean. To listen for the registration and unregistration of MBeans, register a listener with when MBeans are registered or unregistered. If you register a listener with If you register a listener in the Runtime MBean Server or the Domain Runtime MBean Server, you receive notifications only when pending changes have been successfully activated in the domain. If you are interested solely in monitoring configuration data (and are not interested in monitoring run-time statistics), register your listener in only one Runtime MBean Server. See Best Practices: Choosing an MBean Server. See Example: Listening for The Registration of Configuration MBeans. |
The configuration of a WebLogic Server resource is modified |
All configuration MBeans emit notifications of type To receive this notification, register a listener with the MBean that is in the Domain Runtime MBean Server or Runtime MBean Server (see Best Practices: Choosing an MBean Server). If you register an MBean in the Edit MBean Server, you receive notifications when someone modifies the pending MBean hierarchy. If you register a listener in the Runtime MBean Server or the Domain Runtime MBean Server, you receive notifications only when pending changes have been successfully activated in the domain. If you are interested solely in monitoring configuration data (and are not interested in monitoring run-time statistics), register your listener in only one Runtime MBean Server. See Best Practices: Choosing an MBean Server. |
The run-time state of a WebLogic Server resource changes |
Some run-time MBeans emit notifications of type If a run-time MBean does not emit notifications, you can create a monitor MBean that polls the run-time MBean. See Using Monitor MBeans to Observe Changes: Main Steps. |
A WebLogic Server resource emits a log message |
When a WebLogic Server resource generates a log message, the server's To listen for log message notifications, register a listener with To see a list of error messages that WebLogic Server resources generate, refer to Error Messages. For more information, see |
WebLogic Server MBeans provide detailed statistics on the run-time state of its services and resources. The statistics in Table 7-2 provide a general overview of the performance of WebLogic Server. You can listen for changes to these statistics by creating a listener and registering it directly with the MBeans that contain the attributes or you can configure monitor MBeans to periodically poll and report only the statistics that you consider to be significant. (See Registering a Notification Listener and Filter, and Registering the Monitor and Listener.)
Table 7-2 Commonly Monitored WebLogic Server Runtime Statistics
To track this statistic... | Listen or monitor this MBean attribute... |
---|---|
The current state of server. |
MBean Type: ServerLifeCycleRuntimeMBean Attribute Name: |
Activity on the server's listen ports. |
MBean Type: ServerRuntimeMBean Attribute Name: MBean Type: ServerMBean Attribute Name: Use these two attributes together to compare the current activity on the server's listen ports to the total number of requests that can be backlogged on the ports. |
Memory and thread use. |
MBean Type: ThreadPoolRuntimeMBean Attribute Name: Indicates the number of threads in a server's execute queue that are taking up memory space but are not being used to process data. |
Memory and thread use |
MBean Type: ThreadPoolRuntimeMBean Attribute Name: Indicates the number of user requests waiting in a server's execute queue. |
Memory and thread use |
MBean Type: JVMRuntimeMBean Attribute Name: Indicates the amount of memory (in bytes) that is currently available in the server's JVM heap. |
Database connections |
MBean Type: JDBCDataSourceRuntimeMBean Attribute Name: Indicates the current number of active connections in a JDBC connection pool. |
Database connections |
MBean Type: JDBCDataSourceRuntimeMBean Attribute Name: The high water mark of active connections in a JDBC connection pool. The count starts at zero each time the connection pool is instantiated. |
Database connections |
MBean Type: JDBCDataSourceRuntimeMBean Attribute Name: Indicates the total number of leaked connections. Leaked connections are connections that have been checked out but never returned to the connection pool via a |
Database connections |
MBean Type: JDBCDataSourceRuntimeMBean Attribute Name: Indicates the average time to connect to a connection pool. |
Database connections |
MBean Type: JDBCDataSourceRuntimeMBean Attribute Name: Indicates when the connection pool fails to reconnect to its data store. Applications may notify a listener when this attribute increments, or when the attribute reaches a threshold, depending on the level of acceptable downtime. |
To listen directly for the notifications that an MBean emits:
Create a listener class in your application. See Creating a Notification Listener.
Create an additional class that registers your listener and an optional filter with the MBean whose notifications you want to receive. See Configuring a Notification Filter, and Registering a Notification Listener and Filter.
Package and deploy the listener and registration class. See Packaging and Deploying Listeners on WebLogic Server.
To create a notification listener:
Create a class that implements javax.management.NotificationListener
.
See NotificationListener
in the Java SE 7 API Specification at http://docs.oracle.com/javase/7/docs/api/javax/management/NotificationListener.html
.
Within the class, add a NotificationListener.handleNotification(Notification notification, java.lang.Object handback)
method.
Note: Your implementation of this method should return as soon as possible to avoid blocking its notification broadcaster. |
(Optional) In most listening situations, you want to know more than the simple fact that an MBean has emitted a notification object. For example, you might want to know the value of the notification object's Type
attribute, which is used to classify the type of event that caused the notification to be emitted.
To retrieve information from a notification object, within your handleNotification
method invoke the object's methods. Because all notification types extend javax.management.Notification
, the following Notification
methods are available for all notifications:
getMessage()
getSequenceNumber()
getTimeStamp()
getType()
getUserData()
See Notification
in the Java SE 7 API Specification at http://docs.oracle.com/javase/7/docs/api/javax/management/Notification.html
.
Most notification types provide additional methods for retrieving data that is specific to the notification. For example, javax.management.AttributeChangeNotification
provides getNewValue()
and getOldValue()
, which you can use to determine how the attribute value has changed.
Example 7-1 is a simple listener that uses AttributeChangeNotification
methods to retrieve the name of an attribute with a changed value, and the old and new values.
Example 7-1 Notification Listener
import javax.management.Notification; import javax.management.NotificationFilter; import javax.management.NotificationListener; import javax.management.AttributeChangeNotification; public class MyListener implements NotificationListener { public void handleNotification(Notification notification, Object obj) { if(notification instanceof AttributeChangeNotification) { AttributeChangeNotification attributeChange = (AttributeChangeNotification) notification; System.out.println("This notification is an AttributeChangeNotification"); System.out.println("Observed Attribute: " + attributeChange.getAttributeName() ); System.out.println("Old Value: " + attributeChange.getOldValue() ); System.out.println("New Value: " + attributeChange.getNewValue() ); } } }
As of JMX 1.2, there are no special requirements for programming a listener that runs in a different JVM from the MBean to which it is listening.
Once you establish a connection to the remote JMX agent (using javax.management.MBeanServerConnection
), JMX takes care of sharing data between the JVMs. See Registering a Notification Listener and Filter, for instructions on establishing a connection from a remote JVM.
Consider the following recommendations while creating your NotificationListener
class:
Unless you use a notification filter, your listener receives all notifications (of all notification types) from the MBeans with which it is registered.
Instead of using one listener for all possible notifications that an MBean emits, the best practice is to use a combination of filters and listeners. While having multiple listeners adds to the amount of time for initializing the JVM, the trade-off is ease of code maintenance.
If your WebLogic Server environment contains multiple instances of MBean types that you want to monitor, you can create one notification listener and then create as many registration classes as MBean instances that you want to monitor.
For example, if your WebLogic Server domain contains three JDBC data sources, you can create one listener class that listens for AttributeChangeNotifications
. Then, you create three registration classes. Each registration class registers the listener with a specific instance of JDBCDataSourceRuntimeMBean
.
While the handleNotification
method signature includes an argument for a handback object, your listener does not need to retrieve data from or otherwise manipulate the handback object. It is an opaque object that helps the listener to associate information regarding the MBean emitter.
Your implementation of the handleNotification
method should return as soon as possible to avoid blocking its notification broadcaster.
If you invoke a method from a specialized notification type, wrap the method calls in an if
statement to prevent your listener from invoking the method on notification objects of all types.
As of JDK 1.5, the JDK includes two simple filter classes that you can configure to forward notifications that match criteria that you specify. To configure one of the JDK's filter classes:
In the class that registers your listener with an MBean create an instance of javax.management.NotificationFilterSupport
or AttributeChangeNotificationFilter
.
Invoke a filter class method to specify filter criteria.
See NotificationFilterSupport
(http://docs.oracle.com/javase/7/docs/api/javax/management/NotificationFilterSupport.html
) or AttributeChangeNotificationFilter
(http://docs.oracle.com/javase/7/docs/api/javax/management/AttributeChangeNotificationFilter.html
) in the Java SE 7 API Specification.
For example, the following lines of code configure an AttributeChangeNotificationFilter
that forwards only attribute change notifications and only if there is a change in an attribute named State
:
AttributeChangeNotificationFilter filter = new AttributeChangeNotificationFilter(); filter.enableAttribute("State");
If the JDK's filter class is too simplistic for your needs, you can create more sophisticated, custom filter classes. (See NotificationFilter
in the Java SE 7 API Specification at http://docs.oracle.com/javase/7/docs/api/javax/management/NotificationFilter.html
.) However, Oracle recommends that you use the JDK filter classes whenever possible: using a custom filter complicates the packaging and deployment of your listener and filter. See Packaging and Deploying Listeners on WebLogic Server.
After you implement a notification listener class, you create an additional class that registers your listener (and optionally configures and registers a filter) with an MBean instance.
To register a notification listener and filter with an M Bean:
Initialize a connection to a Runtime MBean Server or the Domain Runtime MBean Server.
To register with a WebLogic Server MBean, navigate the MBean hierarchy and retrieve an object name for the MBean that you want to listen to. See Make Remote Connections to an MBean Server.
To register with a custom MBean, create an ObjectName
that contains the MBean's JMX object name. See javax.management.ObjectName
in the Java SE 7 API Specification at http://docs.oracle.com/javase/7/docs/api/javax/management/ObjectName.html
.
Instantiate the listener class that you created.
(Optional) Instantiate and configure one of the JDK's filter classes or instantiate a custom class.
Register the listener and filter by passing the MBean's object name, listener class, and filter class to the MBeanServerConnection.addNotificationListener (ObjectName
name
, ObjectName
listener
, NotificationFilter
filter
,Object
handback
)
method.
The example class registers the listener from Example 7-1 and the JDK's AttributeChangeNotificationFilter
with all ServerLifeCycleRuntimeMBean
s in a domain. The class does not pass a handback object.
In the example, weblogic
is a user who has permission to view and modify MBean attributes. For information about permissions to view and modify MBeans, refer to "Users, Groups, and Security Roles" in Securing Resources Using Roles and Policies for Oracle WebLogic Server.
The example class also includes some code that keeps the RegisterListener
class active and not exit the main program. Usually this code is not necessary because a listener class runs in the context of some larger application that is responsible for invoking the class and keeping it active. It is included here so you can easily compile and see the example working.
Example 7-2 Registering a Listener with ServerLifeCycleRuntimeMBean
import java.util.Hashtable; import java.io.IOException; import java.net.MalformedURLException; import javax.management.MBeanServerConnection; import javax.management.ObjectName; import javax.management.MalformedObjectNameException; import javax.management.remote.JMXConnector; import javax.management.remote.JMXConnectorFactory; import javax.management.remote.JMXServiceURL; import javax.naming.Context; import javax.management.AttributeChangeNotificationFilter; public class RegisterListener { private static MBeanServerConnection connection; private static JMXConnector connector; private static final ObjectName service; // Initializing the object name for DomainRuntimeServiceMBean // so it can be used throughout the class. static { try { service = new ObjectName( "com.bea:Name=DomainRuntimeService,Type=weblogic.management.mbeanserv ers.domainruntime.DomainRuntimeServiceMBean"); }catch (MalformedObjectNameException e) { throw new AssertionError(e.getMessage()); } } /* * Initialize connection to the Domain Runtime MBean Server * each server in the domain hosts its own instance. */ public static void initConnection(String hostname, String portString, String username, String password) throws IOException, MalformedURLException { String protocol = "t3"; Integer portInteger = Integer.valueOf(portString); int port = portInteger.intValue(); String jndiroot = "/jndi/"; String mserver = "weblogic.management.mbeanservers.domainruntime"; JMXServiceURL serviceURL = new JMXServiceURL(protocol, hostname, port, jndiroot + mserver); Hashtable h = new Hashtable(); h.put(Context.SECURITY_PRINCIPAL, username); h.put(Context.SECURITY_CREDENTIALS, password); h.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, "weblogic.management.remote"); connector = JMXConnectorFactory.connect(serviceURL, h); connection = connector.getMBeanServerConnection(); } /* * Get an array of ServerLifeCycleRuntimeMBeans */ public static ObjectName[] getServerLCRuntimes() throws Exception { ObjectName domainRT = (ObjectName) connection.getAttribute(service, "DomainRuntime"); return (ObjectName[]) connection.getAttribute(domainRT, "ServerLifecycleRuntimes"); } public static void main(String[] args) throws Exception { String hostname = args[0]; String portString = args[1]; String username = args[2]; String password = args[3]; try { //Instantiating your listener class. MyListener listener = new MyListener(); AttributeChangeNotificationFilter filter = new AttributeChangeNotificationFilter(); filter.enableAttribute("State"); initConnection(hostname, portString, username, password); //Passing the name of the MBeans and your listener class to the //addNotificationListener method of MBeanServer. ObjectName[] serverLCRT = getServerLCRuntimes(); int length= (int) serverLCRT.length; for (int i=0; i < length; i++) { connection.addNotificationListener(serverLCRT[i], listener, filter, null); System.out.println("\n[myListener]: Listener registered with" +serverLCRT[i]); } //Keeping the remote client active. System.out.println("pausing..........."); System.in.read(); } catch(Exception e) { System.out.println("Exception: " + e); } } }
You can package and deploy a JMX listener as a remote application, a WebLogic Server startup class (which makes the listener available as soon as a server boots), or within one of your other applications that you deploy on WebLogic Server.
If you use a filter from the JDK, you do not need to package the filter class. It is always available through the JDK.
Table 7-3 describes how to package and deploy your listeners and any custom filters.
Table 7-3 Packaging and Deploying Listeners and Custom Filters
If you deploy the listener... | Do this for the listener... | Do this for a custom filter... |
---|---|---|
As a remote application |
Make the listener's class available on the remote client's classpath. |
Make the filter's class available on the remote client's classpath. Also add the filter class to the classpath of each server instance that hosts the monitored MBeans by archiving the class in a JAR file and copying the JAR in each server's |
As a WebLogic Server startup class |
Add the listener class to the server's classpath by archiving the class in a JAR file and copying the JAR in the server's |
Add the filter class to the server's classpath by archiving the class in a JAR file and copying the JAR in the server's |
As part of an application that you deploy on WebLogic Server |
Package the listener class with the application. |
Package the listener class with the application. Also add the filter class to the classpath of each server instance that hosts the monitored MBeans by doing one of the following:
|
When you create a WebLogic Server resource, such as a server or a JDBC data source, WebLogic Server creates a configuration MBean and registers it in the Domain Runtime MBean Server.
To listen for these events, register a listener with javax.management.MBeanServerDelegate
, which emits a notification of type
javax.management.MBeanServerNotification
each time an MBean is registered or unregistered. See MBeanServerDelegate
in the Java SE 7 API Specification (http://docs.oracle.com/javase/7/docs/api/javax/management/MBeanServerDelegateMBean.html
)
Note the following about the example listener in Example 7-3:
To provide information about which type of WebLogic Server MBean has been registered, the listener looks at the object name of the registered MBean. All WebLogic Server MBean object names contain a key property whose name is "Type" and whose value indicates the type of MBean. For example, instances of ServerRuntimeMBean
contain the Type=ServerRuntime
key property in their object names.
All JMX notifications contain a Type
attribute, whose value offers a way to categorize and filter notifications. The Type
attribute in MBeanServerNotification
contains only one of two possible strings: "JMX.mbean.registered" or "JMX.mbean.unregistered". JMX notifications also contain a getType
method that returns the value of the Type
attribute.
The listener in Example 7-3 invokes different lines of code depending on the value of the Type
attribute.
If a JDBCDataSourceRuntimeMBean
has been registered, the listener passes the MBeans' object name to a custom method. The custom method registers a listener and configures a filter for the JDBCDataSourceRuntimeMBean
; this MBean listener emits messages when the MBean's Enabled
attribute changes.
The implementation of the custom method is located in the registration class (not the filter class) so that the method can reuse registration class's connection to the MBean server. Such reuse is an efficient use of resources and eliminates the need to store credentials and URLs in multiple classes.
Example 7-3 Example: Listening for MBeans Being Registered and Unregistered
import javax.management.Notification; import javax.management.NotificationListener; import javax.management.MBeanServerNotification; import javax.management.ObjectName; public class DelegateListener implements NotificationListener { public void handleNotification(Notification notification, Object obj) { if (notification instanceof MBeanServerNotification) { MBeanServerNotification msnotification = (MBeanServerNotification) notification; // Get the value of the MBeanServerNotification // Type attribute, which contains either // "JMX.mbean.registered" or "JMX.mbean.unregistered" String nType = msnotification.getType(); // Get the object name of the MBean that was registered or // unregistered ObjectName mbn = msnotification.getMBeanName(); // Object names for WebLogic Server MBeans always contain // a "Type" key property, which indicates the // MBean's type (such as ServerRuntime or Log) String key = mbn.getKeyProperty("Type"); if (nType.equals("JMX.mbean.registered")) { System.out.println("A " + key + " has been created."); System.out.println("Full MBean name: " + mbn); System.out.println("Time: " + msnotification.getTimeStamp()); if (key.equals("JDBCDataSourceRuntime")) { // Registers a listener with a ServerRuntimeMBean. // By defining the "registerwithServerRuntime" method // in the "ListenToDelegate" class, you can reuse the // connection that "ListenToDelegate" established; // in addition to being an efficient way to use resources, // it eliminates the need to store credentials and URLs in // multiple classes. ListenToDelegate.registerwithJDBCDataSourceRuntime(mbn); } } if (nType.equals("JMX.mbean.unregistered")) { System.out.println("An MBean has been unregistered"); System.out.println("Server name: " + mbn.getKeyProperty("Name")); System.out.println("Time: " + msnotification.getTimeStamp()); System.out.println("Full MBean name: " + msnotification.getMBeanName()); } } } }
Example 7-4 shows methods from a registration class. Note the following:
The JMX object name for MBeanServerDelegate
is always "JMImplementation:type=MBeanServerDelegate"
.
The main
method configures an instance of javax.management.NotificationFilterSupport
to forward notifications only if value of the notification's Type attribute starts with "JMX.mbean.registered" or "JMX.mbean.unregistered".
The registerwithJDBCDataSourceRuntime
method registers the listener in Example 7-1 with the specified JDBCDataSourceRuntimeMBean
instance. The method also configures a javax.management.AttributeChangeNotificationFilter
, which forwards only AttributeChangeNotification
s that describe changes to an attribute named Enabled
.
To compile and run these methods, use the supporting custom methods from Example 7-2 and run the resulting class as a remote JMX client.
Example 7-4 Example: Registering a Listener with MBeanServerDelegate
public static void main(String[] args) throws Exception { String hostname = args[0]; String portString = args[1]; String username = args[2]; String password = args[3]; ObjectName delegate = new ObjectName( "JMImplementation:type=MBeanServerDelegate"); try { //Instantiating your listener class. StartStopListener slistener = new StartStopListener(); NotificationFilterSupport filter = new NotificationFilterSupport(); filter.enableType("JMX.mbean.registered"); filter.enableType("JMX.mbean.unregistered"); /* Invoke a custom method that establishes a connection to the * Domain Runtime MBean Server and uses an instance of * MBeanServerConnection to represents the connection. The custom * method assigns the MBeanServerConnection to a class-wide, static * variable named "connection". */ initConnection(hostname, portString, username, password); //Passing the name of the MBeans and your listener class to the //addNotificationListener method of MBeanServer. connection.addNotificationListener(delegate, slistener, filter, null); System.out.println("\n[myListener]: Listener registered ..."); //Keeping the remote client active. System.out.println("pausing..........."); System.in.read(); } catch (Exception e) { System.out.println("Exception: " + e); } } // Called by the listener if it receives notification of a // JDBCDataSourceRuntimeMBean being registered. public static void registerwithJDBCDataSourceRuntime(ObjectName mbname) { try { MyListener mylistener = new MyListener(); AttributeChangeNotificationFilter filter = new AttributeChangeNotificationFilter(); filter.enableAttribute("Enabled"); connection.addNotificationListener(mbname, mylistener, filter, null); } catch (Exception e) { System.out.println("Exception: " + e); } }
To configure and use monitor MBeans:
Choose the type of monitor MBean type that supports your monitoring needs. See Monitor MBean Types and Notification Types.
Create a listener class that can listen for notifications from monitor MBeans. See Creating a Notification Listener for a Monitor MBean.
Create a class that creates, registers and configures a monitor MBean, registers your listener class with the monitor MBean, and then starts the monitor MBean. See Registering the Monitor and Listener.
JMX provides monitor MBeans that are specialized to observe specific types of changes:
StringMonitorMBean
observes attributes whose value is a String
.
Use this monitor to periodically observe attributes such as ServerLifeCycleRuntimeMBean
State
.
See javax.management.monitor.StringMonitor
in the Java SE 7 API Specification at http://docs.oracle.com/javase/7/docs/api/javax/management/monitor/StringMonitor.html
, which implements StringMonitorMBean
.
GaugeMonitorMBean
observes attributes whose value is a Number
.
Use this monitor to observe an attribute whose value fluctuates as a result of normal operations. Configure the gauge monitor to emit a notification if the value of the attribute fluctuates outside a specific range. For example, you can use it to monitor the ThreadPoolRuntimeMBean
StandbyThreadCount
attribute to verify that the number of unused but available threads in a server falls within an acceptable range.
See javax.management.monitor.GaugeMonitor
in the Java SE 7 API Specification (see http://docs.oracle.com/javase/7/docs/api/javax/management/monitor/GaugeMonitor.html
), which implements GaugeMonitorMBean
.
CounterMonitorMBean
observes attributes whose value is a Number
.
Use this monitor to observe an attribute whose value only increases as a result of normal operation. Configure the counter monitor to emit a notification if the value of the attribute crosses an upper threshold. You can also configure the counter monitor to increase the threshold and then reset the threshold at a specified point.
For example, to track the overall number of hits on a server and to be notified each time 100 additional hits have accumulated, use a counter monitor that observes the ServerRuntimeMBean
SocketsOpenedTotalCount
attribute.
See javax.management.monitor.CounterMonitor
in the Java SE 7 API Specification (see http://docs.oracle.com/javase/7/docs/api/javax/management/monitor/CounterMonitor.html
), which implements CounterMonitorMBean
.
All monitor MBeans emit notifications of type javax.management.monitor.MonitorNotification
. When a monitor MBean generates a notification, it describes the event that generated the notification by writing a specific value into the notification's Type
property. Table 7-4 describes the value of the Type
property that the different types of monitor MBeans encode. A filter or listener can use the notification's getType()
method to retrieve the String
in the Type
property.
Table 7-4 Monitor MBeans and the MonitorNotification Type Property
A Monitor MBean of This Type | Encodes This String in the MonitorNotification's Type Property |
---|---|
CounterMonitor |
|
GaugeMonitor |
|
StringMonitor |
|
If an error occurs, all monitors encode one of the following values in the notification's Type
property:
jmx.monitor.error.mbean
, which indicates that the observed MBean is not registered in the MBean Server. The observed object name is provided in the notification.
jmx.monitor.error.attribute
, which indicates that the observed attribute does not exist in the observed object. The observed object name and observed attribute name are provided in the notification.
jmx.monitor.error.type
, which indicates that the object instance of the observed attribute value is null
or not of the appropriate type for the given monitor. The observed object name and observed attribute name are provided in the notification.
jmx.monitor.error.runtime
, which contains exceptions that are thrown while trying to get the value of the observed attribute (for reasons other than the cases described above).
The counter and the gauge monitors can also encode jmx.monitor.error.threshold
into the Type
property under the following circumstances:
For a counter monitor, when the threshold, the offset, or the modulus is not of the same type as the observed counter attribute.
For a gauge monitor, when the low threshold or high threshold is not of the same type as the observed gauge attribute.
When an observed attributes meets the criteria that you specify, a monitor MBean emits a notification. There are no special requirements for creating a listener for a MonitorNotification
. The steps are the same as those described in Creating a Notification Listener, except:
You listen for notifications of type MonitorNotification
.
Optionally, you can import the javax.management.monitor.MonitorNotification
class and invoke its methods to retrieve additional information about the event that generated the notification.
See Example 7-5.
Example 7-5 Listener for Monitor Notifications
import javax.management.Notification; import javax.management.NotificationListener; import javax.management.monitor.MonitorNotification; public class MonitorListener implements NotificationListener { public void handleNotification(Notification notification, Object obj) { if(notification instanceof Notification) { Notification notif = (Notification) notification; System.out.println("Notification type" + notif.getType() ); System.out.println("Message: " + notif.getMessage() ); } if (notification instanceof MonitorNotification) { MonitorNotification mn = (MonitorNotification) notification; System.out.println("Observed Attribute: " + mn.getObservedAttribute()); System.out.println("Trigger: " + mn.getTrigger() ); } } }
Recall that to use a monitor MBean, you first must create and register an instance of the monitor MBean in the MBean server. Then you register a listener with the monitor MBean that you created. You can do all of this in a single class.
To register a monitor MBean, register your listener, and start the monitor MBean:
Initialize a connection to the Domain Runtime MBean Server.
Create an ObjectName
for your monitor MBean instance.
See javax.management.ObjectName
in the Java SE 7 API Specification at http://docs.oracle.com/javase/7/docs/api/javax/management/ObjectName.html
.
Oracle recommends that your object name starts with the name of your organization and includes key properties that clearly identifies the purpose of the monitor MBean instance.
For example, mycompany:Name=SocketMonitor,Type=CounterMonitor
Create and register one of the monitor MBeans.
Use javax.management.MBeanServerConnection.createMBean(String
classname
ObjectName
name
)
method, where:
classname
represents one of the following values:
javax.management.monitor.CounterMonitor
javax.management.monitor.GaugeMonitor
javax.management.monitor.StringMonitor
Hname
represents the object name that you created for the monitor MBean instance.
Configure the monitor MBean by setting the value of its attributes.
For guidelines on which attributes to set, see the javax.management.monitoring
package in the Java SE 7 API Specification at http://docs.oracle.com/javase/7/docs/api/javax/management/monitor/package-summary.html
.
To specify the MBean that your monitor MBean monitors (the observed MBean), invoke the monitor MBean's addObservedObject(ObjectName
objectname
)
and addObservedAttribute(String
attributename
)
operations where.
objectname
is the ObjectName
of the observed MBean
attributename
is the name of the attribute in the observed MBean that you want to monitor
A single instance of a monitor MBean can monitor multiple MBeans. Invoke the addObservedObject
and addObservedAttribute
operation for each MBean instance that you want to monitor.
Instantiate the listener object that you created in Creating a Notification Listener for a Monitor MBean.
Optionally instantiate and configure a filter.
Register the listener and optional filter with the monitor MBean. Do not register the listener with the observed MBean.
Invoke the monitor MBean's addNotificationListener(NotificationListener
listener
, NotificationFilter
filter
, Object
handback
)
method.
Start the monitor by invoking the monitor MBean's start()
operation.
Example 7-6 shows the main()
method of a class that creates and configures a CounterMonitorMBean
to observe the SocketsOpenedTotalCount
attribute in each ServerRuntimeMBean
instance in a domain. (See "SocketsOpenedTotalCount" in MBean Reference for Oracle WebLogic Server.)
The code example connects to the Domain Runtime MBean Server so that it can monitor multiple instances of ServerRuntimeMBean
. Note the following:
Only one instance of CounterMonitorMBean
monitors all instances of ServerRuntimeMBean
. The Domain Runtime MBean Server gives the CounterMonitorMBean
federated access to instances of ServerRuntimeMBean
that are running in a different JVM.
Only one instance of your listener class and the filter class listens and filters notifications from the CounterMonitorMBean
.
To compile and run this main method, use the supporting custom methods from Example 7-2 and run the resulting class as a remote JMX client.
Example 7-6 Example: Registering a CounterMonitorMBean and Its Listener
public static void main(String[] args) throws Exception { String hostname = args[0]; String portString = args[1]; String username = args[2]; String password = args[3]; try { /* Invokes a custom method that establishes a connection to the * Domain Runtime MBean Server and uses an instance of * MBeanServerConnection to represents the connection. The custom * method assigns the MBeanServerConnection to a class-wide, static * variable named "connection". */ initConnection(hostname, portString, username, password); //Creates and registers the monitor MBean. ObjectName monitorON = new ObjectName("mycompany:Name=mySocketMonitor,Type=CounterMonitor"); String classname = "javax.management.monitor.CounterMonitor"; System.out.println("===> create mbean "+monitorON); connection.createMBean(classname, monitorON); //Configure the monitor MBean. Number initThreshold = new Long(2); Number offset = new Long(1); connection.setAttribute(monitorON, new Attribute("InitThreshold", initThreshold)); connection.setAttribute(monitorON, new Attribute("Offset", offset)); connection.setAttribute(monitorON, new Attribute("Notify", new Boolean(true))); //Gets the object names of the MBeans that you want to monitor. ObjectName[] serverRT = getServerRuntimes(); int length= (int) serverRT.length; for (int i=0; i < length; i++) { //Sets each instance of ServerRuntime MBean as a monitored MBean. System.out.println("===> add observed mbean "+serverRT[i]); connection.invoke(monitorON, "addObservedObject", new Object[] { serverRT[i] }, new String[] { "javax.management.ObjectName" }); Attribute attr = new Attribute("ObservedAttribute", "SocketsOpenedTotalCount"); connection.setAttribute(monitorON, attr); } // Instantiates your listener class and configures a filter to // forward only counter monitor messages. MonitorListener listener = new MonitorListener(); NotificationFilterSupport filter = new NotificationFilterSupport(); filter.enableType("jmx.monitor.counter"); filter.enableType("jmx.monitor.error"); //Uses the MBean server's addNotificationListener method to //register the listener and filter with the monitor MBean. System.out.println("===> ADD NOTIFICATION LISTENER TO "+monitorON); connection.addNotificationListener(monitorON, listener, filter, null); System.out.println("\n[myListener]: Listener registered ..."); //Starts the monitor. connection.invoke(monitorON, "start", new Object[] { }, new String[] { }); //Keeps the remote client active. System.out.println("pausing..........."); System.in.read(); } catch(Exception e) { System.out.println("Exception: " + e); e.printStackTrace(); } }
This chapter describes how to use JMX to manage security realms, which comprise the mechanisms for protecting WebLogic resources. Each security realm consists of a set of configured security providers, which are modular components that handle specific aspects of security. You can create a JMX client that uses the providers in a realm to add or remove security data such as users and groups. You can also create a client that adds or removes providers and makes other changes to the realm configuration.
This chapter includes the following sections:
For more information about WebLogic Security, see Understanding Security for Oracle WebLogic Server.
Like other subsystems, the WebLogic Server security framework organizes its MBeans in a hierarchy that JMX clients can navigate without constructing JMX object names. However, the set of MBean types that are available in a security realm depends on which security providers you have installed in the realm, and the set of services that each security provider enables depends on how the provider was created.
The root of the security realm hierarchy is the RealmMBean
. It contains all of the providers that have been configured for the realm. For example, its Authorizers
attribute contains all authorization providers that have been configured for the realm. WebLogic Server installs a default set of security providers; therefore, by default the RealmMBean
Authorizers
attribute contains a DefaultAuthorizerMBean
. However, you can uninstall these default providers and replace them with any number of your own providers or third-party providers. For information about the default security providers, see "Configuring WebLogic Security Providers" and "Configuring Authorization Providers" in Administering Security for Oracle WebLogic Server.
Each security provider must extend a base provider type. For example, DefaultAuthorizerMBean
extends AuthorizerMBean
, and any custom or third-party authorization provider also extends AuthorizerMBean
. If a JMX client gets the value of the RealmMBean
Authorizers
attribute, the MBean server returns all MBeans in the realm that extend AuthorizerMBean
. The JMX client can iterate through the list of providers and select one based on the value of its Name
attribute or other criteria.
Base provider types can be enhanced by extending a set of optional mix-in interfaces. For example, if an authentication provider extends the UserEditorMBean
, then the provider can add users to the realm.
WebLogic Server's Security MBeans configure security providers in a security realm. The following tables describe the MBeans that configure different types of security providers.
Table 6-1 describes the MBeans that configure Authentication security providers, as well as the abstract MBean classes that Authentication providers must extend. In addition to the MBeans in this table, WebLogic Server includes configuration MBeans for each out-of-the-box Authentication provider.
Table 6-2 describes the MBeans that configure security providers, other than Authentication security providers.
Table 6-3 describes optional MBean mixin interfaces that security providers can support for management and utility purposes.
For more information about configuring WebLogic security providers, see "Configuring WebLogic Security Providers" and "Configuring Authorization Providers" in Administering Security for Oracle WebLogic Server. Figure 6-1 illustrates where the MBeans are located in the configuration MBean hierarchy.
Table 6-1 MBeans for Authentication Security Providers
This MBean... | Configures... |
---|---|
AuthenticationProviderMBean |
The base MBean for all MBean implementations that manage Authentication providers. If your Authentication provider uses the WebLogic Security SSPI to provide login services, then your MBean must extend See "AuthenticationProviderMBean" in the MBean Reference for Oracle WebLogic Server. |
AuthenticatorMBean |
The SSPI MBean that all Authentication providers with login services must extend. This MBean provides a See "AuthenticatorMBean" in the MBean Reference for Oracle WebLogic Server. |
IdentityAsserterMBean |
The SSPI MBean that all Identity Assertion providers must extend. This MBean enables an Identity Assertion provider to specify the token types for which it is capable of asserting identity. See "IdentityAsserterMBean" in the MBean Reference for Oracle WebLogic Server. |
ServletAuthenticationFilterMBean |
The SSPI MBean that all Servlet Authentication Filter providers must extend. This MBean is just a marker interface. It has no methods on it. See "ServletAuthenticationFilterMBean" in the MBean Reference for Oracle WebLogic Server. |
Table 6-2 MBeans for Other Security Providers
This MBean... | Configures... |
---|---|
AdjudicatorMBean |
The SSPI MBean that all Adjudication providers must extend. See "AdjudicatorMBean" in the MBean Reference for Oracle WebLogic Server. |
DefaultAdjudicatorMBean |
Configuration attributes for the WebLogic Adjudication provider. See "DefaultAdjudicatorMBean" in the MBean Reference for Oracle WebLogic Server. |
AuditorMBean |
The SSPI MBean that all Auditing providers must extend. See "AuditorMBean" in the MBean Reference for Oracle WebLogic Server. |
DefaultAuditorMBean |
Configuration attributes for the WebLogic Auditing provider. See "DefaultAuditorMBean" in the MBean Reference for Oracle WebLogic Server. |
AuthorizerMBean |
The SSPI MBean that all Authorization providers must extend. See "AuthorizerMBean" in the MBean Reference for Oracle WebLogic Server. |
DeployableAuthorizerMBean |
The SSPI MBean that must be extended by all Authorization providers that can store policies created while deploying a Web application or EJB. See "DeployableAuthorizerMBean" in the MBean Reference for Oracle WebLogic Server. |
DefaultAuthorizerMBean |
Configuration attributes for the WebLogic Authorization provider. See "DefaultAuthorizerMBean" in the MBean Reference for Oracle WebLogic Server. |
CredentialMapperMBean |
The SSPI MBean that all Credential Mapping providers must extend. See "CredentialMapperMBean" in the MBean Reference for Oracle WebLogic Server. |
DeployableCredentialMapperMBean |
The SSPI MBean that must be extended by all Credential Mapper providers that can store credential maps created while deploying a component. See "DeployableCredentialMapperMBean" in the MBean Reference for Oracle WebLogic Server. |
DefaultCredentialMapperMBean |
Configuration attributes for the WebLogic Credential Mapping provider, a username/password Credential Mapping provider. See "DefaultCredentialMapperMBean" in the MBean Reference for Oracle WebLogic Server. |
PKICredentialMapperMBean |
Configuration attributes for the PKI Credential Mapping provider, a key pair Credential Mapping provider. See "PKICredentialMapperMBean" in the MBean Reference for Oracle WebLogic Server. |
SAMLCredentialMapperMBean |
Configuration attributes for the SAML Credential Mapping provider, a Security Assertion Markup Language Credential Mapping provider. See "SAMLCredentialMapperMBean" in the MBean Reference for Oracle WebLogic Server. |
CertPathProviderMBean |
The base MBean for all certification path providers. See "CertPathProviderMBean" in the MBean Reference for Oracle WebLogic Server. |
CertPathBuilderMBean |
The SSPI MBean that all certification path providers with CertPathBuilder services must extend. See "CertPathBuilderMBean" in the MBean Reference for Oracle WebLogic Server. |
CertPathValidatorMBean |
The SSPI MBean that all certification path providers with CertPathValidator services must extend. See "CertPathValidatorMBean" in the MBean Reference for Oracle WebLogic Server. |
CertificateRegistryMBean |
Configures and manages the certificate registry. It is both a builder and a validator. It supports building from the end certificate, the end certificate's subject DN, the end certificate's issuer DN and serial number, and the end certificate's subject key identifier. See "CertificateRegistryMBean" in the MBean Reference for Oracle WebLogic Server. |
WebLogicCertPathProviderMBean |
The SSPI MBean that all certification path providers with CertPathBuilder services must extend. See "WebLogicCertPathProviderMBean" in the MBean Reference for Oracle WebLogic Server. |
RoleMapperMBean |
The base MBean for Role Mapping providers. A Role Mapping provider for a non-deployable module must extend this MBean directly. A Role Mapping provider for a deployable module must extend the See "RoleMapperMBean" in the MBean Reference for Oracle WebLogic Server. |
DeployableRoleMapperMBean |
The SSPI MBean that must be extended by Role Mapping providers that can store roles created while deploying a Web application or EJB. See "DeployableRoleMapperMBean" in the MBean Reference for Oracle WebLogic Server. |
DefaultRoleMapperMBean |
Configuration attributes for the WebLogic Role Mapping provider. See "DefaultRoleMapperMBean" in the MBean Reference for Oracle WebLogic Server. |
Table 6-3 MBean Mixin Interfaces for Security Providers
This MBean... | Configures... |
---|---|
ContextHandlerMBean |
Provides a set of attributes for ContextHandler support. An Auditor provider MBean can optionally implement this MBean. See "ContextHandlerMBean" in the MBean Reference for Oracle WebLogic Server. |
GroupEditorMBean |
Provides a set of methods for creating, editing, and removing groups. An Authentication provider MBean can optionally implement this MBean. See "GroupEditorMBean" in the MBean Reference for Oracle WebLogic Server. |
GroupMemberListerMBean |
Provides a method for listing a group's members. An Authentication provider MBean can optionally implement this MBean. See "GroupMemberListerMBean" in the MBean Reference for Oracle WebLogic Server. |
GroupMembershipHierarchyCacheMBean |
Provides configuration attributes that are required to support the Group Membership Hierarchy Cache. An Authentication provider MBean can optionally implement this MBean. See "GroupMembershipHierarchyCacheMBean" in the MBean Reference for Oracle WebLogic Server. |
GroupReaderMBean |
Provides a set of methods for reading data about groups. An Authentication provider MBean can optionally implement this MBean. See "GroupReaderMBean" in the MBean Reference for Oracle WebLogic Server. |
MemberGroupListerMBean |
Provides a method for listing the groups that contain a member. An Authentication provider MBean can optionally implement this MBean. See "MemberGroupListerMBean" in the MBean Reference for Oracle WebLogic Server. |
UserEditorMBean |
Provides a set of methods for creating, editing, and removing users. An Authentication provider MBean can optionally implement this MBean. See "UserEditorMBean" in the MBean Reference for Oracle WebLogic Server. |
UserLockoutManagerMBean |
Lists and manages lockouts on user accounts. An Authentication provider MBean can optionally implement this MBean. See "UserLockoutManagerMBean" in the MBean Reference for Oracle WebLogic Server. |
UserPasswordEditorMBean |
Provides two methods for changing a user's password. An Authentication provider MBean can optionally implement this MBean. See "UserPasswordEditorMBean" in the MBean Reference for Oracle WebLogic Server. |
UserReaderMBean |
Provides a set of methods for reading data about users. An Authentication provider MBean can optionally implement this MBean. See "UserReaderMBean" in the MBean Reference for Oracle WebLogic Server. |
UserRemoverMBean |
Provides a method for removing users. An Authentication provider MBean can optionally implement this MBean. See "UserRemoverMBean" in the MBean Reference for Oracle WebLogic Server. |
RoleEditorMBean |
Provides a set of methods for creating, editing, and removing roles. A Role Mapping provider MBean can optionally implement this MBean. See "RoleEditorMBean" in the MBean Reference for Oracle WebLogic Server. |
RoleListerMBean |
Provides a set of methods for listing data about roles. A Role Mapping provider MBean can optionally implement this MBean. See "RoleListerMBean" in the MBean Reference for Oracle WebLogic Server. |
RoleReaderMBean |
Provides a set of methods for reading roles. A Role Mapping provider MBean can optionally implement this MBean. See "RoleReaderMBean" in the MBean Reference for Oracle WebLogic Server. |
PolicyEditorMBean |
Provides a set of methods for creating, editing, and removing policies. An Authorization provider MBean can optionally implement this MBean. See "PolicyEditorMBean" in the MBean Reference for Oracle WebLogic Server. |
PolicyListerMBean |
Provides a set of methods for listing data about policies. An Authorization provider MBean can optionally implement this MBean. See "PolicyListerMBean" in the MBean Reference for Oracle WebLogic Server. |
PolicyReaderMBean |
Provides a set of methods for reading policies. An Authorization provider MBean can optionally implement this MBean. See "PolicyReaderMBean" in the MBean Reference for Oracle WebLogic Server. |
PKICredentialMapEditorMBean |
Provides a set of methods for creating, editing, and removing a credential map that matches users, resources and credential action to keystore aliases and the corresponding passwords. A PKICredentialMapping provider MBean can optionally implement this MBean. See "PKICredentialMapEditorMBean" in the MBean Reference for Oracle WebLogic Server. |
PKICredentialMapReaderMBean |
Provides a set of methods for reading a credential map that matches users and resources to keystore aliases and their corresponding passwords that can then be used to retrieve key information or public certificate information from the configured keystores. A PKICredentialMapping provider MBean can optionally implement this MBean. <^p>See "PKICredentialMapReaderMBean" in the MBean Reference for Oracle WebLogic Server. |
UserPasswordCredentialMapEditorMBean |
Provides a set of methods for creating, editing, and removing a credential map that matches WebLogic users to remote usernames and their corresponding passwords. A Credential Mapping provider MBean can optionally extend this MBean. See "UserPasswordCredentialMapEditorMBean" in the MBean Reference for Oracle WebLogic Server. |
UserPasswordCredentialMapExtendedReaderMBean |
Provides a set of methods for reading credentials and credential mappings. Credential mappings match WebLogic users to remote usernames and passwords. A Credential Mapping provider MBean can optionally extend this MBean. See "UserPasswordCredentialMapExtendedReaderMBean" in the MBean Reference for Oracle WebLogic Server. |
UserPasswordCredentialMapReaderMBean |
Provides a set of methods for reading credentials and credential mappings. Credential mappings match WebLogic users to remote usernames and passwords. A Credential Mapping provider MBean can optionally extend this MBean. See "UserPasswordCredentialMapReaderMBean" in the MBean Reference for Oracle WebLogic Server. |
ImportMBean |
Provides a set of methods for importing provider specific data. An optional mixin interface that any security provider may extend. See "ImportMBean" in the MBean Reference for Oracle WebLogic Server |
ExportMBean |
Provides a set of methods for exporting provider specific data. An optional mixin interface that any security provider may extend. See "ExportMBean" in the MBean Reference for Oracle WebLogic Server |
ListerMBean |
Provides a general mechanism for returning lists. Derived MBeans extend this interface to add methods that access the data of the current object in the list. An optional mixin interface that any security provider may extend. See "ListerMBean" in the MBean Reference for Oracle WebLogic Server |
NameListerMBean |
Defines a method used to return lists of names. An optional mixin interface that any security provider may extend. See "NameListerMBean" in the MBean Reference for Oracle WebLogic Server |
LDAPServerMBean |
Provides methods to get configuration parameters needed for connecting to an external LDAP server. An optional mixin interface that any security provider may extend. See "LDAPServerMBean" in the MBean Reference for Oracle WebLogic Server |
ApplicationVersionerMBean |
The SSPI MBean that security providers extend to indicate that the provider supports versionable applications. An optional mixin interface that a RoleMapper, Authorizer, or CredentialMapper provider MBean may extend. See "ApplicationerVersionMBean" in the MBean Reference for Oracle WebLogic Server |
When using JMX to manage security realms, you must use two different MBean servers depending on your task:
To set the value of a security MBean attribute, you must use the Edit MBean Server.
To add users, groups, roles, and policies, or to invoke other operations in a security provider MBean, you must use a Runtime MBean Server or the Domain Runtime MBean Server.
In addition, to prevent the possibility of incompatible changes, you cannot invoke operations in security provider MBeans if your client or another JMX client has an edit session currently active.
For example, the value of the MinimumPasswordLength
attribute in DefaultAuthenticatorMBean
is stored in the domain's configuration document. Because all modifications to this document are controlled by WebLogic Server, to change the value of this attribute you must use the Edit MBean Server and acquire a lock on the domain's configuration. The createUser
operation in DefaultAuthenticatorMBean
adds data to an LDAP server, which is not controlled by WebLogic Server. To prevent incompatible changes between the DefaultAuthenticatorMBean
's configuration and the data that it uses in the LDAP server, you cannot invoke the createUser
operation if you or other users are in the process of modifying the MinimumPasswordLength
attribute. In addition, because changing this attribute requires you to restart WebLogic Server, you cannot invoke the createUser
operation until you have restarted the server.
Because security providers can extend optional mix-in interfaces, not all security providers can perform all tasks. This flexibility enables your organization's security architect to design a realm for your security needs. The flexibility also makes the design of your JMX clients dependent upon the design and configuration of each realm.
For example, some realms might contain three types of Authentication providers:
One that extends UserEditorMBean
to save administrative users to an LDAP server
One that extends UserEditorMBean
to save customers to a database management system
One that does not extend UserEditorMBean
and is used only to authenticate existing users
To work with the Authentication providers in this realm, your JMX client must be able to determine which one can add users to the appropriate repository.
Table 6-4 discusses techniques for finding a security provider that is appropriate for your task.
Table 6-4 Finding a Provider in the Realm
Technique | Description |
---|---|
Find by name |
Each security provider instance is assigned a short name when an administrator configures it for the realm. Your JMX client can look up all providers of a specific type (such as all Authentication providers) and choose the one that matches a name. If you use this technique, consider saving the name of the security provider in a configuration file instead of hard-coding it in your JMX client. The configuration file enables system administrators to change the providers in the realm and update the properties file instead of requiring you to update and recompile the JMX client. |
Find by MBean type |
If the system administrator always wants to use the same type of provider for a task, then your JMX client can find the provider MBean that is of the specified type. For example, if the system administrator always wants to use a While this technique requires no user input, it assumes:
|
Use any provider that extends the mix-in interface you need |
You can create a JMX client that learns about the class hierarchy for each provider MBean instance and chooses an instance that extends the mix-in interface you need for your task. For example, your client can discover which Authentication provider extends Use this technique if you know that your security realm will contain only one MBean that extends the needed mix-in interface, or if it does not matter which one you use. |
To create a JMX client that finds MBeans by type or mix-in interface:
Connect to a WebLogic Server Runtime MBean Server. See Make Remote Connections to an MBean Server.
All WebLogic Server instances maintain their own Runtime MBean Server, and you can connect to any server's Runtime MBean Server.
Get all security provider MBeans of a specific type in the realm (for example, get all Authentication provider MBeans):
Use either the RuntimeServiceMBean
or DomainRuntimeServiceMBean
to navigate the following path through the WebLogic Server MBean hierarchy:
DomainMBean
to SecurityConfigurationMBean
to RealmMBean
.
Get the value of the RealmMBean
attribute that contains instances of the security provider type.
For example, to get all Authentication providers, get the value of the RealmMBean
AuthenticationProviders
attribute.
For each security provider MBean in the RealmMBean
attribute, get the name of the MBean's class (see Example 6-1):
Get the provider MBean's javax.management.ModelMBeanInfo
object.
Use MBeanServerConnection.getMBeanInfo(
Provider-MBean
)
where Provider-MBean
is a provider MBean that you retrieved from RealmMBean
.
Get the MBean info's javax.management.Descriptor
object, and then get the value of the Descriptor's interfaceClassName
field.
Use the WebLogic Server MBean type service to find all security provider MBean classes that extend a particular base type or mix-in interface (see Example 6-1):
Determine the fully-qualified interface name of the base type or mix-in interface.
Each entry in the MBean Reference for Oracle WebLogic Server lists the fully-qualified interface name of WebLogic Server provider MBeans. If you use a third-party provider, refer to the third-party documentation for this information.
For example, the fully-qualified interface name of the UserEditorMBean
mix-in interface is weblogic.management.security.authentication.UserEditorMBean
. (See "UserEditorMBean" in the MBean Reference for Oracle WebLogic Server.)
Construct the MBeanTypeService
MBean's object name.
The MBeanTypeService
MBean is always registered under the following javax.management.ObjectName
:
com.bea:Name=MBeanTypeService,Type=weblogic.management.mbeanservers.MBeanTypeService
Invoke the MBeanTypeService
MBean's getSubtypes(java.lang.String
beanInterface
)
operation, where beanInterface
represents the fully-qualified interface name that you determined in Step 1.
The operation returns an array of java.lang.String
objects.
Compare the output of the MBean type service with the class name of each provider MBean instance (see Example 6-1).
If the provider MBean's class implements or extends the interface from step 4a, invoke operations on the provider MBean.
Example 6-1 Example: Determine If a Provider MBean Instance Extends UserEditorMBean Mix-In Interface
ObjectName MBTservice = new ObjectName( "com.bea:Name=MBeanTypeService,Type=weblogic.management.mbeanservers. MBeanTypeService"); for (int p = 0; atnProviders != null && p < atnProviders.length; p++) { ModelMBeanInfo info = (ModelMBeanInfo) mBeanServerConnection.getMBeanInfo(atnProviders[p]); Descriptor desc = info.getMBeanDescriptor(); String className = (String)desc.getFieldValue("interfaceClassName"); String[] mba = (String[]) mBeanServerConnection.invoke( MBTservice, "getSubtypes", new Object[] { "weblogic.management.security.authentication.UserEditorMBean" }, new String[] { "java.lang.String" }); boolean isEditor = false; for (int i = 0; i < mba.length; i++) { if (mba[i].equals(className)){ userEditor = atnProviders[p]; isEditor = true; break; } if (isEditor = true) break; } }
The code example in Example 6-2 adds a user to a security realm and adds the user to the Administrators
group by searching through all of the authentication providers in the realm and using the first one that extends UserEditorMBean
.
Note the following about the code example:
The user name and password come from a JavaBean that was created from an Apache Struts action.
The code does not need to lock the domain's configuration because it is not modifying the configuration of the security MBean itself. Instead, it is invoking an operation in the default Authorization provider which saves security data in an LDAP server.
Example 6-2 Example: Adding Users to a Realm
public ActionForward createNewAdmin(ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response) throws ClientException, Exception { logger.info("Create New Admin"); CreateAdminBean user = (CreateAdminBean) form; logger.debug(user.toString()); MBeanServerConnection mBeanServerConnection = this.getDomainMBeanServerConnection(request); ObjectName service = new ObjectName("com.bea:Name=DomainRuntimeService,"+ "Type=weblogic.management.mbeanservers.domainruntime. DomainRuntimeServiceMBean"); ObjectName domainMBean = (ObjectName) mBeanServerConnection.getAttribute(service, "DomainConfiguration"); ObjectName securityConfiguration = (ObjectName) mBeanServerConnection.getAttribute(domainMBean, "SecurityConfiguration"); ObjectName defaultRealm = (ObjectName) mBeanServerConnection. getAttribute(securityConfiguration, "DefaultRealm"); ObjectName[] atnProviders = (ObjectName[]) mBeanServerConnection.getAttribute(defaultRealm, "AuthenticationProviders"); ObjectName userEditor = null; ObjectName MBTservice = new ObjectName( "com.bea:Name=MBeanTypeService,Type=weblogic.management.mbeanservers. MBeanTypeService"); for (int p = 0; atnProviders != null && p < atnProviders.length; p++) { ModelMBeanInfo info = (ModelMBeanInfo) mBeanServerConnection.getMBeanInfo(atnProviders[p]); Descriptor desc = info.getMBeanDescriptor(); String className = (String)desc.getFieldValue("interfaceClassName"); String[] mba = (String[]) mBeanServerConnection.invoke( MBTservice, "getSubtypes", new Object[] { "weblogic.management.security.authentication.UserEditorMBean" }, new String[] { "java.lang.String" }); boolean isEditor = false; for (int i = 0; i < mba.length; i++) { if (mba[i].equals(className)){ userEditor = atnProviders[p]; isEditor = true; break; } if (isEditor = true) break; } } try { mBeanServerConnection.invoke( userEditor, "createUser", new Object[] {user.getUsername(), user.getPassword(), "MedRec Admininistator"}, new String[] {"java.lang.String", "java.lang.String", "java.lang.String"} ); } catch (MBeanException ex) { Exception e = ex.getTargetException(); if (e instanceof AlreadyExistsException) { logger.info("User, " + user.getUsername() + ", already exists."); ActionErrors errors = new ActionErrors(); errors.add("invalidUserName", new ActionError("invalid.username.already.exists")); saveErrors(request, errors); return mapping.findForward("create.new.admin"); } else { logger.debug(e); return mapping.findForward("create.new.admin"); } } try { mBeanServerConnection.invoke( userEditor, "addMemberToGroup", new Object[] {"Administrators", user.getUsername()}, new String [] {"java.lang.String", "java.lang.String"} ); mBeanServerConnection.invoke( userEditor, "addMemberToGroup", new Object[] {"MedRecAdmins", user.getUsername()}, new String [] {"java.lang.String", "java.lang.String"} ); } catch (MBeanException ex) { Exception e = ex.getTargetException(); if (e instanceof NameNotFoundException) { logger.info("Invalid Group Name."); ex.printStackTrace(); return mapping.findForward("create.new.admin"); } else { logger.debug(e); return mapping.findForward("create.new.admin"); } } logger.info("MedRec Administrator successfully created."); return mapping.findForward("create.new.admin.successful"); }
While security provider MBeans handle specific aspects of security, such as authentication and authorization, two other MBeans handle general, realm-wide and domain-wide aspects of security:
RealmMBean
represents a security realm. JMX clients can use it to add or remove security providers and to specify such behaviors as whether Web and EJB containers call the security framework on every access or only when security is set in the deployment descriptors.
SecurityConfigurationMBean
specifies domain-wide security settings such as connection filters and URL-pattern matching behavior for security constraints, servlets, filters, and virtual-hosts in the WebApp container and external security policies.
These two MBeans persist their data in WebLogic Server configuration files. Therefore, to modify attribute values in RealmMBean
or SecurityConfigurationMBean
, you must use the Edit MBean Server and ConfigurationManagerMBean
as described in Chapter 5, "Managing a Domain's Configuration with JMX."