F OPSS System and Configuration Properties

This appendix documents OPSS system properties (set through the switch -D at server start) and configuration properties (set with elements <property> and <extendedProperty> in the configuration file jps-config.xml) in the following sections:

OPSS System Properties
OPSS Configuration Properties

To manage server properties programmatically, use OPSS MBeans. For details and example, see Section E.2.3, "Programming with OPSS MBeans."

Note:

All OPSS configuration changes (manual or through JpsConfiguration MBean) require server restart to take effect.

OPSS data domain changes do not require server restart to take effect. Data changes include modifying an application policy and creating, deleting, or updating a credential.

F.1 OPSS System Properties

A system property cannot be set without restarting the server. In order to set a system property the administrator must edit the setDomainEnv.sh shell script and add the property to the environment variable EXTRA_JAVA_PROPERTIES in that script.

Table F-1 lists the Java system properties available with OPSS.

Table F-1 Java System Properties Used by OPSS

Name	Description
`jps.policystore.hybrid.mode`	Enables or disables the hybrid mode. The hybrid mode is used to facilitate the transition from the Sun java.security.Policy to the OPSS Java PolicyProvider. When the hybrid mode is enabled, the OPSS Java Policy Provider reads from both files, java.policy and system-jazn-data.xml. Default value: TRUE.
`jps.authz`	Enables or disables the delegation of calls to JDK API AccessController.checkPermission, which reduces runtime and debugging overhead. Default value: FALSE.
`jps.combiner.optimize`	Enables or disables the caching of a subject's protection domain. Default value: FALSE.
`jps.combiner.optimize.lazyeval`	Enables or disables the evaluation of a subject's protection domain when a check permission is triggered. Default value: FALSE.
`jps.auth.debug`	Controls server logging output. Default value: TRUE. For details, see Section I.1.2.1, "jps.auth.debug."
`jps.auth.debug.verbose`	Controls server logging output. Default value: FALSE. For details, see Section I.1.2.2, "jps.auth.debug.verbose."
`oracle.security.jps.config`	Specifies the path to the domain configuration files `jps-config.xml` or `jps-config-jse.xml`. Paths specifications in those files can be absolute or relative to the location of the configuration file.

F.2 OPSS Configuration Properties

This section describes the properties of various instances in the following sections:

LDAP Policy Store Properties
LDAP Credential Store Properties
LDAP Identity Store Properties
Generic LDAP Properties
Anonymous and Authenticated Roles Properties
Policy Provider Framework Properties
Keystore Properties

F.2.1 LDAP Policy Store Properties

Table F-2 lists the properties of LDAP-based policy store instances.

Table F-2 LDAP-Based Policy Store Properties

Name	Description
`bootstrap.security.principal.key`	The key for the password credentials to access the LDAP policy store, stored in the CSF store. Valid only in J2EE applications. No default value. When the policy store is migrated from a file-based to an LDAP-base store, the out-of-the-box value in the jps-config.xml file is `bootstrap`.
`bootstrap.security.principal.map`	The map for the password credentials to access the LDAP policy store, stored in the CSF store. Valid only in J2EE applications. Default value: BOOTSTRAP_JPS.
`oracle.security.jps.farm.name`	The RDN format of the domain node in the LDAP policy store. Valid in J2EE and J2SE applications. No default value.
`oracle.security.jps.ldap.root.name`	The RDN format of the root node in the LDAP policy store. Valid in J2EE and J2SE applications. No default value.
`ldap.url`	The URL of the LDAP policy store, with the format `ldap://host:port`. Valid in J2EE and J2SE applications. No default value.
`policystore.type`	The type of the LDAP policy store. Valid in J2EE and J2SE applications. No default value.
`oracle.security.jps.policystore.rolemember.cache.type`	The type of the role member cache. Valid only in J2EE applications. Valid values: STATIC - Cache objects are statically cached and can be cleaned explicitly only according the applied cache strategy, such as FIFO. The garbage collector does not clean a cache of this type. SOFT - The cleaning of a cache of this type relies on the garbage collector when there is a memory crunch. WEAK - The behavior of a cache of this type is similar to a cache of type SOFT, but the garbage collector cleans it more frequently. Default value: STATIC.
`oracle.security.jps.policystore.rolemember.cache.strategy`	The type of strategy used in the role member cache. Valid only in J2EE applications. Valid values: FIFO - The cache implements the first-in-first-out strategy. NONE - All entries in the cache grow until a refresh or reboot occurs; there is no control over the size of the cache; not recommended but typically efficient when the policy footprint is very small. Default value: FIFO.
`oracle.security.jps.policystore.rolemember.cache.size`	The size of the role member cache. Valid only in J2EE applications. Default value: 1000.
`oracle.security.jps.policystore.policy.lazy.load.enable`	Enables or disables the policy lazy load. Valid only in J2EE applications. Default value: TRUE.
`oracle.security.jps.policystore.policy.cache.strategy`	The type of strategy used in the permission cache. Valid only in J2EE applications. PERMISSION_FIFO - The cache implements the first-in-first-out strategy. NONE - All entries in the cache grow until a refresh or reboot occurs; there is no control over the size of the cache; not recommended but typically efficient when the policy footprint is very small. Default value: PERMISSION_FIFO.
`oracle.security.jps.policystore.policy.cache.size`	The size of the permission cache. Valid only in J2EE applications. Default value: 1000.
`oracle.security.jps.policystore.refresh.enable`	Enables or disables the refresh of the policy store. Valid only in J2EE applications. Default value: TRUE.
`oracle.security.jps.policystore.purge.timeout`	The time, in milliseconds, after which the policy store is refreshed. Valid only in J2EE applications. Default value: 43200000 (12 hours).
`oracle.security.jps.policystore.refresh.interval`	The interval, in milliseconds, at which the policy store is polled for changes. Valid only in J2EE applications. Default value: 600000.
`oracle.security.jps.policystore.refresh.permissions.invalidate.threshold`	The number of user's permissions after which the permission cache is invalidated. Valid only in J2EE applications. Default value: 50.
`oracle.security.jps.policystore.rolemember.cache.warmup.enable`	This property controls the way the ApplicationRole membership cache is created. If set to TRUE, the cache is created at server startup; otherwise, it is created on demand (lazy loading). Set to TRUE when the number of users and groups is significantly higher than the number of application roles; set to FALSE otherwise, that is, when the number of application roles is very high. Valid only in J2EE applications. Default value: FALSE.

The following fragment illustrates the configuration of the above properties for a J2EE application:

<serviceInstance provider="ldap.policystore.provider" name="policystore.ldap">
     <property value="OID" name="policystore.type"/>
     <property value="bootstrap" name="bootstrap.security.principal.key"/>
     <property value="cn=wls-jrfServer" name="oracle.security.jps.farm.name"/>
     <property value="cn=jpsTestNode" name="oracle.security.jps.ldap.root.name"/>
     <property value="ldap://stadk06.us.oracle.com:3060" name="ldap.url"/>
     <property value="STATIC" name="oracle.security.jps.policystore.rolemember.cache.type"/>
     <property value="FIFO" name="oracle.security.jps.policystore.rolemember.cache.strategy"/>
     <property value="1000" name="oracle.security.jps.policystore.rolemember.cache.size"/>
     <property value="true" name="oracle.security.jps.policystore.policy.lazy.load.enable"/>
     <property value="PERMISSION_FIFO" name="oracle.security.jps.policystore.policy.cache.strategy"/>
     <property value="1000" name="oracle.security.jps.policystore.policy.cache.size"/>
     <property value="true" name="oracle.security.jps.policystore.refresh.enable"/>
     <property value="43200000" name="oracle.security.jps.policystore.refresh.purge.timeout"/>
     <property value="600000" name="oracle.security.jps.ldap.policystore.refresh.interval"/>
</serviceInstance>

The following fragment illustrates the configuration of the above properties for a J2SE application:

<serviceInstance name="policystore.oid" provider="policy.oid">
   <property value="OID" name="policystore.type"/>
   <property name="security.principal" value="cn=orcladmin"/>
   <property name="security.credential" value="welcome1"/>
   <property name="ldap.url" value="ldap://sttt:3060"/>
   <property name="oracle.security.jps.ldap.root.name" value="cn=jpsNode"/>
   <property name="oracle.security.jps.farm.name" value="cn=domain1"/>
</serviceInstance>

Table F-3 lists the reload/refresh properties of LDAP-based policy store instances.

Table F-3 LDAP-Based Policy Store Reload/Refresh Properties

Name	Description
`oracle.security.jps.ldap.cache.enable`	Enables or disables the refresh of the cache. Default value: TRUE.
`oracle.security.jps.ldap.cache.purge.timeout`	The time, in milliseconds, after which the existing cache will be purged and the whole cache will be reloaded. Default value: 43200000 (12 hours).
`oracle.security.jps.ldap.cache.refresh.interval`	The interval, in milliseconds, at which the policies will be scanned for any change in LDAP store such as additions, deletions, or updates. Default value: 43200000 (12 hours).
`oracle.security.jps.ldap.cache.load.factor`	The load factor for the cache object. Default value: 0.7.
`oracle.security.jps.ldap.cache.initial.capacity`	The initial default capacity, in MB, of the cache. Default value: 20.

F.2.2 LDAP Credential Store Properties

Table F-4 lists the properties of LDAP-based credential store instances.

Table F-4 LDAP-Based Credential Store Properties

Name	Description
`bootstrap.security.principal.key`	The key for the password credentials to access the LDAP credential store, stored in the CSF store. Valid only in J2EE applications. No default value. When the policy store is migrated from a file-based to an LDAP-base store, the out-of-the-box value in the jps-config.xml file is `bootstrap`.
`bootstrap.security.principal.map`	The map for the password credentials to access the LDAP credential store, stored in the CSF store. Valid only in J2EE applications. Default value: BOOTSTRAP_JPS.
`oracle.security.jps.farm.name`	The RDN format of the domain node in the LDAP credential store. Valid in J2SE and J2EE applications. No default value.
`oracle.security.jps.ldap.root.name`	The RDN format of the root node in the LDAP policy store. Valid in J2SE and J2EE applications. No default value.
`ldap.url`	The URL of the LDAP credential store, with the format `ldap://host:port`. Valid in J2SE and J2EE applications. No default value.

The following fragment illustrates the configuration of the above properties for a J2EE application:

<serviceInstance provider="ldap.credentialstore.provider" name="credstore.ldap">
    <property value="bootstrap" name="bootstrap.security.principal.key"/>
    <property value="cn=wls-jrfServer" name="oracle.security.jps.farm.name"/>
    <property value="cn=jpsTestNode" name="oracle.security.jps.ldap.root.name"/>
    <property value="ldap://stttt.us.oracle.com:3060" name="ldap.url"/>
</serviceInstance>

The following fragment illustrates the configuration of the above properties for a J2SE application:

<serviceInstance name="credstore_ldap_instance" provider="credstore_ldap_provider">
    <property name="security.principal" value="cn=orcladmin"/>
    <property name="security.credential" value="welcome1"/>
    <property name="oracle.security.jps.farm.name" value="cn=wls-jrfServer"/>
    <property name="oracle.security.jps.ldap.root.name" value="cn=jpsTestNode"/>
    <property name="ldap.url" value="ldap://stttt:3060"/>
</serviceInstance>

F.2.3 LDAP Identity Store Properties

Table F-5 lists the properties of LDAP-based identity store instances.

Table F-5 LDAP-Based Identity Store Properties

Name	Description
`idstore.type`	The type of the LDAP identity store. Valid only in J2SE applications. No default value.
`security.principal.alias`	The CSF map name. Valid only in J2SE applications. No default value.
`security.principal.key`	The CSF key name. Valid only in J2SE applications. No default value.
`ldap.url`	The LDAP URL value. Valid only in J2SE applications. No default value.
`user.search.bases`	The user search base for the LDAP server in DN format. Valid only in J2SE applications. No default value.
`group.search.bases`	The group search base for the LDAP server in DN format. Valid only in J2SE applications. No default value.
`idstore.config.provider`	The out-of-the-box idstore provider. Valid only in J2EE applications. The only supported value is: oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvider

The following fragment illustrates the configuration of the above properties:

<serviceInstance name="idstore.ldap" provider="idstore.ldap.provider">
    <property name="idstore.type" value="OID"/>
    <property name="security.principal.alias" value="MAP_NAME"/>
    <property name="security.principal.key" value="KEY_NAME"/>
    <property name="ldap.url" value="ldap://stadk06:3060"/>
    <extendedProperty>
       <name>user.search.bases</name>
          <values>
             <value>cn=users,dc=us,dc=oracle,dc=com</value>
          </values>
    </extendedProperty>
    <extendedProperty>
       <name>group.search.bases</name>
          <values>
             <value>cn=groups,dc=us,dc=oracle,dc=com</value>
          </values>
    </extendedProperty>
</serviceInstance>

F.2.4 Generic LDAP Properties

Table F-6 lists generic properties of LDAP-based stores that can be specified in service instances. In the case of an LDAP-based identity store service instance, to ensure that the User and Role API picks up the connection pool properties when it is using the JNDI connection factory, the identity store service instance must include the following property:

<property 
name="INITIAL_CONTEXT_FACTORY" value="com.sun.jndi.ldap.LdapCtxFactory"/>

Table F-6 Generic LDAP Properties

Name	Description
`connection.pool.authentication`	Specifies the type of LDAP connection that the JNDI connection pool uses. Values: none, simple, and DIGEST-MD5. Default: simple.
`connection.pool.max.size`	Specifies the maximum number of connections in the LDAP connection pool. Values: integer Example: 30
`connection.pool.min.size`	Specifies the minimum number of connections in the LDAP connection pool. Values: integer Example: 5
`connection.pool.protocol`	Specifies the protocol to use for the LDAP connection. Values: plain, ssl. Default: plain.
`connection.pool.provider.type`	Specifies the connection pool to use. Values: JNDI, IDM. Default: JNDI.
`connection.pool.timeout`	Specifies the number of milliseconds that an idle connection can remain in the pool; after timeout, the connection is closed and removed from the pool. Values: an integer in string form. Defaults to 300000 (5 minutes)
`oracle.security.jps.ldap.max.retry`	Specifies the maximum number of retry attempts if there are problems with the LDAP connection. Values: integer Example: 5

The following fragment illustrates the configuration of the above properties:

<jpsConfig ... >
   ...
   <!-- These are various JPS common properties used for LDAP operations -->
   <property name="oracle.security.jps.farm.name" value="cn=OracleFarmContainer"/>
   <property name="oracle.security.jps.ldap.root.name"
             value="cn=OracleJpsContainer"/>
   <property name="oracle.security.jps.ldap.max.retry" value="5"/>
   ...
</jpsConfig>

F.2.5 Anonymous and Authenticated Roles Properties

Table F-7 lists the properties of anonymous users, anonymous roles, and authenticated roles. Some of them may also be used to configure the anonymous service or an identity store login module.

Table F-7 Anonymous and Authenticated Roles Properties

Name	Description
`anonymous.role.description`	Provides a description of the anonymous role. Example: `This is the anonymous role used by the anonymous service instance.`
`anonymous.role.name`	Specifies the principal name of the anonymous role. Default value: `anonymous-role`
`anonymous.role.uniquename`	Specifies the name of the anonymous role. Default value: `anonymous-role`
`anonymous.user.name`	Specifies the principal name of the anonymous user. Default value: `anonymous`
`authenticated.role.description`	Provides a description of the authenticated role. Example: `This is the role used for authenticated users by the identity store service instance.`
`authenticated.role.name`	Specifies the principal name of the role used for authenticated users. Default value: `authenticated-role`
`authenticated.role.uniquename`	Specifies the name of the authenticated role. Default value: `authenticated-role`
`remove.anonymous.role`	Specifies whether the anonymous role should be removed from the subject after a user is authenticated. Default value: FALSE.

F.2.6 Policy Provider Framework Properties

Table F-8 lists the properties of the policy provider framework.

Table F-8 Policy Provider Framework Properties

Name	Description
`policystore.delegation.permission`	Specifies the fully qualified class name of the permission that extends PolicyDelegationPermission. This is used in runtime for custom provider delegation by the policy framework. By default, this property is not specified in `jps-config.xml`.
`policystore.role.memberattr`	Specifies the attribute of a static LDAP role object that specifies the distinguished names (DNs) of the members of the role. Example: `uniquemember`
`policystore.role.nameattr`	Specifies the name of the LDAP attribute that uniquely identifies the name of the role. Example: `cn`
`policystore.role.objectclass`	Specifies LDAP schema object classes that represent a role. If specifying multiple classes, separate the classes with a space. The default for Sun Java System Directory Server is `groupOfUniqueNames`. For Active Directory, the default is `group`. Example: `orclrole`
`policystore.role.searchbase`	Specifies a list of space-delimited distinguished names (DN) in the LDAP directory that contains roles. Example: `cn=groups,dc=us,dc=abc,dc=com`
`policystore.role.searchscope`	Specifies how deep in the LDAP directory tree to search for roles. Default values: `subtree` or `onelevel`

The following example illustrates the configuration of a policy store service provider, using an Oracle Internet Directory, and its use in a jpscontext.

<jpsConfig ... >
   ...
   <serviceProviders>
      <serviceProvider type="POLICY_STORE" name="policystore.ldap.provider"
                    class= "oracle.security.jps.internal.policystore.ldap.LdapPolicyStoreProvider">
         <description>LDAP-based PolicyStore</description>
         <property name="policystore.type" value="OID"/>
         <property name="connection.pool.max.size" value="30"/>
         <property name="connection.pool.provider.type" value="IDM"/>
      </serviceProvider>
   </serviceProviders>
   ...
   <serviceInstances>
      <serviceInstance name="policystore.oid" provider="policystore.ldap.provider">
         <property name="max.search.filter.length" value="4096"/>
         <property name="security.principal" value="cn=orcladmin"/>
         <property name="security.credential" value="password"/>
         <property name="ldap.url" value="ldap://xyz.us.oracle.com:389"/>
         <property name="policystore.jpsbase" value="cn=jps,cn=oraclecontext"/>
         <property name="policystore.role.objectclass" value="orclrole"/>
         <property name="policystore.role.searchbase" value="cn=roles"/>
         <property name="policystore.role.searchscope" value="subtree"/>
         <property name="policystore.role.nameattr" value="cn"/>
         <property name="policystore.role.memberattr" value="uniquemember"/>
         <property name="policystore.role.roleheirarchyattr" value="assignedRoles"/>
      </serviceInstance>
   </serviceInstances>
   ...  
   <jpsContexts default="default">
      <jpsContext name="default">
         <serviceInstanceRef ref="policystore.oid"/>
      </jpsContext>
   </jpsContexts>
</jpsConfig>

F.2.7 Keystore Properties

Table F-9 lists the properties that configure keystore services. When using encryption or signing, you specify a password to retrieve the private key and provide the map to access the keystore credential.

Table F-9 Keystore Properties

Name	Description
`keystore.path`	The path to the keystore.
`keystore.type`	The type of keystore.
`keystore.csf.map`	The map of the keystore credentials in the credential store.
`keystore.pass.csf.key`	The key to the private password in the credential store.
`keystore.sig.csf.key`	The private key in the credential store when using signing.
`keystore.enc.csf.key`	The private key in the credential store when using encryption.

The following example illustrates the configuration of the above properties:

<serviceInstance provider="keystore.provider" name="keystore">
   <description>Default JKS Keystore Service</description>
   <property value="${oracle.instance}/config/default-keystore.jks" name="keystore.path"/>
   <property value="JKS" name="keystore.type"/>
   <property value="oracle.wsm.security" name="keystore.csf.map"/>
   <property value="keystore-csf-key" name="keystore.pass.csf.key"/>
   <property value="sign-csf-key" name="keystore.sig.csf.key"/>
   <property value="enc-csf-key" name="keystore.enc.csf.key"/>
</serviceInstance>