8 Configuring the OPSS Security Store

The OPSS security store is the repository of system and application-specific policies, credentials, and keys. For an introduction to policies, credentials, keys and certificates, see the following sections:

When a WebLogic domain is setup to use policies based on the OPSS security store, JACC policies and the Java Security Manager become unavailable on all managed servers in that domain.

Important:

All permission classes used in policies in the OPSS security store must be included in the class path, so the policy provider can load them when a service instance is initialized.

8.1 Introduction to the OPSS Security Store

The OPSS security store is the repository of system and application-specific policies, credentials, and keys. This centralization facilitates the administration and maintenance of policy, credential, and key data.

The OPSS security store can be file-, LDAP-, or DB-based depending on the choice of repository type, and it can be reassociated (that is, the repository type can be changed) from file-based to LDAP- or DB-based; from DB-based to LDAP- or DB-based; and from LDAP-based to LDAP- or DB-based. No other reassociation is supported. For details about the tools and procedures available to reassociate the OPSS security store, see sections Reassociating with Fusion Middleware Control and Reassociating with the Script reassociateSecurityStore. Out-of-the-box, the OPSS security store is file-based.

8.2.1 Multiple-Node Server Environments

In domains where several server instances are distributed across multiple machines, it is highly recommended that the OPSS security store be a centralized LDAP- or DB-based store configured in the administration server.

In case of a file-based multiple-node server domain (not recommended), the JMX framework periodically propagates changes made in the administration server to runtime environments in the domain managed servers; the data in each of these runtime environments is refreshed based on caching policies and property values. It is crucial that any changes to a file-based security store be performed in the domain administration server (and not in a managed server).

8.2.2 Prerequisites to Using an LDAP-Based Security Store

The only supported LDAP-based OPSS security store is Oracle Internet Directory. In order to ensure the proper access to the Oracle Internet Directory, you must set a node in the server directory as explained below.

The distinguished name of the root node (illustrated by the string jpsroot above) must be distinct from any other distinguished name. Some LDAP servers enforce case sensitivity by default. One root node can be shared by multiple WebLogic domains. It is not required that this node be created at the top level, as long as read and write access to the subtree is granted to the Oracle Internet Directory administrator.

Import this data into the LDAP server using the command ldapadd, as illustrated in the following example (there should be no line break in the command invocation):

8.2.3 Setting Up a One- Way SSL Connection to the LDAP

This section describes how to set up a one-way SSL channel between Oracle WebLogic server or a Java SE application and the LDAP Oracle Internet Directory. Such connection may be required, for example, when reassociating to an LDAP-based target store.

Modify the script that starts the JMV to include a line like the following:

-Djavax.net.ssl.trustStore=<absolute path name to file myKeys.jks>

8.3 Using a DB-Based OPSS Security Store

A DB-based security store is typically used in production environments. The only supported DB-based security store in production environments is Oracle RDBMS (releases 10.2.0.4 or later; releases 11.1.0.7 or later; and releases 11.2.0.1 or later).

To use a DB-based OPSS security store the domain administrator must configure it, as appropriate, using Oracle Enterprise Manager Fusion Middleware Control or OPSS scripts. In case any checks are needed before the server completes its initialization, see Section L.15, "Permission Failure Before Server Starts."

8.3.1 Prerequisites to Using a DB-Based Security Store

To use a database repository for the OPSS security store, one must first use Oracle Fusion Middleware Repository Creation Utility (RCU) to create the required schema and to seed some initial data. This setup is also required before reassociating the OPSS security store to a DB-based security store.

Then click Next to have RCU check the entered data and perform pre-creation operations; once this check is successfully completed, RCU displays the Select Components dialog.

In that dialog, choose to use an existing schema prefix or create a new prefix, and pick the OPSS component to install the schema.

When finished selecting components, click Next to display the Schema Passwords dialog where you supply passwords, and then click Next to display the Map Tablespaces dialog which shows the tablespace summary. Use one default tablespace and one temporary tablespace; the default tablespace names are PREFIX_IAS_OPSS and PREFIX_IAS_TEMP, respectively.

To create a non-default tablespace or datafile, click the button Manage Tablespaces to display the Manage Tablespaces dialog, where you can specify the information to create them. When finished, click OK. If the specified tablespaces are not yet in the database, RCU creates them and informs about this in the Creating Tablespaces; click OK to display the Summary dialog, which displays the summary of data you have entered, and then click Create to effect the creation of the additional tablespace(s) or datafile(s).

When the creation is completed, RCU displays the Completion Summary, which shows the database details.

Invoke the SQLPlus command illustrated below to verify that the database schema has been properly created:

SQL> desc <schemaPrefix>.jps_dn;

where schemaPrefix is the prefix set in step 4 above.

8.3.1.2 Dropping the OPSS Schema in an Oracle Database

Dropping the OPSS schema is required only if one no longer wishes to use that DB for storing OPSS security policies.

After the OPSS schema has been successfully created, use RCU to drop the OPSS schema as follows:

Start RCU to display the RCU Welcome page; in this page, click Next to display the Drop Repository page.

In that page, select the radio button Drop; then click Next to display the Database Connections Details page.

In that page, enter the appropriate connectivity information: Database Type, Host Name, Port, Service Name, Username, Password, and Role. Then click Next to display the Select Components dialog.

In that dialog, select the prefix and, in the Component hierarchy, check AS Common Schemas and Oracle Platform Security Services; then click Next to display the Summary page.

In that page, verify that the details gathered are correct, and click Drop to trigger the dropping; when the operation is successfully completed, RCU displays the Completion Summary page detailing the schema dropped.

8.3.1.3 Creating a Data Source Instance

To create a JDBC data source in a WebLogic domain using the Oracle WebLogic Administration Console, proceed as follows:

Login to the Console and navigate to Services > DataSources and select New > Generic Data Source.

Enter the JNDI Name and then click Next. Note that this name is used when configuring a DB-based store in the file jps-config.xml.

In the Database Driver pull-down, select Oracle's Driver (Thin) for Instance connections; Versions:9.0.1 and later (this is a non-XA JDBC driver) and then click Next.

Make sure that Supports Global Transactions is deselected and then click Next.

In the area Connection Properties, enter data for DatabaseName, HostName, Port, DatabaseUserName, and Password. Then click Next.

Inspect and test your settings and, when satisfied, click Finish.

Deploy the data source just created on the administration server; this data source must be targeted to all servers in the domain.

11.2 Oracle JDBC driver deprecated the following time zones: Etc/UCT, UCT, Etc/UTC, Etc/Universal, Etc/Zulu, and Universal. When setting a time zone for your Oracle JDBC driver, make sure that it is a non-deprecated time zone.

8.3.2 Maintaining a DB-Based Security Store

This section describes a few tasks that an administrator can follow to maintain a DB-based security store.

A DB-based security store maintains a change log that should be periodically purged. To purge it, an administrator can use the provided SQL script opss_purge_changelog.sql, which will purge change logs older than 24 hours, or connect to the database and run SQL delete (with the appropriate arguments) as illustrated in the following lines:

If the OPSS management API performs slowly while accessing the DB-based security store, run the DBMS_STATS package to gather statistics about the physical storage of a DB table, index, of cluster. This information is stored in the data dictionary and can be used to optimize the execution plan for SQL statements accessing analyzed objects.

When loading large amount of data into a DB-based security store, such as when creating thousands of new application roles, it is recommended that DBMS_STATS be run within short periods and concurrently with the loading activity. Otherwise, when the loading activity is small, DBMS_STATS needs to be run just once and according to your needs.

8.5 Reassociating the OPSS Security Store

Reassociating the OPSS security store consists in relocating the policy, credential, and key stores from one repository to another one. The source can be file-, LDAP-, or DB-based; the target can be LDAP- or DB-based. The only type of LDAP target supported is Oracle Internet Directory; the only type of DB target supported is DB_ORACLE.

Reassociation changes the repository preserving the integrity of the data stored. For each security artifact, reassociation searches the target store and, if it finds a match for it, it updates the matching artifact; otherwise, creates a new artifact.

Reassociation is typically performed, for example, when setting a domain to use an LDAP- or DB-based OPSS store instead of the out-of-the-box file-based store. This operation can take place at any time after the OPSS store has been configured and instantiated, and it is carried out using either Fusion Middleware Control or reassociateSecurityStore as explained in the following sections:

8.5.1 Reassociating with Fusion Middleware Control

Reassociation migrates the OPSS policy store (policies, credentials, and keys) from one repository to another and reconfigures the appropriate security store providers. This section explains how to perform reassociation with Fusion Middleware Control pages.

The table in the area Security Stores shows the characteristics of the current provider configured in the domain.

Click the button Change Association to display the Set Security Provider page, and choose the Store Type from the pull-down list. The text displayed on this page depends on the store type selected. The following graphic partially illustrates this page when Oracle Internet Directory is selected.

If you have selected Database, enter the name of the data source in the Datasource Name box. This should be the name of the JDBC data source entered when the data source was created; see Creating a Data Source Instance for details. If needed, click Select to obtain a list of configured data source names.

If you have selected Oracle Internet Directory, in the LDAP Server Details area, specify details and connection information about the target LDAP server:

Enter the host name and port number of your target Oracle Internet Directory LDAP server.

Optionally, check the box Use SSL to Connect to establish an anonymous SSL transmission to the LDAP server.

When checking this box, keep in mind the following points:

The port of the target LDAP server must be configured to handle an anonymous SSL transmission; this port is distinct from the default (non-secure) LDAP server port.

If the reassociation is to use a one-way SSL to a target LDAP store, be sure to follow the instructions in Setting Up a One- Way SSL Connection to the LDAPbefore completing this step. Among other things, that setup identifies the port to support a one-way SSL channel, and it is that port that should be specified in this step. Reassociation through a two-way SSL channel is not supported in this release.

Fusion Middleware Control modifies the file weblogic.policy by adding the necessary grant to support the anonymous SSL connection.

In the text box Connect DN, enter the full distinguished name, a string containing between 1 and 256 characters. For example, cn=orcladmin,dc=us,dc=oracle,dc=com.

In the box Password, enter the user password, also a string containing between 1 and 256 characters.

In the Root Node Details area, enter the root DN in the box Root DN, which identifies the top of the tree that contains the data in the LDAP repository. The Domain Name defaults to the name of the selected domain.

Optionally, in the Policy Store Properties and Credential Store Properties areas, enter service instance properties, such as Enable Lazy Load and Role Member Cache Size.

To add a new property: click Add to display the Add New Property dialog; in this dialog, enter strings for Property Name and Value; click OK. The added property-value pair is displayed in the table Custom Properties.

These properties are typically used to initialize the instance when it is created.

A property-value pair you enter modifies the domain configuration file jps-config.xml by adding a <property> element in the configuration of the LDAP service instance.

To illustrate how a service instance is modified, suppose you enter the property name foo and value bar; then the configuration for the LDAP service instance changes to contain a <property> element as illustrated in the following excerpt:

When finished entering your data, click OK to return to the Security Provider Configuration page. The system displays a dialog notifying the status of the reassociation. The table in the SecurityStores area is modified to reflect the provider you have specified.

Restart the application server. Changes do not take effect until it has been restarted.

Reassociation modifies the domain configuration file $DOMAIN_HOME/config/fmwconfig/jps-config.xml: it deletes any configuration for the old store provider, inserts a configuration for the new store provider, and moves the policy and credential information from the source to the destination store.

If the destination store is LDAP-based, the information is stored under the domain DN according to the following format:

cn=<domain_name>,cn=JpsContext,<JPS ROOT DN>

As long as the configuration of the installation relies upon the above domain DN, that node should not be deleted from the LDAP Server.

8.5.1.1 Securing Access to Oracle Internet Directory Nodes

The procedure explained in this section is optional and performed only to enhance the security to access an Oracle Internet Directory.

An access control list (ACL) is a list that specifies who can access information and what operations are allowed on the Oracle Internet Directory directory objects. The control list is specified at a node, and its restrictions apply to all entries in the subtree under that node.

ACL can be used to control the access to policy and credential data stored in an LDAP Oracle Internet Directory repository, and it is, typically, specified at the top, root node of the store.

To specify an ACL at a node in an Oracle Internet Directory repository, proceed as follows:

8.5.2 Reassociating with the Script reassociateSecurityStore

8.6 Migrating the OPSS Security Store

A domain includes one and only one policy store. Applications can specify their own policies, and these are stored as application policies in the appropriate stripe in the policy store when the application is deployed to a server. All applications deployed or redeployed to a domain use a common policy store, the domain policy store. The policy store is logically partitioned in stripes, one for each application name specified in the file $DOMAIN_HOME/config/fmwconfig/system-jazn-data.xml under the element <applications>.

Migrating the OPSS security store consists in relocating the policy, credential, and key stores from one repository to another one. The source can be file-, LDAP-, or DB-based; the target can be LDAP- or DB-based. The OPSS binaries and the target policy store must have compatible versions; for details, see Section L.22, "Incompatible Versions of Binaries and Policy Store."

During application development, an application specifies its own policies, and these can be migrated to the OPSS security store when the application is deployed with Fusion Middleware Control. Policies can also be migrated manually; in addition, each application component can specify the use of anonymous user and role, authenticated role, and JAAS mode.

The configuration of the policy store is performed by an administrator.

Use the system propertyjps.deployment.handler.disabled to disable the migration of application policies and credentials for applications deployed on a WebLogic Server.

When this system property is set to TRUE, the migration of policies and credentials at deployment is disabled for all applications regardless of the particular application settings in the application file weblogic-application.xml.

8.6.1 Migrating with Fusion Middleware Control

Application policies are specified in the application file jazn-data.xml and can be migrated to the policy store when the application is deployed to a server in the WebLogic environment with Fusion Middleware Control; they can also be removed from the policy store when the application is undeployed or be updated when the application is redeployed.

All three operations, the migration, the removal, and the updating of application policies, can take place regardless of the type of policy repository, but they do require particular configurations.

8.6.2 Migrating with the Script migrateSecurityStore

Application-specific policies, system policies, and credentials can be migrated manually from a source repository to a target repository using the OPSS script migrateSecurityStore.

This script is offline, that is, it does not require a connection to a running server to operate; therefore, the configuration file passed to the argument configFile need not be an actual domain configuration file, but it can be assembled just to specify the source and destination repositories of the migration.

configFile specifies the location of a configuration file relative to the directory where the script is run. This configuration file should be specially assembled and must contain the following elements:

a context specifying the source store

a context specifying the destination store

a context specifying the bootstrap credentials

The bootstrap context refers to the location of a cwallet.sso file where the keys needed to access the source and destination stores, and to decrypt and encrypt security data in them are expected to be.

src specifies the name of a jps-context in the configuration file passed to the argument configFile.

dst specifies the name of another jps-context in the configuration file passed to the argument configFile.

The contexts passed to src and dst must be defined in the passed configuration file and must have distinct names. From these two contexts, the script determines the locations of the source and the target repositories involved in the migration.

To migrate just system policies on WebLogic, use the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

The meanings of the arguments configFile, src, and dst are identical to the previous cases. The meaning of other five arguments is as follows:

srcApp specifies the name of the source application, that is, the application whose policies are being migrated.

dstApp specifies the name of the target application, that is, the application whose policies are being written. If unspecified, it defaults to the name of the source application.

migrateIdStoreMapping specifies whether enterprise policies should be migrated. The default value is True. To filter out enterprise policies from the migration, that is, to migrate just application policies, set it to False.

overWrite specifies whether a target policy matching a source policy should be overwritten by or merged with the source policy. Set to true to overwrite the target policy; set to false to merge matching policies. Optional. If unspecified, defaults to false.

mode specifies whether the migration should stop and signal an error upon encountering a duplicate principal or a duplicate permission in an application policy. Either do not specify or set to lax to allow the migration to continue upon encountering duplicate items, to migrate just one of the duplicated items, and to log a warning to this effect.

If the input does not follow the syntax requirements above, the script execution fails and returns an error. In particular, the input must satisfy the following requisites: (a) the file jps-config.xml is found in the passed location; (b) the file jps-config.xml includes the passed jps-contexts; and (c) the source and the destination context names are distinct.

To migrate all credentials use either of the script (first) or interactive (second) syntaxes (arguments are written in separate lines for clarity):

The meanings of the arguments configFile, src, and dst are identical to the previous case. The meanings of the last four arguments (all optional) are as follows:

srcFolder specifies the name of the map containing the credentials to be migrated. Optional. If unspecified, the credential store is assumed to have only one map and the value of this argument defaults to the name of that map.

dstFolder specifies the map where the source credentials are migrated. Optional; if unspecified, it defaults to the map passed to srcFolder.

srcConfigFile specifies the location of an alternate configuration file, and it is used in the special case in which credentials are not configured in the file passed to configFile. Optional; if unspecified, it defaults to the value passed to configFile; if specified, the value passed to configFile is ignored.

overWrite specifies whether a target credential matching a source credential should be overwritten by or merged with the source credential. Set to true to overwrite target credentials; set to false to merge matching credentials. Optional. If not specified, defaults to false. When set to false, if a matching is detected, the source credential is disregarded and a warning is logged.

8.6.2.1 Migrating Audit Metadata

You can use the script migrateSecurityStore to migrate audit metadata into a domain security store, or migrate audit metadata into an XML file.

The area of the Security Provider Configuration page labeled Web Services Manager Authentication Providers pertains to the configuration of Login Modules and the Keystore for Web Services Manager only and is not relevant to ADF or Java EE applications.

In that page, the Trust Service Provider area shows whether the service is configured; to configure the service, click the Configure to display the Trust Service Provider page.

That page contains the following areas:

Provider, where the name of the chosen provider is displayed.

Trust Store, where you select a stripe and a trust store, from the available ones.

Keystore and Alias, where you select a certificate by picking a stripe and a keystore, and an alias from the list of available trust aliases. The read-only entries at the bottom of the area (Issuer Name and Expiration Date) give information about the certificate selected.

Trust Service Configuration, where you enter the following values:

Clock Skew, the number of seconds that the clocks of the two systems (involved in the use of the trust service) may differ; the default is 60.

Token Validity Period, the number of seconds that the token is valid; the default is 1800.

Include Certificate, a boolean stating whether the certificate should be included in the token.

Codesource Permission, specifying the URL of the client code (that will access the trust store); no default value provided; this information translates into a codesource permission granted to the specified code.

Click OK to save the entered data and to return to the Security Provider Configuration page; the values you entered are saved in the file $DOMAIN_HOME/config/fmwconfig/jps-config.xml.

8.7.4 Configuring Properties and Property Sets

A property set is collection of properties typically used to define the properties of a service instance or generic properties of the domain.

The elements <property> and <properySet> in the file $DOMAIN_HOME/config/fmwconfig/jps-config.xml are used to define property and property sets. Property sets can be referenced by the element <propertySetRef>.

Expand, if necessary, the area Advanced Properties, and click Configure to display the Advanced Properties page.

To enter a property, click Add in the Properties area to display the dialog Add New Property, and enter a property name and value. When finished, click OK. The entered property appears on the Properties table.

To enter a property set, click Add Property Set in the Property Sets area to display the dialog Add Property Set, and enter the property set name.

To enter a property in a property set, select a property set from the existing ones, then click Add Property to display the dialog Add New Property, and then enter a property name and value. The entered property is added to the list of properties in the selected property set.

Use the button Delete to remove a selected item from any table. When finished entering or editing properties and property sets, click OK.

Restart the Oracle WebLogic Server. Changes do not take effect until the server has been restarted.

The addition or deletion of property sets modifies the domain configuration file $DOMAIN_HOME/config/fmwconfig/jps-config.xml; the changes do not take effect until the server is restarted.

The elements <property> and <propertySet> added by the previous procedure are inserted directly under the element <jpsConfig>.

Scripting on this page enhances content navigation, but does not change the content in any way.