bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Server > Developing Security Providers for WebLogic Server > Auditing Providers |
Developing Security Providers for WebLogic Server |
Auditing is the process whereby information about operating requests and the outcome of those requests are collected, stored, and distributed for the purposes of non-repudiation. In WebLogic Server, an Auditing provider provides this electronic trail of computer activity.
The following sections describe Auditing provider concepts and functionality, and provide step-by-step instructions for developing a custom Auditing provider:
Note: If you are looking for information about how to write out audit events from a custom security provider, see Auditing Events From Custom Security Providers.
Before you develop an Auditing provider, you need to understand the following concepts:
How Auditing Providers Work With the WebLogic Security Framework and Other Types of Security Providers
Figure 9-1 shows how Auditing providers interact with the WebLogic Security Framework and other types of security providers (using Authentication providers as an example). An explanation follows.
Figure 9-1 Auditing Providers, the WebLogic Security Framework, and Other Security Providers
Auditing providers interact with the WebLogic Security Framework and other types of security providers in the following manner:
Note: In Figure 9-1 and the explanation below, the "other types of security providers" are a WebLogic Authentication provider and a custom Authentication provider. However, these can be any type of security provider that is developed as described in Auditing Events From Custom Security Providers.
Note: An AuditEvent class is created by implementing either the AuditEvent SSPI or an AuditEvent convenience interface in the Authentication provider's runtime class, in addition to the other security service provider interfaces (SSPIs) the custom Authentication provider must already implement. For more information about Audit Events and the AuditEvent SSPI/convenience interfaces, see Create an Audit Event.
Note: This is a trusted call because the Auditor Service is already passed to the security provider's initialize method as part of its "Provider" SSPI implementation. For more information, see Understand the Purpose of the "Provider" SSPIs.
Note: For more information about audit severity levels and the Audit Context, see Audit Severity and Audit Context, respectively.
An Audit Channel is the component of an Auditing provider that determines whether a security event should be audited, and performs the actual recording of audit information based on Quality of Service (QoS) policies.
Note: For more information about Audit Channels, see Implement the AuditChannel SSPI.
Do You Need to Develop a Custom Auditing Provider?
The default (that is, active) security realm for WebLogic Server includes a WebLogic Auditing provider. The WebLogic Auditing provider records information from a number of security requests, which are determined internally by the WebLogic Security Framework. The WebLogic Auditing provider also records the event data associated with these security requests, and the outcome of the requests.
The WebLogic Auditing provider makes an audit decision in its writeEvent method, based on the audit severity level it has been configured with and the audit severity contained within the AuditEvent object that is passed into the method. (For more information about AuditEvent objects, see Create an Audit Event.
Note: You can change the audit severity level that the WebLogic Auditing provider is configured with using the WebLogic Server Administration Console. For more information, see "Configuring a WebLogic Auditing Provider" in Managing WebLogic Security.
If there is a match, the WebLogic Auditing provider writes audit information to the DefaultAuditRecorder.log file, which is located in the bea_home\user_projects\domain directory (where bea_home represents the central support directory for all BEA products installed on one machine, and domain represents the name of a domain you create). Listing 9-1 is an excerpt from the DefaultAuditRecorder.log file.
Listing 9-1 DefaultAuditRecorder.log File: Sample Output
#### Audit Record Begin <Jun 12, 2002 4:55:21 PM> <Severity=INFORMATION>
<<<Event Type=RoleManager Audit Event><Subject:2 Principal=class
weblogic.security.principal.WLSUserImpl("installadministrator") Principal=class
weblogic.security.principal.WLSGroupImpl("Administrators")><<web>><type=<web>,
application=_appsdir_certificate_war, uri=certificate.war,
webResource=CertificateServlet, httpMethod=GET><>>> Audit Record End ####
Specifically, Listing 9-1 shows the Role Manager (a component in the WebLogic Security Framework that deals specifically with roles) recording an audit event to indicate that an authorized administrator has accessed a protected method in a certificate servlet.
Each time the WebLogic Server instance is booted, a new DefaultAuditRecorder.log file is created (the old DefaultAuditRecorder.log file is renamed to DefaultAuditRecorder.log.old).
If you want to write audit information in addition to that which is specified by the WebLogic Security Framework, or to an output repository that is not the DefaultAuditRecorder.log (that is, to a simple file with a different name/location or to an existing database), then you need to develop a custom Auditing provider.
How to Develop a Custom Auditing Provider
If the WebLogic Auditing provider does not meet your needs, you can develop a custom Auditing provider by following these steps:
Create Runtime Classes Using the Appropriate SSPIs
Before you start creating runtime classes, you should first:
When you understand this information and have made your design decisions, create the runtime classes for your custom Auditing provider by following these steps:
For an example of how to create a runtime class for a custom Auditing provider, see Example: Creating the Runtime Class for the Sample Auditing Provider.
Implement the AuditProvider SSPI
To implement the AuditProvider SSPI, provide implementations for the methods described in Understand the Purpose of the "Provider" SSPIs and the following method:
For more information about the AuditProvider SSPI and the getAuditChannel method, see the WebLogic Server 7.0 API Reference Javadoc.
Implement the AuditChannel SSPI
To implement the AuditChannel SSPI, provide an implementation for the following method:
For more information about the AuditChannel SSPI and the writeEvent method, see the WebLogic Server 7.0 API Reference Javadoc.
Example: Creating the Runtime Class for the Sample Auditing Provider
Listing 9-2 shows the SampleAuditProviderImpl.java class, which is the runtime class for the sample Auditing provider. This runtime class includes implementations for:
Note: The bold face code in Listing 9-2 highlights the class declaration and the method signatures.
Listing 9-2 SampleAuditProviderImpl.java
package examples.security.providers.audit;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.PrintStream;
import weblogic.management.security.ProviderMBean;
import weblogic.security.spi.AuditChannel;
import weblogic.security.spi.AuditEvent;
import weblogic.security.spi.AuditProvider;
import weblogic.security.spi.SecurityServices;
public final class SampleAuditProviderImpl implements AuditChannel, AuditProvider
{
private String description;
private PrintStream log;
public void initialize(ProviderMBean mbean, SecurityServices services)
{
System.out.println("SampleAuditProviderImpl.initialize");
description = mbean.getDescription() + "\n" + mbean.getVersion();
SampleAuditorMBean myMBean = (SampleAuditorMBean)mbean;
File file = new File(myMBean.getLogFileName());
System.out.println("\tlogging to " + file.getAbsolutePath());
try {
log = new PrintStream(new FileOutputStream(file), true);
} catch (IOException e) {
throw new RuntimeException(e.toString());
}
}
public String getDescription()
{
return description;
}
public void shutdown()
{
System.out.println("SampleAuditProviderImpl.shutdown");
log.close();
}
public AuditChannel getAuditChannel()
{
return this;
}
public void writeEvent(AuditEvent event)
{
// Write the event out to the sample Auditing provider's log file using
// the event's "toString" method.
log.println(event);
}
}
Generate an MBean Type Using the WebLogic MBeanMaker
Before you start generating an MBean type for your custom security provider, you should first:
When you understand this information and have made your design decisions, create the MBean type for your custom Auditing provider by following these steps:
Notes: Several sample security providers (available under "Code Direct" on the dev2dev Web site) illustrate how to perform these steps.
All instructions provided in this section assume that you are working in a Windows environment.
Create an MBean Definition File (MDF)
To create an MBean Definition File (MDF), follow these steps:
Note: A complete reference of MDF element syntax is available in MBean Definition File (MDF) Element Syntax.
Use the WebLogic MBeanMaker to Generate the MBean Type
Once you create your MDF, you are ready to run it through the WebLogic MBeanMaker. The WebLogic MBeanMaker is currently a command-line utility that takes as its input an MDF, and outputs some intermediate Java files, including an MBean interface, an MBean implementation, and an associated MBean information file. Together, these intermediate files form the MBean type for your custom security provider.
The instructions for generating an MBean type differ based on the design of your custom Auditing provider. Follow the instructions that are appropriate to your situation:
If the MDF for your custom Auditing provider does not include any custom operations, follow these steps:
java -DMDF=xmlfile -DFiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.
Whenever xmlfile is provided, a new set of output files is generated. If files already exist in the location specified by filesdir, you are informed that the existing files will be overwritten and are asked to confirm.
Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.
If the MDF for your custom Auditing provider does include custom operations, consider the following:
java -DMDF=xmlfile -DFiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.
Whenever xmlfile is provided, a new set of output files is generated. If files already exist in the location specified by <filesdir>, you are informed that the existing files will be overwritten and are asked to confirm.
Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.
java -DMDF=xmlfile -DFiles=filesdir -DcreateStubs=true weblogic.management.commo.WebLogicMBeanMaker
where xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.
Whenever xmlfile is provided, a new set of output files is generated. If files already exist in the location specified by filesdir, you are informed that the existing files will be overwritten and are asked to confirm.
Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.
About the Generated MBean Interface File
The MBean interface file is the client-side API to the MBean that your runtime class or your MBean implementation will use to obtain configuration data. It is typically used in the initialize method as described in Understand the Purpose of the "Provider" SSPIs.
Because the WebLogic MBeanMaker generates MBean types from the MDF you created, the generated MBean interface file will have the name of the MDF, plus the text "MBean" appended to it. For example, the result of running the SampleAuditor MDF through the WebLogic MBeanMaker will yield an MBean interface file called SampleAuditorMBean.java.
Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)
Once your have run your MDF through the WebLogic MBeanMaker to generate your intermediate files, and you have edited the MBean implementation file to supply implementations for the appropriate methods within it, you need to package the MBean files and the runtime classes for the custom Auditing provider into an MBean JAR File (MJF). The WebLogic MBeanMaker also automates this process.
To create an MJF for your custom Auditing provider, follow these steps:
java -DMJF=jarfile -DFiles=filesdir weblogic.management.commo.WebLogicMBeanMaker
where jarfile is the name for the MJF and <filesdir> is the location where the WebLogic MBeanMaker looks for the files to JAR into the MJF.
Compilation occurs at this point, so errors are possible. If jarfile is provided, and no errors occur, an MJF is created with the specified name.
Notes: If you want to update an existing MJF, simply delete the MJF and regenerate it. The WebLogic MBeanMaker also has a -DIncludeSource option, which controls whether source files are included into the resulting MJF. Source files include both the generated source and the MDF itself. The default is false. This option is ignored when -DMJF is not used.
The resulting MJF can be installed into your WebLogic Server environment, or distributed to your customers for installation into their WebLogic Server environments.
Install the MBean Type Into the WebLogic Server Environment
To install an MBean type into the WebLogic Server environment, copy the MJF into the WL_HOME\server\lib\mbeantypes directory, where WL_HOME is the top-level installation directory for WebLogic Server. This "deploys" your custom Auditing provider—that is, it makes the custom Auditing provider manageable from the WebLogic Server Administration Console.
You can create instances of the MBean type by configuring your custom Auditing provider (see Configure the Custom Auditing Provider Using the Administration Console), and then use those MBean instances from a GUI, from other Java code, or from APIs. For example, you can use the WebLogic Server Administration Console to get and set attributes and invoke operations, or you can develop other Java objects that instantiate MBeans and automatically respond to information that the MBeans supply. We recommend that you back up these MBean instances. For more information, see "Backing Up Security Configuration Data" under "Recovering Failed Servers" in Creating and Configuring WebLogic Server Domains.
Configure the Custom Auditing Provider Using the Administration Console
Configuring a custom Auditing provider means that you are adding the custom Auditing provider to your security realm, where it can be accessed by security providers requiring audit services.
Configuring custom security providers is an administrative task, but it is a task that may also be performed by developers of custom security providers. This section contains information that is important for the person configuring your custom Auditing providers:
Note: The steps for configuring a custom Auditing provider using the WebLogic Server Administration Console are described under "Configuring a Custom Security Provider" in Managing WebLogic Security.
During the configuration process, an Auditing provider's audit severity must be set to one of the following severity levels:
This severity represents the level at which the custom Auditing provider will initiate auditing.