Configuring Security for a WebLogic Domain

3 Configuring Security for a WebLogic Domain

Configuring security for an Oracle WebLogic Server environment starts with a creating a secure installation of WebLogic Server. It also includes choosing the security configuration options that are appropriate for the environment in which the domain runs, such as obtaining and storing certificates, protecting user accounts, and securing the network on which the domain runs.

This chapter includes the following sections:

For a complete checklist of all components in the WebLogic Server that should be secured in a production environment, including specific tasks recommended for configuring a secure domain, securing the network, files and databases used by WebLogic Server, see Lock Down WebLogic Server in Securing a Production Environment for Oracle WebLogic Server.

Performing a Secure Installation of WebLogic Server

Performing a secure installation includes steps to secure the host machine on which WebLogic Server is installed, to limit access to that host to only authorized users, and to install Critical Patch Updates immediately after installation is complete.

If you are installing WebLogic Server in a production environment, Oracle strongly recommends the guidelines described in the following sections:

Before Installing WebLogic Server

Before you start the WebLogic Server installation program, complete the following tasks:

Create a My Oracle Support account so that you can register your WebLogic Server installation with Oracle and receive security updates automatically. Visit http://www.oracle.com/support/index.html.
Secure the host machine, operating system, and file system to ensure that access is restricted only to authorized users. For example:
- Keep your hardware in a secured area to prevent unauthorized operating system users from gaining access to the machine and its network connections.
- Make sure the host machine has the latest operating system patches and security updates.
  
  Note:
  
  As new patches become available, you should download and install them promptly.
Secure networking services and the file system that the operating system provides to prevent unauthorized access. For example, make sure that any file system sharing is secured.
Set operating system file access permissions to restrict access to data stored on disk that will be used or managed by WebLogic Server, such as the security LDAP database and directories into which keystores are created and managed.
Limit the number of user accounts on the host machine. Create a group to contain only the following user accounts:
1. The user who installs WebLogic Server only.
2. The user who creates the WebLogic domain and uses Node Manager to start the Administration Server and each Managed Server instance in the domain.
Restrict the privileges of these user accounts to only the following directories:
- Oracle home — Root directory created for all Oracle Fusion Middleware products on a host computer
- WebLogic home — Root directory of the WebLogic Server installation
- Domain home — Root directory of the WebLogic domain
Note:

Some processes also need access to temporary directories by default, such as /tmp on Unix platforms. If the privileges of a user account are restricted to only the Oracle home, WebLogic home, and WebLogic domain directories, the user must change environment variables, such as TEMP or TMP, to point to a directory to which that user does have access.
Ensure that any Web servers on the host machine run only as an unprivileged user, never as root.
Ensure no software development tools or sample software is installed.
Consider using additional software to secure your operating system, such as a reputable intrusion detection system (IDS).

See Secure the Host Environment in Securing a Production Environment for Oracle WebLogic Server.

While Running the Installation Program

During installation, make sure that you do not install the sample applications component.

Immediately After Installation is Complete

Remove the Derby DBMS database, which is bundled with WebLogic Server for use by the sample applications and code examples as a demonstration database. Derby DBMS is located in the WL_HOME/common/derby directory.
Visit the Critical Patch Updates, Security Alerts and Bulletins page at the following location to review WebLogic Server security advisories:

https://www.oracle.com/security-alerts/

See the following topics in Securing a Production Environment for Oracle WebLogic Server:

Creating a WebLogic Domain for Production Use

To create a WebLogic domain for production use, consider the environment in which the domain will run, such as whether it will interoperate with other WebLogic domains, and how best to secure the accounts of users who have access to the domain.

When configuring a WebLogic domain for use in a production environment, using tools such as the Configuration Wizard, the pack/unpack commands, WLST, or the WebLogic Server Administration Console, consider the following:

Configure the domain to run in either production mode or secured production mode. The domain mode determines default settings regarding security and logging.

In production mode, the security configuration is relatively stringent, such as requiring a user name and password to deploy applications and start the Administration Server. If you are using the unpack command to create a full WebLogic domain, or a subset of a domain that is used for a Managed Server domain directory on a remote machine, use the -server_start_mode=prod parameter to configure production mode.
In secured production mode, your production environment is more secure as the authorization and role mapping policies are more restrictive, and warnings are logged for insecure configuration settings in your domain. Note that in order to enable secured production mode, your domain must be in production mode. You can enable secured production mode using the WebLogic Server Administration Console, Fusion Middleware Control or WLST (offline and online). Refer to the following topics for more information about using these tools to enable secured production mode:
- See Secure your production domain in the Oracle WebLogic Server Administration Console Online Help for information about enabling secured production mode and related security settings using the Administration Console.
- Use the setOption WLST offline command while creating a domain, and set the ServerStartMode argument to secure to create a domain in secured production mode. See setOption in WLST Command Reference for Oracle WebLogic Server.
- See Using WLST Online to Update an Existing WebLogic Domain in Understanding the WebLogic Scripting Tool to learn how to change your domain environment from production mode to secured production mode.
- See Configure domain security in Administering Oracle WebLogic Server with Fusion Middleware Control to enable secured production mode and related security settings using Fusion Middleware Control.
Note:
It is possible to change the domain mode from development to production, production to development, and from production to secured production mode. However, it is important to remember that to enable secured production mode, your domain must be in production mode.
For production environments with more stringent security requirements, Oracle recommends setting the production domain mode at the time you create the domain (as opposed to changing a development mode domain to production mode). See Development and Production Modes in Understanding Domain Configuration for Oracle WebLogic Server for more information about how to modify domain modes.
If the domain will interoperate with other WebLogic domains, or has the potential for that use at some future point, choose resource names carefully. Many resource names are fixed at the time a domain is created, and stringent requirements must be observed for resource names when using Cross-Domain Security, transactions, and messaging.

See Requirements for Transaction Communication in Developing JTA Applications for Oracle WebLogic Server.
When creating domains using WLST, do not enter unencrypted passwords in commands for configuring entities that require them, such as passwords for:
- Domain administrator
- Node Manager user
- Database user
- JKS keystores (both when creating the keystores and again when configuring them with WebLogic Server)
- Wallet
Specifying unencrypted passwords in WLST commands is a security risk: they can be easily viewed from the monitor screen by others, and they are displayed in process listings that log the execution of those commands. Instead, omit the password from the command. When the command is executed, WLST automatically prompts you for any passwords needed to complete the domain configuration.

Securing the Domain After You Have Created It

After you have created your WebLogic domain, several key steps remain to ensure its integrity such as selecting an appropriate domain mode, limiting access to internal applications, and configuring a Password Validation provider. To secure a domain after you have created it, Oracle recommends the following steps:

Secure your production environment by enabling secured production mode for your domain. Your domain must be in production mode to enable secured production mode. In this mode, the secure values override the production mode default values, and the default authorization and security policies are more restrictive. WebLogic Server validates all security settings and logs warnings in case of insecure settings, thereby, providing a highly secure production environment. See Secure your production domain in the Oracle WebLogic Server Administration Console Online Help to learn how to change your domain mode to secured production mode.
Limit access to internal applications by disabling unused internal applications using either the configuration settings or the system property. Enable the Administration port for your domain, and configure a firewall to prevent external access to internal applications on the Administration port. In secured production mode, the Administration port is enabled by default. For information about how to disable internal applications, see Disable Unused Internal Applications in Securing a Production Environment for Oracle WebLogic Server.
Configure the Password Validation provider to manage and enforce password composition rules. The Password Validation provider is configured out-of-the-box to work with several WebLogic authentication providers.

See Configuring the Password Validation Provider.
As you create or add users to the security realm, check that the User Lockout options on user accounts are set for maximum protection. Note that the configuration of User Lockout is defined on a per realm basis. Therefore, if the default User Lockout settings are not suitable for your needs, you might need to customize these settings whenever you create a new security realm. See Protecting User Accounts and How Passwords Are Protected in WebLogic Server.

If your domain is running in secured production mode, then WebLogic Server logs a warning if the user lockout is configured to a value less than the default value.
If you have configured Node Manager to start, shut down, and restart the Administration Server and Managed Server instances distributed across multiple machines, make sure that Node Manager security is properly configured.

If you are using Java Node Manager (recommended for production environments), see Configuring Java-based Node Manager Security in Administering Node Manager for Oracle WebLogic Server.

If you are using Script Node Manager, which may be suitable for environments that have less stringent security requirements, see Step 2: Configure Node Manager Security in Administering Node Manager for Oracle WebLogic Server.
Enable auditing, which provides an automated way of collecting and storing information about events and other activity occurring in the system. Auditing is available through either of the following means:
- Configuration auditing — When this is enabled, the Administration Server emits log messages and generates audit events when a user changes the configuration of any resource within a domain or invokes management operations on any resource within a domain.
- WebLogic Auditing provider — Optional security provider that collects, stores, and distributes information about operating requests and the outcome of those requests for the purposes of non-repudiation. When configuration auditing is enabled, the WebLogic Auditing provider also logs configuration auditing events.
Note that auditing may impose a performance overhead that should be taken into consideration. However, by adjusting how auditing is configured, this additional overhead can be minimized. When enabling auditing, make sure that sufficient disk space is available for the audit log. See Configuring the WebLogic Auditing Provider.

Note:
If secured production mode is enabled for your domain, then WebLogic Server logs a warning if an Auditing provider is not configured. You can use the WarnOnAuditing attribute in the SecureModeMBean to specify whether warnings should be logged or not if auditing is not enabled.
Make sure that the JVM platform MBean server cannot be accessed remotely. See "Monitoring and Management Using JMX Technology" at http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html.
If you have a requirement to comply with Federal Information Processing Standards (FIPS) 140-2, complete the appropriate procedures described in Enabling FIPS Mode.
Make sure configuration settings for complete message time out are sized appropriately for your system. See Configuring Network Resources in Administering Server Environments for Oracle WebLogic Server.
Create and configure the keystores used for holding identity and trust; that is, the keystores containing identity certificates and the keystore containing trusted Certificate Authority (CA) certificates. See Configuring Keystores.
If you are using the Oracle OPSS Keystore Service (KSS) for use with WebLogic Server, see Configuring Oracle OPSS Keystore Service.

Configure certificate validation and revocation checking to ensure that:
- Each certificate in a certificate chain was issued by a certificate authority, as explained in SSL Certificate Validation.
- The revocation status of each certificate WebLogic Server validates is current. See X.509 Certificate Revocation Checking.
Configure a host name verifier. When making an SSL connection, the host name verifier ensures that the host name in the URL to which the client connects matches the host name in the digital certificate that the server sends back. See Using Host Name Verification.
If your domain is running in secured production mode, then WebLogic Server logs a warning if host name verification is disabled. To enable host name verification, see Configure a custom host name verifier in the Oracle WebLogic Server Administration Console Online Help.

Configure SSL for the administration port, network channels, database connections, LDAP server connections, and other resources handling communication that must be secured. In particular, make sure that connections to remote server instances in the domain are secured with SSL. The specific components for which either one- or two-way SSL needs to be configured depends on the overall topology of the production environment. See the following topics:

Table 3-1 SSL Configuration Topics

For information about . . .	See the following topic. . .
An overview of using SSL to secure communications in a basic WebLogic domain	Secure Sockets Layer (SSL) in Understanding Security for Oracle WebLogic Server
Where to use one-way and two-way SSL in a basic WebLogic domain	One-way/Two-way SSL Authentication in Understanding Security for Oracle WebLogic Server
Steps to configure SSL in a basic WebLogic domain	Setting Up SSL: Main Steps
Configuring an administration port for secure communication with the domain Administration Server	Administration Port and Administrative Channel in Administering Server Environments for Oracle WebLogic Server
Securing database connections	Understanding Data Source Security in Administering JDBC Data Sources for Oracle WebLogic Server
An overview of using SSL in Oracle Fusion Middleware to secure components in web, middle, and data tiers	About SSL in Oracle Fusion Middleware in Administering Oracle Fusion Middleware
Best practices for configuring SSL in WebLogic Server	"Section 2. Security Best Practices" in Document ID 1074055.1, available from My Oracle Support at `https://support.oracle.com/`

Note:

Note the following:

By default, WebLogic Server is configured for one-way SSL authentication; however, the SSL port is disabled. Oracle strongly recommends enabling the SSL port in all server instances in a production domain.
The demonstration digital certificates, private keys, and trusted CA certificates provided in WebLogic Server should never be used in a production environment.
In secured production mode, WebLogic Server logs warnings if the SSL configuration is not secure. You can use the WarnOnInsecureSSL attribute contained in the SecureModeMBean to specify whether warnings should be logged if the SSL configuration is not secure.

Restrict the size and the time limit of requests on external channels to prevent Denial of Service attacks. See Reducing the Potential for Denial of Service Attacks in Tuning Performance of Oracle WebLogic Server.
If you use multiple Authentication providers, be sure to set the JAAS control flag correctly. See Using More Than One Authentication Provider.
Ensure that you have correctly assigned users and groups to the default WebLogic Server security roles. See Users, Groups, And Security Roles in Securing Resources Using Roles and Policies for Oracle WebLogic Server.
Review the Security Warnings Report for any outstanding security validation issues in your domain. See Review Potential Security Issues in Securing a Production Environment for Oracle WebLogic Server.

Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authority Certificates

You have multiple choices for obtaining private keys, digital certificates, and trusted CA certificates for your WebLogic Server environment. Oracle strongly recommends obtaining private keys and digital certificates from a reputed certificate authority. When choosing these items, note the following considerations:

For production environments, Oracle strongly recommends obtaining private keys and digital certificates only from a reputable certificate authority such as Entrust or Symantec Corporation. See Obtaining and Storing Certificates for Production Environments.
For development environments only, you can use the digital certificates, private keys, and trusted CA certificates provided by WebLogic Server. You can also use keytool or the CertGen utility to generate self-signed certificates. See Using Keystores and Certificates in a Development Environment.

Storing Private Keys, Digital Certificates, and Trusted Certificate Authority Certificates

Once you have obtained private keys, digital certificates, and trusted CA certificates, you need to store them so that WebLogic Server can use them to find and verify identity. Private keys, their associated digital certificates, and trusted CA certificates are stored in keystores. Then you need to configure those keystores with WebLogic Server.

For information about . . .	See the following topic . . .
Creating a keystore	Creating a Keystore
Configuring a keystore to be used with WebLogic Server	Configuring Keystores with WebLogic Server
A step-by-step example of using the keytool utility to create a keystore and store keys and certificates in it	Creating a Keystore: An Example
Displaying the certificates contained in a keystore	Viewing Keystore Contents
Updating certificates that are due to expire	Replacing Expiring Certificates
Setting reminders about certificate expiration	Setting Certificate Expiry Notifications

Protecting User Accounts

WebLogic Server provides a set of configuration options to protect user accounts from intruders. In the default security configuration, these options are set for maximum protection. You can use the WebLogic Server Administration Console to modify these options using the Configuration > User Lockout page, which is available for each security realm.

As a system administrator, you have the option of turning off all the configuration options, increasing the number of login attempts before a user account is locked, increasing the time period in which invalid login attempts are made before locking the user account, and changing the amount of time a user account is locked. Remember that changing the configuration options lessens security and leaves user accounts vulnerable to security attacks. See Set user lockout attributes in the Oracle WebLogic Server Administration Console Online Help.

Note:

The User Lockout options apply to the default security realm and all its security providers. User Lockout works in all security realms, is layered on top of all configured providers, including custom ones, and is enabled by default.

If you are using an Authentication provider that has its own mechanism for protecting user accounts, consider if disabling User Lockout on the security realm is appropriate because other Authentication providers might be configured in the security realm.

If a user account becomes locked and you delete the user account and add another user account with the same name and password, the User Lockout configuration options will not be reset.

For information about unlocking a locked user account, see Unlock user accounts in the Oracle WebLogic Server Administration Console Online Help. Unlocking a locked user account can be done through either the WebLogic Server Administration Console or the clearLockout attribute on the UserLockoutManagerRuntimeMBean.

Using Connection Filters

Connection filters allow you to deny access at the network level. They can be used to protect server resources on individual servers, server clusters, or an entire internal network or intranet. For example, you can deny any non-SSL connections originating outside of your corporate network. Network connection filters are a type of firewall in that they can be configured to filter on protocols, IP addresses, and DNS node names.

Connection filters are particularly useful when using the Administration port. Depending on your network firewall configuration, you may be able to use a connection filter to further restrict administration access. A typical use might be to restrict access to the Administration port to only the servers and machines in the WebLogic domain. An attacker who gets access to a machine inside the firewall, still cannot perform administration operations unless the attacker is on one of the permitted machines.

WebLogic Server provides a default connection filter called weblogic.security.net.ConnectionFilterImpl. This connection filter accepts all incoming connections and also provides static factory methods that allow the server to obtain the current connection filter. To configure this connection filter to deny access, simply enter the connection filters rules in the WebLogic Server Administration Console.

You can also use a custom connection filter by implementing the classes in the weblogic.security.net package. For information about writing a connection filter, see Using Network Connection Filters in Developing Applications with the WebLogic Security Service. Like the default connection filter, custom connection filters are configured in the WebLogic Server Administration Console.

To configure a connection filter:

Enable the logging of accepted messages. This Connection Logger Enabled option logs successful connections and connection data in the server. This information can be used to debug problems relating to server connections.
Choose which connection filter is to be used in the domain.
- To configure the default connection filter, specify weblogic.security.net.ConnectionFilterImpl in Connection Filter.
- To configure a custom connection filter, specify the class that implements the network connection filter in Connection Filter. This class must also be specified in the CLASSPATH for WebLogic Server.
Enter the syntax for the connection filter rules.

Refer to the following topics:

See Configure connection filtering in the Oracle WebLogic Server Administration Console Online Help.
For information about connection filter rules and writing a custom connection filter, see Using Network Connection Filters and Developing Custom Connection Filters in Developing Applications with the WebLogic Security Service.
You can also use the WebLogic Scripting Tool or Java Management Extensions (JMX) APIs to create a new security configuration.

Using JEP 290 in Oracle WebLogic Server

To improve security, WebLogic Server uses the JDK JEP 290 mechanism to filter incoming serialized Java objects and limit the classes that can be deserialized. The filter helps to protect against attacks from specially crafted, malicious serialized objects that can cause denial of service (DOS) or remote code execution (RCE) attacks.

There are two models to prevent deserialization exploits: blocklist and allowlist. With the blocklist model, WebLogic Server defines a set of well-known classes and packages that are vulnerable and blocks them from being deserialized and all other classes can be deserialized. In the allowlist model, WebLogic Server and the customer define a list of the acceptable classes and packages that are allowed to be deserialized, and block all other classes. While both approaches have benefits, the allowlist model is more secure because it only allows deserialization of classes and packages known to be required by WebLogic Server and customer applications.

Note:

The October 2021 Patch Set Update (PSU) adds support for allowlists in WebLogic Server in this release.

You have the option of choosing whether to use blocklists or allowlists.

WebLogic Server uses blocklists by default. At startup, WebLogic Server configures a default JEP 290 blocklist filter that specifies the maximum depth of a graph and a set of prohibited classes and packages that cannot be deserialized. You can then use WebLogic Server JEP 290 properties to customize the blocklist to add additional classes or packages. You can also use dynamic blocklists, which provide the ability to update your blocklist filters by creating configuration files that can be updated or replaced while the server is running. See Using Dynamic Blocklist Configuration Files.

Note:

These default blocklist settings, including the set of prohibited classes specified in the default filter, can change over time. WebLogic Server Patch Set Updates (PSUs) may include updates to the set of prohibited classes and packages used in the default filter. To ensure that your system is protected with the most current default filter, be sure to apply the latest WebLogic Server PSUs and Java Critical Patch Updates (CPUs) as soon as they are released. The Critical Patch Updates, Security Alerts and Bulletins page references the latest Java and WebLogic Server updates that are available on My Oracle Support.
Alternatively, you can choose to use allowlists. First, you must create an allowlist that contains the classes and packages that are deserialized in the applications in your domain. To do so, you enable recording, which records all of the classes and packages used in both WebLogic Server and customer application deserialization. When deserialization occurs, each class is recorded in an allowlist configuration file. When you are satisfied with the allowlist, you then configure WebLogic Server to use the allowlist configuration file for the JEP 290 filtering. See Using an Allowlist for JEP 290 Filtering.

JEP 290 filter syntax supports both the blocklist and allowlist models. For JEP 290 filter syntax, see the Process-wide Filter section in http://openjdk.java.net/jeps/290. The configuration files that WebLogic Server uses to either block or allow classes adhere to the JEP 290 syntax. For example, a pattern !foo.bar.Mumble blocks the class foo.bar.Mumble. Classes and packages that are not preceded by the ! are allowed.

WebLogic Server JEP 290 Default Filter Configuration

At startup, WebLogic Server configures a default JEP 290 filter with the following characteristics:

The maximum depth of a graph
A set of prohibited classes and packages that cannot be deserialized

These default settings, including the set of prohibited classes specified in the default filter, can change over time. WebLogic Server Patch Set Updates (PSUs) may include updates to this set of prohibited classes and packages used in the default filter. To ensure that your system is protected with the most current default filter, be sure to apply the latest WebLogic Server PSUs and Java Critical Patch Updates (CPUs) as soon as they are released. The Critical Patch Updates, Security Alerts and Bulletins page references the latest Java and WebLogic Server updates that are available on My Oracle Support.

Customizing JEP 290 Filters Using Properties

WebLogic Server includes properties that you can use to customize, replace, or disable the JEP 290 filters if desired. These properties can be specified on the command line as system properties or contained as properties in the JEP 290 dynamic configuration and allowlist configuration files.

The following table describes the properties and includes sample usage.

Table 3-2 WebLogic Server JEP 290 Properties

Property	Description
`weblogic.oif.serialFilter`	Use this property to set a custom JEP 290 filter for WebLogic Server, using the standard JEP 290 filter syntax. For JEP 290 filter syntax, see the Process-wide Filter section in `http://openjdk.java.net/jeps/290`. By default, this custom filter is combined with the default WebLogic Server filter, with the custom filter taking precedence over the default filter for any filter elements that conflict. If you are using the allowlist model, all blocked classes and packages are given the highest priority in the allowlist filter. For example, to set a custom filter by adding a class named `foo.bar.Mumble` to the default blocklist, use: `-Dweblogic.oif.serialFilter=”!foo.bar.Mumble”` This setting blocks the class `foo.bar.Mumble` even if it is allowed by the default filter.
`weblogic.oif.serialFilterMode`	Use this property to specify the filter mode for the custom filter, which provides the ability to combine, replace, or disable the default WebLogic Server filter. Valid values are: `combine` — combines the custom filter with the default WebLogic Server filter. The custom filter settings take precedence over the default filter settings for any filter elements that conflict. This is the default. If you are using the allowlist model, all blocked classes and packages are given the highest priority in the allowlist filter. `replace` — replaces the default WebLogic Server filter with the custom filter. Oracle recommends that you include all of the blocklist and allowlist classes and packages from the default WebLogic Server filter in your replacement filter. If you do not include them, then your system will not be protected from malicious deserialization attacks. `disable` — disables the default WebLogic Server filter. Oracle strongly recommends that you do not disable the filter. If you do so, then your system will not be protected from malicious deserialization attacks. For example, to replace the default WebLogic Server filter with the custom filter, use: `-Dweblogic.oif.serialFilterMode=replace`
`weblogic.oif.serialFilterScope`	Use this property to specify whether the filter should apply globally to the entire JVM (customer application and third-party library deserialization) or to only internal WebLogic Server deserialization. Valid values are `global` and `weblogic`. The default is `global`. Note: The default is `global` for JDK 7 Update 191 (JDK 7u191) or later and JDK 8 Update 181 (JDK 8u181) or later. For earlier supported JDK versions, the default is `weblogic`. For example, to apply the WebLogic Server default or custom filter to internal WebLogic Server deserialization only, instead of to the entire JVM, use: `-Dweblogic.oif.serialFilterScope=weblogic`
`weblogic.oif.serialGlobalFilter`	Use this property to set a custom JEP 290 global filter for WebLogic Server, using the standard JEP 290 filter syntax. For JEP 290 filter syntax, see the Process-wide Filter section in `http://openjdk.java.net/jeps/290`. By default, this custom global filter is combined with the default WebLogic Server filter, with the custom global filter taking precedence over the default filter for any filter elements that conflict. This global filter applies to object input streams used for application and third party library deserialization, and does not apply to WebLogic Server deserialization For example, to set a custom global filter by adding a class named `foo.bar.Mumble` to the default blocklist, use: `-Dweblogic.oif.serialGlobalFilter=”!foo.bar.Mumble”` This setting blocks the class `foo.bar.Mumble` from deserialization in customer applications and third party libraries, even if it is allowed by the default filter.
`weblogic.oif.head.serialFilter`	Use this property to override a custom JEP 290 filter for WebLogic Server, using the standard JEP 290 filter syntax. For JEP 290 filter syntax, see the Process-wide Filter section in `http://openjdk.java.net/jeps/290`. By default, this head filter is combined with the custom and default WebLogic Server filters, with the head filter taking precedence over both the custom and default filter for any filter elements that conflict. For example, to set a head filter by adding a class named `foo.bar.Mumble` to the allowlist, use: `-Dweblogic.oif.head.serialFilter=”!foo.bar.Mumble”` This setting blocks the class `foo.bar.Mumble` from WebLogic Server deserialization even if it is allowed by the custom and default filters.
`weblogic.oif.head.serialGlobalFilter`	Use this property to override a custom JEP 290 global filter for WebLogic Server, using the standard JEP 290 filter syntax. For JEP 290 filter syntax, see the Process-wide Filter section in `http://openjdk.java.net/jeps/290`. By default, this custom global filter is combined with the custom and default WebLogic Server filters, with the head global filter taking precedence over both the custom and default filter for any filter elements that conflict. This global filter applies to object input streams used for application and third party library deserialization, and does not apply to WebLogic Server deserialization For example, to set a head global filter by adding a class named `foo.bar.Mumble` to the allowlist, use: `-Dweblogic.oif.head.serialGlobalFilter=”!foo.bar.Mumble”` This setting blocks the class `foo.bar.Mumble` from deserialization in customer applications and third party libraries even if it is allowed by the custom and default filters.
`weblogic.oif.serialUnauthenticatedFilter`	Use this property to set a custom JEP 290 filter for the unauthenticated code path of WebLogic Server, using the standard JEP 290 filter syntax. For JEP 290 filter syntax, see the Process-wide Filter section in `http://openjdk.java.net/jeps/290`. Note: This filter is used when you have disabled remote anonymous RMI T3 and IIOP requests. Oracle does not expect that users will need to customize the unauthenticated code path filter. The current set of allowed classes during the unauthenticated code path should be sufficient. By default, this custom filter is combined with the default WebLogic Server unauthenticated filter, with the custom filter taking precedence over the default filter for any filter elements that conflict. For example, to set a custom filter by adding a class named `foo.bar.Mumble` to the default unauthenticated allowlist, use: `-Dweblogic.oif.serialUnauthenticatedFilter="foo.bar.Mumble"` This setting allows the class `foo.bar.Mumble` to be used in the unauthenticated code path.

Using Dynamic Blocklist Configuration Files

Dynamic blocklists provide the ability to update your blocklist filters by creating configuration files that can be updated or replaced while the server is running.

The April 2021 Patch Set Update (PSU) provides the following functionality for dynamic blocklists:

By default, WebLogic Server will detect the presence of a dynamic blocklist configuration file located in the DOMAIN_HOME/config/security directory, and block deserialization of classes specified in the configuration file.
WebLogic Server can locate dynamic blocklist configuration files that you place in other directories, for example the Oracle Home directory, and block deserialization using those files as appropriate. For WebLogic Server to detect the presence of these files, you must specify the locations of the files using a new system property, weblogic.oif.serialPropDirectories, and include the property in the WebLogic Server start-up script.

In the October 2021 PSU, WebLogic Server can also detect the presence of a dynamic blocklist configuration file in the ORACLE_HOME/oracle_common/common/jep290 directory, and block deserialization of classes and packages specified in the file.

When blocklist files are saved in these locations, WebLogic Server reads them at the specified time interval and immediately begins enforcing the blocks that are specified. You can update or replace the files without needing to stop the server.

To use dynamic blocklists:

Create a configuration file that contains the desired WebLogic, global and unauthenticated filters and save it using the suffix serial.properties. Ensure that the filter strings do not contain any white spaces. Also ensure that WebLogic Server has read permission to the configuration file or server start up will fail. A sample serial.properties file is shown here:
```
weblogic.oif.serialFilter=\
!MyCustomer1.Employee;\
!MyCustomer2.Employee2;\
!MyCustomer3.*;\
!MyCustomer4.**;\
!MyCustomer5.Employee5

weblogic.oif.serialGlobalFilter=\
!MyCustomer1.Employee;\
!MyCustomer2.Employee2;\
!MyCustomer3.**;\
!MyCustomer4.**;\
!MyCustomer5.Employee5
```
In this example:
- The weblogic.oif.serialFilter applies to WebLogic Server deserialization.
- The weblogic.oif.serialGlobalFilter applies to customer application and third party library deserialization.
For both of these filters, the first one matched takes precedence over the others in the filter. For a description of these filters, see Table 3-2.
To use the default location, save the file to the DOMAIN_HOME/config/security directory. In this pathname, DOMAIN_HOME represents the WebLogic domain root directory. WebLogic Server locates the file in this directory by default.

If you are not using the default location, save the file with the suffix serial.properties to the desired directory and specify the directory location using the weblogic.oif.serialPropDirectories system property in the startup script. You can specify multiple files and locations. For example:

-Dweblogic.oif.serialPropDirectories=/u01/oracle/fmw/app1:/u01/oracle/fmw/app2
By default, these directories are polled every 60 seconds. To change the default polling interval, set the weblogic.oif.serialPropPollingFileInterval system property in the startup script. For example, to set the polling interval to 10 seconds, use:

-Dweblogic.oif.serialPropPollingFileInterval=10000

Using an Allowlist for JEP 290 Filtering

Allowlists are configuration files that define a list of the WebLogic Server and customer application classes and packages that you wish to allow to be deserialized. Allowlists can be created and configured to control which packages and classes are deserialized (or blocked) in running systems.

To create and configure a customer allowlist:

In a staging or test environment, enable recording using either of the following methods:
- Use the WebLogic Server Administration Console:
  
  Note:
  Console support for the allowlist model was added in the October 2021 PSU.
  1. In the Change Center of the Administration Console, click Lock & Edit.
  2. In the left pane of the console, under Domain Structure, select the domain name.
  3. Select Configuration>Allowlist, then select the Recording Enabled check box.
  4. Click Save, then in the Change Center, click Activate Changes.
- Use WLST online to set the AllowListRecordingEnabled attribute on the AllowListMBean:
```
edit()
startEdit()
cd("AllowList/mydomain")
cmo.setAllowListRecordingEnabled(true)
save()
activate()
disconnect()
```
When recording is enabled, all classes are allowed during deserialization except for the classes specified in the blockist.
Run a full set of tests to ensure that the recorded allowlist configuration file provides appropriate coverage of all packages and classes that must be allowed in order for your application to run successfully. When deserialization occurs, each class is recorded in the following configuration file:

DOMAIN_HOME/config/security/jep290-recorded.serial.properties

In this pathname, DOMAIN_HOME represents the WebLogic domain root directory.

A sample jep290-recorded.serial.properties is shown here:
```
Wed May 19 23:55:13 UTC 2021
weblogic.oif.serialFilter=\
    com.company1.common.collections.objs.*;\
    com.company1.common.tools.Calculator;\
    com.company2.shared.tools.Converter
weblogic.oif.serialGlobalFilter=\
    com.company1.common.lists.AList;\
    com.company1.common.tools.Calculator;\
    com.company2.shared.tools.*
```
Turn off recording using either the WebLogic Server Administration Console or WLST online:
- In the WebLogic Server Administration Console, clear the Recording Enabled check box on the Allowlist page and click Save, then click Activate Changes.
- Use WLST online to set the AllowListRecordingEnabled attribute to false.
Configure the WebLogic Server domain to use either allowlists or blocklists in one of the following ways:
- In the WebLogic Server Administration Console, select the desired setting from the Violation Action control on the Allowlist page and click Save, then click Activate Changes.
- Use WLST online to set the AllowListViolationAction attribute on the AllowListMBean.
The available settings are as follows:
- IGNORE - Ignore the allowlist and use the blocklists. If any class found during deserialization is present in the blocklist, the class is blocked from being deserialized.
- DENY - Block everything except the classes specified in the allowlist, and log a message when a class is blocked.
- LOG - Log a message if a violation occurs but allow the class unless it is listed in the blocklist.
Note:
You can also set the AllowListViolationAction on a channel using the network access point. Doing so allows you to use an allowlist on untrusted external channels and a blocklist on internal trusted channels.
By default, the directory containing the allowlist configuration file is polled every 60 seconds. To change the default polling interval, do one of the following:
- In the WebLogic Server Administration Console, enter the desired interval in the Serial Profile Polling interval control on the Allowlist page and click Save, then click Activate Changes.
- Set the serialPropPollingFileInterval attribute on the AllowListMBean to the desired interval.
- Set the weblogic.oif.serialPropPollingFileInterval system property in the startup script. For example, to set the polling interval to 10 seconds, use:
  
  -Dweblogic.oif.serialPropPollingFileInterval=10000
Configure your production domain to use allowlists by copying the recorded allowlist configuration file that you created in Step 2 to the DOMAIN_HOME/config/security directory of the production domain.

Note:
Oracle recommends that you run your production domain with AllowListViolationAction set to Log for some period of time to ensure that all classes and packages were recorded.
Maintain the accuracy of the allowlist configuration file. Whenever a new application is deployed to the domain, or a new version of the application is deployed, you should repeat this process, beginning at Step 1, to recreate the allowlist or verify the allowlist with the new application to ensure that all packages and classes required by the new or updated application are included in the allowlist.

Customizing the Allowlist After Recording

Oracle recommends that you use the recording method to create an allowlist whenever possible. If customization is required after creating the allowlist configuration file, then:

Turn off recording.
Make a backup copy of the jep290-recorded.serial.properties file.
Edit the jep290-recorded.serial.properties in the DOMAIN_HOME/config/security/ directory to add or remove classes as required. See Customizing JEP 290 Filters Using Properties.

This list provides examples for editing the following sample jep290-recorded.serial.properties file:

Wed May 19 23:55:13 UTC 2021
weblogic.oif.serialFilter=\
    com.company1.common.collections.objs.*;\
    com.company1.common.tools.Calculator;\
    com.company2.shared.tools.Converter
weblogic.oif.serialGlobalFilter=\
    com.company1.common.lists.AList;\
    com.company1.common.tools.Calculator;\
    com.company2.shared.tools.*

Removing a class from the recorded file

If the recorded allowlist file is allowing a class that you want to block, then edit the recorded jep290-recorded.serial.properties file to remove the class. For example, to remove the class com.company1.common.tools.Calculator; from both the WebLogic and global filters in the sample recorded allowlist file, remove the row from both the weblogic.oif.serialFilter=\ and weblogic.oif.serialGlobalFilter=\ stanzas.

The resulting sample file is as follows:
```
Wed May 19 23:55:13 UTC 2021
weblogic.oif.serialFilter=\
    com.company1.common.collections.objs.*;\
    com.company2.shared.tools.Converter
weblogic.oif.serialGlobalFilter=\
    com.company1.common.lists.AList;\
    com.company2.shared.tools.* 
```
Adding a class to the recorded allowlist file

If you want to add a class to the recorded allowlist file this is being blocked, then edit the recorded jep290-recorded.serial.properties file to add the class to the desired filter. For example, to add the class com.company1.MyApplication1 to both the WebLogic and global filters in the sample recorded file, add the row to both the weblogic.oif.serialFilter=\ and weblogic.oif.serialGlobalFilter=\ stanzas.

The resulting sample file is as follows (the bold text identifies the added content):
```
Wed May 19 23:55:13 UTC 2021
weblogic.oif.serialFilter=\
    com.company1.common.collections.objs.*;\
    com.company1.common.tools.Calculator;\
    com.company2.shared.tools.Converter;\
    com.company1.MyApplication1
weblogic.oif.serialGlobalFilter=\
    com.company1.common.lists.AList;\
    com.company1.common.tools.Calculator;\
    com.company2.shared.tools.*;\
    com.company1.MyApplication1   
```
Allowing a class that WebLogic Server is blocking

As described in Understanding the Filter Order Preference, all blocked classes and packages are given the highest priority in the allowlist filter unless they are specifically allowed by the weblogic.oif.head.serialGlobalFilter or weblogic.oif.head.serialFilter properties.

Therefore, if the class org.codehaus.groovy.runtime.ConvertedClosure is blocked by the WebLogic Server custom or default filter and you want to allow this class for global object input streams (used for application and 3rd party library deserialization), you can use the weblogic.oif.head.serialGlobalFilter JEP 290 property to override the setting in the filter. You can do so using either of the following methods:
- Specify the following property on the command line as a system property:
```
-Dweblogic.oif.head.serialGlobalFilter=org.codehaus.groovy.runtime.ConvertedClosure
```
- Add the following lines to the sample recorded DOMAIN_HOME/config/security/jep290-recorded.serial.properties file:
```
weblogic.oif.head.serialGlobalFilter=\
    org.codehaus.groovy.runtime.ConvertedClosure
```
  The resulting sample allowlist file is as follows (the bold text identifies the added content):
```
Wed May 19 23:55:13 UTC 2021
weblogic.oif.serialFilter=\
    com.company1.common.collections.objs.*;\
    com.company1.common.tools.Calculator;\
    com.company2.shared.tools.Converter
weblogic.oif.serialGlobalFilter=\
    com.company1.common.lists.AList;\
    com.company1.common.tools.Calculator;\
    com.company2.shared.tools.*
weblogic.oif.head.serialGlobalFilter=\
    org.codehaus.groovy.runtime.ConvertedClosure 
weblogic.oif.serialUnauthenticatedFilter=\
```
If the class org.codehaus.groovy.runtime.ConvertedClosure is blocked by the WebLogic Server custom or default filter and you want to allow this class for WebLogic Server deserialization, you can do either of the following:
- Specify the following property on the command line as a system property:
```
-Dweblogic.oif.head.serialFilter=org.codehaus.groovy.runtime.ConvertedClosure 
```
- Add the following lines to the sample recorded DOMAIN_HOME/config/security/jep290-recorded.serial.properties file:
```
weblogic.oif.head.serialFilter=\
    org.codehaus.groovy.runtime.ConvertedClosure
```
  The resulting sample file is as follows (the bold text identifies the added content):
```
Wed May 19 23:55:13 UTC 2021
weblogic.oif.serialFilter=\
    com.company1.common.collections.objs.*;\
    com.company1.common.tools.Calculator;\
    com.company2.shared.tools.Converter
weblogic.oif.serialGlobalFilter=\
    com.company1.common.lists.AList;\
    com.company1.common.tools.Calculator;\
    com.company2.shared.tools.*
weblogic.oif.head.serialFilter=\
    org.codehaus.groovy.runtime.ConvertedClosure 
weblogic.oif.serialUnauthenticatedFilter=\
```

After you edit the file as required and save it, the server picks up the edited file after the specified polling interval.

Enabling Filter Logging

WebLogic Server provides a system property, weblogic.oif.serialFilterLogging, and a debug flag, DebugAllowList on the ServerDebugMBean, that you can use to log the current blocklist and allowlist classes and packages.

To enable logging, start WebLogic Server with the weblogic.oif.serialFilterLogging system property set to true. For example:

./startWebLogic.sh -Dweblogic.oif.serialFilterLogging=true

Note:

In the October 2021 PSU, a new property DebugAllowList has been added to the ServerDebugMBean. To get more implementation specific logging details, set this property to true in the WebLogic Server Administration Console, using WLST, or on the command line, for example -Dweblogic.debug.DebugAllowList=true.

The following log shows sample output using the system property. The filter settings, as well as the blocklist and allowlist classes and packages, are displayed in the server log.


<Jul 1, 2021 9:07:33,787 PM UTC> <Info> <WebLogicServer> <BEA-003807> <The WebLogic Server JEP 290 filter mode is COMBINE> 
<Jul 1, 2021 9:07:33,787 PM UTC> <Info> <WebLogicServer> <BEA-003808> <The WebLogic Server JEP 290 filter scope is GLOBAL> 
<Jul 1, 2021 9:07:33,788 PM UTC> <Info> <WebLogicServer> <BEA-003810> <WebLogic Server JEP 290 filter limit element for scope WEBLOGIC is: maxdepth=250>
...
<Jul 1, 2021 9:07:33,790 PM UTC> <Info> <WebLogicServer> <BEA-003811> <WebLogic Server JEP 290 filter blocklist package for scope WEBLOGIC is: org.apache.commons.collections.functors> 
...
<Jul 1, 2021 9:07:33,802 PM UTC> <Info> <WebLogicServer> <BEA-003812> <WebLogic Server JEP 290 filter blocklist class for scope WEBLOGIC is: java.rmi.server.RemoteObject>
...
<Jul 1, 2021 9:07:33,806 PM UTC> <Info> <WebLogicServer> <BEA-003813> <WebLogic Server JEP 290 filter allowlist for scope WEBLOGIC is: weblogic.**> 
<Jul 1, 2021 9:07:33,806 PM UTC> <Info> <WebLogicServer> <BEA-003813> <WebLogic Server JEP 290 filter allowlist for scope WEBLOGIC is: oracle.**>
...
<Jul 1, 2021 9:07:33,827 PM UTC> <Info> <WebLogicServer> <BEA-003813> <WebLogic Server JEP 290 filter allowlist for scope GLOBAL is: java.**> 
...

Note:

The filter log also displays the filters being used, and any additions or deletions. The filter string for each type of filter used, such as weblogic.oif.serialFilter, weblogic.oif.serialGlobalFilter, and weblogic.oif.serialUnauthenticatedFilter, shows the order of blocklist and allowlist entries in the filter.

Understanding the Filter Order Preference

WebLogic Server combines the blocked and allowed classes and packages specified using properties and configuration files to create a filter that is used to determine order preference for the blocklists and allowlists.

The order preference for the filter created, from highest priority to lowest priority, is determined as follows:

Custom filters specified at server startup using the weblogic.oif.head.serialFilter and weblogic.oif.head.serialGlobalFilter properties (highest).
Custom filters specified at server startup using the weblogic.oif.serialFilter and weblogic.oif.serialGlobalFilter properties.
Custom filters specified in configuration files using the weblogic.oif.serialPropDirectories property.
Custom filters specified in a configuration file located in the default directory DOMAIN_HOME/config/security.
Custom filters specified in a configuration file located in the Oracle home directory ORACLE_HOME/oracle_common/common/jep290.
The WebLogic Server default filter (lowest).

Note:

If you are using allowlists, all blocked classes and packages are given the highest priority in the allowlist filter unless they are specifically allowed by the weblogic.oif.head.serialFilter or weblogic.oif.head.serialGlobalFilter properties.

Setting the Deserialization Timeout Interval

You can further strengthen your protection against potential denial of service attacks by setting a time limit on deserialization. When the time limit elapses, the deserialization process is automatically terminated.

The April 2022 Patch Set Update (PSU) adds support for the KernelMBean attribute RMIDeserializationMaxTimeLimit and the weblogic.rmi.stream.deserialization.timelimitmillis system property when used with the RMI protocol. The January 2023 PSU extends this functionality to IIOP.

By default, the time limit is disabled and not enforced when deserializing Java objects. To add a limit, set your desired time interval, in milliseconds, using either the RMIDeserializationMaxTimeLimit attribute in the KernelMBean or the weblogic.rmi.stream.deserialization.timelimitmillis system property. WebLogic Server does not apply a single interval across multiple Java objects. Instead each top-level object triggers its own separate time limit.

For example, to set a time limit of 10 seconds, use -Dweblogic.rmi.stream.deserialization.timelimitseconds=10000.

Enter an interval of 100 ms or longer. Very short intervals may prevent deserialization from operating smoothly.

Enter 0 to disable the time limit.

Note:

The deserialization time limit will not take effect if the JEP 290 system property weblogic.oif.serialFilterMode is set to disable.