8 Managing Security Module Configurations

The Security Module Configuration User Interface (SMConfig UI) is used to configure a Security Module after the OES Client has been successfully installed and a Security Module type has been instantiated. Basic configurations are accomplished during the installation and instantiation processes but the SMConfig UI allows for additional configurations or modifications to a Security Module profile. This chapter contains the following sections.

8.1 Before You Begin

The SMConfig UI assumes the following Oracle Entitlements Server installation procedures have already been completed.

The OES Client installs the Security Module bits and the SMConfig Tool. The SMConfig Tool will define the Security Module type and create a directory structure for each Security Module instance. The instance's home directory is created at $OES_CLIENT_HOME/oes_sm_instances/SM_Name/ and contains the configuration files used to run the applicable Security Module SMConfig UI script; oessmconfig.sh and oessmconfig.bat are located in the /bin directory of the Security Module instance's home directory.

Note:

Beginning with Oracle Entitlements Server 11gR2, a Security Module can be installed in a Fusion Middleware domain, version 11gR1 PS5 (11.1.1.6). Also, when an Oracle Entitlements Server Security Module is installed into a JRF domain, only non-controlled mode is supported.

8.2 Starting the SMConfig UI

The SMConfig UI is a standalone Java-based tool distributed with the OES Client installation package. The tool configures the Policy Decision Point (PDP), the Policy Information Point (PIP), and the policy store, among other data. The SMConfig UI script is available in the directory created during the instantiation of a Security Module; for example, $OES_CLIENT_HOME/oes_sm_instances/SM_Name/bin/.

Note:

The SMConfig UI script will run only after SMConfig Tool has exited. See Section 8.1, "Before You Begin" for details.

In a Linux environment the SMConfig UI script is named oessmconfig.sh and in a Windows environment it is called oessmconfig.bat. To start the SMConfig UI change to the bin directory in the appropriate Security Module instance directory and run the script on the command line.

cd $OES_CLIENT_HOME/oes_sm_instances/SM_Name/bin/
./oessmconfig.sh

The SMConfig UI runs on the same host as the Security Module. The script will modify the Security Module's jps-config.xml file. The location of the jps-config.xml can be specified as an input parameter when first creating the Security Module. If this parameter is not specified, the default file (located in the Security Module's home directory at $OES_CLIENT_HOME/oes_sm_instances/SM_Name/config) is used.

Note:

For the WebLogic Server Security Module, specify the jps-config.xml file located under user_projects/domains/domain_name/config/oeswlssmconfig/AdminServer when using oessmconfig.sh. Pass the file's location to the tool using the -jpsconfig parameter. For more information, enter the following:

./oessmconfig.sh -help

Figure 8-1 is a screenshot of the SMConfig UI for a Java Security Module.

Figure 8-1 SMConfig UI for Java Security Module

Description of Figure 8-1 follows
Description of "Figure 8-1 SMConfig UI for Java Security Module"

Depending on the type of Security Module, you can expect to configure some or all of the following:

  • If installed in non-controlled mode, configure the Policy Store Type as either LDAP, Oracle DB, or XML.

    • If a database, define a location URL and database credentials, and verify database connectivity.

    • If an LDAP store, define a location URL and LDAP credentials, and verify LDAP connectivity.

  • If installed in controlled push mode, configure the host, distribution port, listener port, username and password for Policy Distribution.

  • If installed in Proxy Mode, configure the communication protocol, and host and distribution point of the Security Module.

8.3 Modifying Security Module Configurations

The SMConfig UI allows an administrator to fine-tune parameter values for a specific Security Module instantiation. This includes the following groups of parameters.

Note:

The SMConfig UI can not change the type of Security Module. To create another type of Security Module, execute the SMConfig Tool and create a new Security Module instance.

8.4 Configuring Security Modules Post-Instantiation

The following sections have information regarding the parameters, specific to the Security Module type, that can be modified post-instantiation. See Appendix A, "Installation and Configuration Parameters" for detailed descriptions.

8.4.1 Configuring the Java Security Module

Table 8-1 documents the controlled-push Client Configuration properties for the Java Security Module.

Table 8-1 Java Security Module Controlled-Push Client Configuration

Property Name jps-config.xml Property

SM Name

oracle.security.jps.runtime.pd.client.sm_name

Policy Distribution Mode

oracle.security.jps.runtime.pd.client.policyDistributionMode

Client Configuration

  • Local Policy Work Folder: oracle.security.jps.runtime.pd.client.localpolicy.work_folder

  • Incremental Distribution: oracle.security.jps.runtime.pd.client.incrementalDistribution

  • Registration Retry Interval: oracle.security.jps.runtime.pd.client.registrationRetryInterval

  • Wait Distribution Time: oracle.security.jps.runtime.policyDistributionWaitTime

  • Registration Server URL: oracle.security.jps.runtime.pd.client.RegistrationServerURL

  • Backup Registration Server URL: oracle.security.jps.runtime.pd.client.backupRegistrationServerURL

  • Distribution Service Port: oracle.security.jps.runtime.pd.client.DistributionServicePort

  • SSL Mode: oracle.security.jps.pd.client.sslMode

  • SSL Identity Key Store File Name: oracle.security.jps.pd.client.ssl.identityKeyStoreFileName

  • SSL Trust Key Store File Name: oracle.security.jps.pd.client.ssl.trustKeyStoreFileName

  • SSL Identity Key Store Key Alias: oracle.security.jps.pd.client.ssl.identityKeyStoreKeyAlias


Table 8-2 documents the controlled-pull Client Configuration properties for the Java Security Module. The configuration properties are organized under the Client Configuration tab and the Policy Store tab.

Table 8-2 Java Security Module Controlled-Pull Client and Store Configuration

Property Name jps-config.xml Property

SM Name

oracle.security.jps.runtime.pd.client.sm_name

Policy Distribution Mode

oracle.security.jps.runtime.pd.client.policyDistributionMode

Client Configuration

  • Local Policy Work Folder: oracle.security.jps.runtime.pd.client.localpolicy.work_folder

  • Incremental Distribution: oracle.security.jps.runtime.pd.client.incrementalDistribution

  • Registration Retry Interval: oracle.security.jps.runtime.pd.client.registrationRetryInterval

  • Wait Distribution Time: oracle.security.jps.runtime.policyDistributionWaitTime

  • Polling Timer: oracle.security.jps.pd.client.PollingTimerEnabled

  • Polling Timer Interval: oracle.security.jps.pd.client.PollingTimerInterval

Policy Store

  • Policy Store Type: policystore.type takes a value of DB_ORACLE as controlled distribution works only with a database

  • Database Configuration Through URL

    • JDBC URL: jdbc.url

    • JDBC Driver: jdbc.driver

    • Username: security.principal

    • Password: security.credential

  • Database Configuration Through JNDI Name

    • Datasource JNDI Name: datasource.jndi.name

  • Maximum Search Filter Length: max.search.filter.length defines the maximum length of a search filter. Takes as a value an integer; for example, 1024.

  • Farm Name: oracle.security.jps.farm.name

  • Resource Type Enforcement Mode: oracle.security.jps.policystore.resourcetypeenforcementmode


Table 8-3 documents the non-controlled distribution properties for the Java Security Module.

Table 8-3 Java Security Module Non-controlled Policy Store Configuration

Property Name jps-config.xml Property

SM Name

oracle.security.jps.runtime.pd.client.sm_name

Policy Distribution Mode

oracle.security.jps.runtime.pd.client.policyDistributionMode

Policy Store

Policy Store Type: policystore.type takes a value of OID or DB_ORACLE.

DB

  • Database Configuration Through URL

    • JDBC URL: jdbc.url

    • JDBC Driver: jdbc.driver

    • Username: security.principal

    • Password: security.credential

  • Database Configuration Through JNDI Name

    • Datasource JNDI Name: datasource.jndi.name

  • Maximum Search Filter Length: max.search.filter.length defines the maximum length of a search filter. Takes as a value an integer defining the maximum length; for example, 1024.

  • Farm Name: oracle.security.jps.farm.name

  • Resource Type Enforcement Mode: oracle.security.jps.policystore.resourcetypeenforcementmode

LDAP

  • LDAP URL: ldap.url defines the location of the LDAP policy store

  • Maximum Search Filter Length: max.search.filter.length defines the maximum length of a search filter. Takes as a value an integer; for example, 1024.

  • LDAP Root Name: oracle.security.jps.ldap.root.name

  • Farm Name: oracle.security.jps.farm.name

  • Resource Type Enforcement Mode: oracle.security.jps.policystore.resourcetypeenforcementmode

  • Username: security.principal

  • Password: security.credential

FILE

  • Policy Store File: location of the file used as the policy store


Table 8-4 documents the Advanced configuration properties for the Java Security Module.

Table 8-4 Java Security Module Advanced Properties

Property Name jps-config.xml Property

Rolemember Cache Type

oracle.security.jps.policystore.rolemember.cache.type

Rolemember Cache Strategy

oracle.security.jps.policystore.rolemember.cache.strategy

Rolemember Cache Size

oracle.security.jps.policystore.rolemember.cache.size

Rolemember Cache Warmup Enable

oracle.security.jps.policystore.rolemember.cache.warmup.enable

Policy Lazy Load Enable

oracle.security.jps.policystore.policy.lazy.load.enable

Policy Cache Strategy

oracle.security.jps.policystore.policy.cache.strategy

Policy Cache Size

oracle.security.jps.policystore.policy.cache.size

Policy Cache Updatable

oracle.security.jps.policystore.cache.updateable

Refresh Enable

oracle.security.jps.policystore.refresh.enable

Refresh Purge Timeout

oracle.security.jps.policystore.refresh.purge.timeout

Refresh Purge Interval

oracle.security.jps.ldap.policystore.refresh.interval

Missing App Policy Query TTL

oracle.security.jps.pdp.missingAppPolicyQueryTTL

Decision Cache Enable

oracle.security.jps.pdp.AuthorizationDecisionCacheEnabled

Decision Cache Eviction Capacity

oracle.security.jps.pdp.AuthorizationDecisionCacheEvictionCapacity

Decision Cache Eviction Percentage

oracle.security.jps.pdp.AuthorizationDecisionCacheEvictionPercentage

Decision Cache TTL

oracle.security.jps.pdp.AuthorizationDecisionCacheTTL

Anonymous Role Enable

oracle.security.jps.pdp.anonymousrole.enable

Authenticated Role Enable

oracle.security.jps.pdp.authenticatedrole.enable


Table 8-5 documents the parameters for defining an attribute retriever as the Policy Information Point (PIP). After clicking New, the display contains the parameters for each attribute retriever type.

Table 8-5 Java Security Module PIP Parameters (Attribute Retrievers)

Name Definition

Attribute Retriever

Type of attribute retriever is chosen from the drop down menu. Options include LDAP, DB and Custom.

LDAP

  • Name: the Attribute Retriever's name as defined in the serviceInstance tag

    <serviceInstance name="dbname" 
      provider="pip.service.provider">
    
  • Description: an optional description as defined in the serviceInstance tag

    <serviceInstance name="description"
      value="dbdescription">
    
  • LDAP URL: ldap.url defines the location of the LDAP policy store. Valid in JEE and JSE applications and only applies to LDAP stores. Takes as a value a URI in the format ldap://host:port

  • Failed Server Retry Interval: interval of time defined for the failed.server.retry.interval property when attempting to reach a failed server again

  • Username: security.principal

  • Password: security.credential

DB

  • Name: the predefined Attribute Retriever's name

  • Description: an optional description

  • Database Configuration Through URL

    • JDBC URL: jdbc.url defines the location of the database policy store. Must be defined when using the Java Database Connectivity (JDBC) API to connect to a database. Takes as a value a list of comma-delimited URLs where the first is treated as primary and so on. For example, jdbc:oracle:thin:@scl58116.domainexample.com:1521:orcl

    • JDBC Driver: jdbc.driver defines the location of the driver when using JDBC API to connect to a database. Takes as a value oracle.jdbc.driver.OracleDriver, for example.

    • Username: security.principal

    • Password: security.credential

  • Database Configuration Through JNDI Name

    • Datasource JNDI Name: Data source JNDI name if you want the PIP instance working through data source rather than directly through JDBC. The data source scenario is supported on WebLogic Server and WebSphere Application Server only. Takes as a value the JNDI name of the pre-defined data source object.

  • Failed Server Retry Interval: After communication with a primary repository has failed, this attribute defines the interval of time during which the backup repository is used before switching back to the primary repository. Takes as a value the number of seconds; the default value is 15.

Custom

  • Name: the custom Attribute Retriever's name

  • Description: an optional description

  • Class Names: one or more class names


Table 8-6 documents the parameters that define the attribute which should be retrieved from the applicable Policy Information Point (PIP). It includes the parameters for both LDAP and database stores.

Table 8-6 Java Security Module PIP Parameters (Attributes)

Name jps-config.xml Property

Attribute Retriever

Select the defined Attribute Retriever from the drop down menu.

Name

Name of the attribute as defined in the policy store. If using the predefined LDAP Attribute Retriever, the attribute name defined for Oracle Entitlements Server must be the same as the attribute name defined in the LDAP store. Currently, there is no name mapping functionality.

Query

This is an example of an LDAP query:

<property name="query" value="(cn=xUSERATTR)"/>

This is an example of a database query:

<property name="query" value="select description from bookstore where author='jimmy'"/>

Search Base

The search base for an LDAP store; not displayed for a database

Time To Live

Time-to-live (in seconds) of any cached attribute values when cached is enabled.

Attribute Cached

Enables the caching of attribute values.


8.4.2 Configuring the RMI Security Module

The following links document the parameters when configuring the RMI Security Module post-instantiation.

See Appendix A, "Installation and Configuration Parameters" for descriptions of the properties.

Tip:

When using a JBOSS Security Module in Proxy Mode as the PEP and the RMI Security Module as the PDP, jbossx.jar must be added to the CLASSPATH of the RMI Security Module.

8.4.3 Configuring the Web Services Security Module

The following links document the parameters when configuring the Web Services Security Module post-instantiation.

See Appendix A, "Installation and Configuration Parameters" for descriptions of the properties. See Section 8.4.4, "Configuring the WebLogic Server Security Module" if using the Web Services Security Module on a WebLogic Server.

Tip:

When using a JBOSS Security Module in Proxy Mode as the PEP and the Web Services Security Module as the PDP, jbossx.jar must be added to the CLASSPATH of the Web Services Security Module.

8.4.4 Configuring the WebLogic Server Security Module

The following links document the parameters when configuring the WebLogic Server Security Module post-instantiation. These parameters are also valid when using the Web Services Security Module on a WebLogic Server.

Note:

If installed on a WebLogic Server, there is no need to configure the Web Service entry point.

See Appendix A, "Installation and Configuration Parameters" for descriptions of the properties.

8.4.5 Configuring the SharePoint Server (MOSS) Security Module

The SMConfig UI does not configure parameters for the MOSS Security Module itself. It configures the Web Services Security Module that serves as the remote PDP for the SharePoint Security Module. See Section 8.4.3, "Configuring the Web Services Security Module" for information. The Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management contains additional information on configuring the MOSS Security Module.

8.4.6 Configuring the .NET Security Module

The SMConfig UI does not configure parameters for the .NET Security Module itself. It configures the Web Services Security Module that serves as the remote PDP for the .NET Security Module. See Section 8.4.3, "Configuring the Web Services Security Module" for information. The Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management contains additional information on configuring the MOSS Security Module.

8.4.7 Configuring the WebSphere, Tomcat and JBoss Security Modules

The following links document the parameters when configuring the WebSphere, Tomcat and JBoss Security Modules post-instantiation.

Tip:

In order for the Security Modules to recognize JBOSS Principals, add JBOSS_HOME/common/lib/jbosssx.jar - which contains org.jboss.security.SimplePrincipal - into the CLASSPATH of the RMI/WS server.

See Appendix A, "Installation and Configuration Parameters" for descriptions of the properties.

8.4.8 Configuring the Oracle Service Bus Security Module

The Oracle Service Bus (OSB) Security Module works only when the Oracle Entitlements Server authorization providers are enabled using the WebLogic Server console (as defined in Section 9.4.1, "Integrating with WebLogic Server"). See Table 8-6, "Configuring the WebLogic Server Security Module" for details on configuring the OSB Security Module parameters post-instantiation. You cannot extend the OSB Domain to create OSB Security Module.

Note:

When an Oracle Entitlements Server Security Module is installed into a JRF domain, only non-controlled mode is supported.

The following procedure is used to configure the OSB Security Module.

  1. After installing and starting the OSB server and Oracle Entitlements Server, install the OESClient.

    See Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management.

  2. Apply Opatch to the installed OESClient and the oracle_common directory.

    The oracle_common directory is created during OSB installation.

  3. Modify the smconfig.prp file.

    smconfig.prp is located in the OES_CLIENT_HOME/oessm/SMConfigTool directory. See Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management.

  4. Create an OSB Security Module using the SMConfig Tool.

    Ensure the Oracle Entitlements Server is running. See Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management.

    1. Change to the bin directory.

      cd OES_CLIENT_HOME/oessm/bin

    2. Run the SMConfig Tool.

      ./config.sh -smType wls -smConfigId osbSM -serverLocation ../wlserver_10.3/

    3. Input the name and password of the user with permission to access the Oracle Entitlements Server policy store in the command window.

    4. Select Oracle Entitlements Server Security Module On Service Bus -11.1.2.0[oesclient] when prompted by the Fusion Middleware Configuration Wizard to Select Extension Source and click Next.

  5. Modify the policy store configuration in the jps-config.xml file in the OSB Domain.

  6. Enable the Oracle Entitlements Server authorization and role mapping providers using the WebLogic Server console.

    See Section 9.4.1, "Integrating with WebLogic Server."

  7. Restart the OSB server.

8.5 Configuring the PDP Proxy Client for RMI or Web Services

Oracle Entitlements Server supports a Proxy Mode that allow clients to invoke authorization services remotely. When the Oracle Entitlements Server PEP API are used by an application to make authorization calls, a PDP Proxy Client can be set up on the application's host to communicate with the remote Security Module (on another machine) for access decisions. The PDP Proxy Client provides local security services, including caching, logging, and failover support. A Remote Method Invocation (RMI) or Web Services call can be used as the method of communication between the PDP Proxy Client and the remote Security Module. The RMI and Web Services Security Modules are the only ones to invoke security services remotely.

Note:

In XACML terminology, the proxy and remote Security Module are analogous to the PDP Proxy and PDP, respectively.

The Oracle Entitlements Server PEP API can be called from an application regardless of whether that application is calling an embedded PDP or a remote PDP. Proxy Mode can be configured to provide security services locally (including authorization caching, logging and failover) and can communicate with the PDP using RMI or SOAP.

There are configurations involved with both the local PDP Proxy Client and the remote Security Module. On the proxy side, client configurations are consolidated in the PDP Service instance inside the jps-config.xml configuration file. On the server side, configuration parameters for both the RMI and Web Services Security Modules are also consolidated in the PDP Service instance inside the jps-config.xml configuration file. See Appendix A, "Installation and Configuration Parameters" for details on the configuration parameters.