A OPSS Configuration File Reference

This appendix describes the element hierarchy and attributes in the file that configures OPSS services. By default, this file is named jps-config.xml (for Java EE applications) or jps-config-jse.xml (for Java SE applications) and is located in the directory $DOMAIN_HOME/config/fmwconfig.

For Java SE applications, an alternative location can be specified using the system property oracle.security.jps.config.

The configuration file is used to configure the policy, credential, and identity stores, the login modules, and the audit service. For a complete example of a configuration file see Section 21.5.9, "Example of Configuration File jps-config.xml."

To configure services programmatically, see Section E.2, "Configuring OPSS Services with MBeans."

This appendix includes the following sections:

A.1 Top- and Second-Level Element Hierarchy

The top element in the file jps-config.xml is <jpsConfig>. It contains the following second-level elements:

  • <property>

  • <propertySets>

  • <extendedProperty>

  • <serviceProviders>

  • <serviceInstances>

  • <jpsContexts>

Table A-1 describes the function of these elements. The annotations between curly braces{} indicate the number of occurrences the element is allowed. For example, {0 or more} indicates that the element can occur 0 or more times; {1} indicates that the element must occur once.

These elements are not application-specific configurations: all items in the configuration file pertain to an entire domain and apply to all managed servers and applications deployed on the domain.

Table A-1 First- and Second-Level Elements in jps-config.xml

Elements Description 
<jpsConfig> {1}

Defines the top-level element in the configuration file.

 
    <property> {0 or more}

Defines names and values of properties. It can also appear elsewhere in the hierarchy, such as under the elements <propertySet>, <serviceProvider>, and <serviceInstance>.

 
    <propertySets> {0 or 1}
        <propertySet> {1 or more}
            <property> {1 or more}

Groups one or more <propertySet> elements so that they can referenced as a group.

 
    <extendedProperty> {0 or more}
        <name> {1}
        <values> {1}
            <value> {1 or more}

Defines a property that has multiple values. It can also appear elsewhere in the hierarchy, such as under the elements extendedProperty and serviceInstance.

 
    <extendedPropertySets> {0 or 1}
        <extendedPropertySet> {1 or more}
            <extendedProperty> {1 or more}
                <name> {1}
                <values> {1}
                    <value> {1 or more}

Groups one or more <extendedPropertySet> elements so that they can referenced a group.

 
    <serviceProviders> {0 or 1}
        <serviceProvider> {1 or more}
            <description> {0 or 1}
            <property> {0 or more}

Groups one or more <serviceProvider> elements, each of which defines an implementation of an OPSS service, such as a policy store provider, a credential store provider, or a login module.

 
    <serviceInstances> {0 or 1}
        <serviceInstance> {1 or more}
            <description> {0 or 1}
            <property> {0 or more}
            <propertySetRef> {0 or more}
            <extendedProperty> {0 or more}
                <name> {1}
                <values> {1}
                    <value> {1 or more}
            <extendedPropertySetRef> {0 or more}

Groups one or more <serviceInstance> elements, each of which configures and specifies property values for a service provider defined in a <serviceProvider> element.

 
    <jpsContexts> {1}
        <jpsContext> {1 or more}
            <serviceInstanceRef> {1 or more}

Groups one or more <jpsContext> elements, each of which is a collection of service instances that an application can use.

A.2 Lower-Level Elements

This section describes, in alphabetical order, the complete set of elements that can occur in under the second-level elements described in the Top- and Second-Level Element Hierarchy.

<description>

This element describes the corresponding entity (a service instance or service provider).

Parent Elements

<serviceInstance> or <serviceProvider>

Child Element

None.

Occurrence

<description> can be a child of <serviceInstance> or <serviceProvider>.

Example

The following example sets a description for a service provider.

<serviceProvider ... >
   <description>XML-based IdStore Provider</description>
   ...
</serviceProvider>

 

<extendedProperty>

This element defines an extended property in the following scenarios:

Table A-2 Scenarios for <extendedProperty>

Location in jps-config.xml Function

Directly under <jpsConfig>

Defines an extended property for general use. As a child of <jpsConfig>, an extended property can specify, for example, all the base DNs in an LDAP-based authenticators.

Directly under <extendedPropertySet>

Defines an extended property for general use that is part of an extended property set.

Directly under <serviceInstance>

Defines an extended property for a particular service instance.

An extended property typically includes multiple values. Use a <value> element to specify each value. Several LDAP identity store properties are in this category, such as the specification of the following values:

  • Object classes used for creating user objects

  • Attribute names that must be specified when creating a user

  • Base DNs for searching users

Parent Elements

<extendedPropertySet>, <jpsConfig>, or <serviceInstance>

Child Elements

<name> or <values>

Occurrence

<extendedProperty> can be a child of <extendedPropertySet>, <jpsConfig>, or <serviceInstance>.

Example

The following example sets a single value:

<extendedProperty>
   <name>user.search.bases</name>
   <values>
      <value>cn=users,dc=us,dc=oracle,dc=com</value>
   </values>
</extendedProperty>

<extendedPropertySet>

This element defines a set of extended properties. The extended property set can then be referenced by an <extendedPropertySetRef> element to specify the given properties as part of the configuration of a service instance.

Attributes

Name Description

name              

Designates a name for the extended property set. No two <extendedPropertySet> elements may have the same name attribute setting within a configuration file.

Values: string

Default: n/a (required)

Parent Element

<extendedPropertySets>

Child Element

<extendedProperty>

Occurrence

Required within <extendedPropertySets>, one or more:

<extendedPropertySets> {0 or 1}
    <extendedPropertySet> {1 or more}
        <extendedProperty> {1 or more}
            <name> {1}
            <values> {1}
                <value> {1 or more}

<extendedPropertySetRef>

This element configures a service instance by referring to an extended property set defined elsewhere in the file.

Attributes

Name Description

ref               

Refers to an extended property set whose extended properties are used for the service instance defined in the <serviceInstance> parent element. The ref value of <extendedPropertySetRef> must match the name value of an <extendedPropertySet> element.

Values: string

Default: n/a (required)

Parent Element

<serviceInstance>

Child Element

None.

Occurrence

Optional, zero or more.

<serviceInstances> {0 or 1}
    <serviceInstance> {1 or more}
        <description> {0 or 1}
        <property> {0 or more}
        <propertySetRef> {0 or more}
        <extendedProperty> {0 or more}
            <name> {1}
            <values> {1}
                <value> {1 or more}
        <extendedPropertySetRef> {0 or more}

<extendedPropertySets>

This element specifies a set of properties.

Parent Element

<jpsConfig>

Child Element

<extendedPropertySet>

Occurrence

Optional, zero or one.

<jpsConfig>
    <extendedPropertySets> {0 or 1}
        <extendedPropertySet> {1 or more}
            <extendedProperty> {1 or more}
                <name> {1}
                <values> {1}
                    <value> {1 or more}

<jpsConfig>

This is the root element of a configuration file.

Parent Element

None.

Child Elements

<extendedProperty>, <extendedPropertySets>, <jpsContexts>, <property>, <propertySets>, <serviceInstances>, or <serviceProviders>

Occurrence

Required, one only.

Example

<jpsConfig xmlns="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd"
    schema-major-version="11" schema-minor-version="1">
...
</jpsConfig>

 

<jpsContext>

This element declares an OPSS context, a collection of service instances common to a domain, either by referring to a set of service instances that comprise the context (typical usage), or by referring to another context. Each <jspContext> in a configuration file must have a distinct name.

Attributes

Name Description

name

Designates a name for the OPSS context. Each context must have a unique name.

Values: string

Default: n/a (required)

Parent Element

<jpsContexts>

Child Element

<serviceInstanceRef>

Occurrence

There must be at least one <jpsContext> element under <jpsContexts>. A <jpsContext> element contains the <serviceInstanceRef> element.

<jpsContexts> {1}
    <jpsContext> {1 or more}
        <serviceInstanceRef> {1 or more}

Example

The following example illustrates the definition of two contexts; the first one, named default, is the default context (specified by the attribute default in <jpsContexts>), and it references several service instances by name.

The second one, named anonymous, is used for unauthenticated users, and it references the anonymous and anonymous.loginmodule service instances.

<serviceInstances>
...
   <serviceInstance provider="credstoressp" name="credstore">
      <description>File Based Default Credential Store Service Instance</description>
      <property name="location" value="${oracle.instance}/config/JpsDataStore/JpsSystemStore"/>
   </serviceInstance>
...
   <serviceInstance provider="anonymous.provider" name="anonymous">
      <property value="anonymous" name="anonymous.user.name"/>
      <property value="anonymous-role" name="anonymous.role.name"/>
   </serviceInstance>
...
   <serviceInstance provider="jaas.login.provider" name="anonymous.loginmodule">
      <description>Anonymous Login Module</description>
      <property value="oracle.security.jps.internal.jaas.module.anonymous.AnonymousLoginModule"
                name="loginModuleClassName"/>
      <property value="REQUIRED"
                name="jaas.login.controlFlag"/>
   </serviceInstance>
...
</serviceInstances>
...
<jpsContexts default="default">
...
   <jpsContext name="default">
      <!-- This is the default JPS context. All the mandatory services and Login Modules must be
           configured in this default context -->
      <serviceInstanceRef ref="credstore"/>
      <serviceInstanceRef ref="idstore.xml"/>
      <serviceInstanceRef ref="policystore.xml"/>
      <serviceInstanceRef ref="idstore.loginmodule"/>
      <serviceInstanceRef ref="idm"/>
   </jpsContext>
   <jpsContext name="anonymous">
       <serviceInstanceRef ref="anonymous"/>
       <serviceInstanceRef ref="anonymous.loginmodule"/>
   </jpsContext>
...
</jpsContexts>

 

<jpsContexts>

This element specifies a set of contexts.

Attributes

Name Description

default         

Specifies the context that is used by an application if none is specified. The default value of the <jpsContexts> element must match the name of a <jpsContext> child element.

Values: string

Default: n/a (required)

Note: The default context must configure all mandatory services and login modules.

Parent Element

<jpsConfig>

Child Element

<jpsContext>

Occurrence

Required, one only.

<jpsConfig>
    <jpsContexts> {1}
        <jpsContext> {1 or more}

Example

See <jpsContext> for an example.

 

<name>

This element specifies the name of an extended property.

Parent Element

<extendedProperty>

Child Element

None

Occurrence

Required, one only.

<extendedProperty> {0 or more}
    <name> {1}
    <values> {1}
        <value> {1 or more}

Example

See <extendedProperty> for an example.

 

<property>

This element defines a property in the following scenarios:

Table A-3 Scenarios for <property>

Location in jps-config.xml Function

Directly under <jpsConfig>

Defines a one-value property for general use.

Directly under <propertySet>

Defines a multi-value property for general use that is part of a property set.

Directly under <serviceInstance>

Defines a property for use by a particular service instance.

Directly under <serviceProvider>

Defines a property for use by all service instances of a particular service provider.

For a list of properties, see Appendix F, "OPSS System and Configuration Properties".

Attributes

Name Description

name  

Specifies the name of the property being set.

Values: string

Default: n/a (required)

value

Specifies the value of the property being set.

Values: string

Default: n/a (required)

Parent Elements

<jpsConfig>, <propertySet>, <serviceInstance>, or <serviceProvider>

Child Element

None.

Occurrence

Under a<propertySet>, it is required, one or more; otherwise, it is optional, zero or more.

Example

The following example illustrates a property to disable JAAS mode for authorization:

<jpsConfig ... >
   ...
   <property name="oracle.security.jps.jaas.mode" value="off"/>
   ...
</jpsConfig>

For additional examples, see <propertySet> and <serviceInstance>.

 

<propertySet>

This element defines a set of properties. Each property set has a name so that it can be referenced by a <propertySetRef> element to include the properties as part of the configuration of a service instance.

Attributes

Name Description

name              

Designates a name for the property set. No two <propertySet> elements may have the same name within a jps-config.xml file.

Values: string

Default: n/a (required)

Parent Element

<propertySets>

Child Element

<property>

Occurrence

Required within a<propertySets>, one or more

<propertySets> {0 or 1}
    <propertySet> {1 or more}
        <property> {1 or more}

Example

<propertySets>
...
   <!-- For property that points to valid Access SDK installation directory -->
   <propertySet name="access.sdk.properties">
      <property name="access.sdk.install.path" value="$ACCESS_SDK_HOME"/>
   </propertySet>
...
</propertySets>

<serviceInstances>
...
   <serviceInstance provider="jaas.login.provider" name="oam.loginmodule">
      <description>Oracle Access Manager Login Module</description>
      <property
          value="oracle.security.jps.internal.jaas.module.oam.OAMLoginModule"
          name="loginModuleClassName"/>
      <property value="REQUIRED" name="jaas.login.controlFlag"/>
      <propertySetRef ref="access.sdk.properties"/>
   </serviceInstance>
...
</serviceInstances>

<propertySetRef>

This element configures a service instance by referring to a property set defined elsewhere in the file.

Attributes

Name Description

ref              

Refers to a property set whose properties are used by the service instance defined in the <serviceInstance> parent element. The ref value of a <propertySetRef> element must match the name of a <propertySet> element.

Values: string

Default: n/a (required)

Parent Element

<serviceInstance>

Child Element

None.

Occurrence

Optional, zero or more.

<serviceInstances> {0 or 1}
    <serviceInstance> {1 or more}
        <description> {0 or 1}
        <property> {0 or more}
        <propertySetRef> {0 or more}
        <extendedProperty> {0 or more}
            <name> {1}
            <values> {1}
                <value> {1 or more}
        <extendedPropertySetRef> {0 or more}

Example

See <propertySet> for an example.

 

<propertySets>

This element specifies a set of property sets.

Parent Element

<jpsConfig>

Child Element

<propertySet>

Occurrence

Optional. If present, there can be only one <propertySets> element.

<jpsConfig>
    <propertySets> {0 or 1}
        <propertySet> {1 or more}
            <property> {1 or more}

Example

See <propertySet> for an example.

 

<serviceInstance>

This element defines an instance of a service provider, such as an identity store service instance, policy store service instance, or login module service instance.

Each provider instance specifies the name of the instance, used to refer to the provider within the configuration file; the name of the provider being instantiated; and, possibly, the properties of the instance. Properties include the location of the instance and can be specified directly, within the instance element itself, or indirectly, by referencing a property or a property set. To change the properties of a service instance, you can use the procedure explained in Section E.1, "Configuring OPSS Service Provider Instances with a Script."

Set properties and extended properties of a service instance in the following ways:

Attributes

Name Description

name

Designates a name for this service instance. Note that no two <serviceInstance> elements may have the same name attribute setting within a jps-config.xml file.

Values: string

Default: n/a (required)

provider

Indicates which service provider this is an instance of.

The provider value of a <serviceInstance> element must match the name value of a <serviceProvider> element.

Values: string

Default: n/a (required)

Parent Element

<serviceInstances>

Child Elements

<description>, <extendedProperty>, <extendedPropertySetRef>, <property>, or <propertySetRef>

Occurrence

Required within <serviceInstances>, one or more.

<serviceInstances> {0 or 1}
    <serviceInstance> {1 or more}
        <description> {0 or 1}
        <property> {0 or more}
        <propertySetRef> {0 or more}
        <extendedProperty> {0 or more}
            <name> {1}
            <values> {1}
                <value> {1 or more}
        <extendedPropertySetRef> {0 or more}

Examples

Example 1   

The following example illustrates the configuration of a file-based identity store service. For a file-based identity store, the subscriber name is the default realm. The example sets the lo cation using the location property.

<serviceInstances>
   <serviceInstance name="idstore.xml" provider="idstore.xml.provider">
      <!-- Subscriber name must be defined for XML Identity Store -->
      <property name="subscriber.name" value="jazn.com"/>
      <!-- This is the location of XML Identity Store -->
      <property name="location" value="./system-jazn-data.xml"/>
   </serviceInstance>
...
</serviceInstances>
Example 2   

The following example illustrates the configuration a credential store service. It uses the location property to set the location of the credential store.

<serviceInstances>
   <serviceInstance provider="credstoressp" name="credstore">
      <description>File Based Default Credential Store Service
                  Instance</description>
      <property name="location"
                value="${oracle.instance}/config/JpsDataStore/JpsSystemStore" />
   </serviceInstance>
...
</serviceInstances>
Example 3   

The following example illustrates the configuration of an LDAP-based identity store using Oracle Internet Directory:

<serviceInstance name="idstore.oid" provider="idstore.ldap.provider">
   <property name="subscriber.name" value="dc=us,dc=oracle,dc=com"/>
   <property name="idstore.type" value="OID"/>
   <property name="security.principal.key" value="ldap.credentials"/>
   <property name="security.principal.alias" value="JPS"/>
   <property name="ldap.url" value="ldap://myServerName.com:389"/>
   <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>
   <property name="username.attr" value="uid"/>
   <property name="groupname.attr" value="cn"/>
</serviceInstance>
Example 4   

The following example illustrates the configuration of an audit provider:

<serviceInstances>
   <serviceInstance name="audit" provider="audit.provider">
      <property name="audit.filterPreset" value="Low"/>
      <property name="audit.specialUsers" value ="admin, fmwadmin" />
      <property name="audit.customEvents" value ="JPS:CheckAuthorization,           CreateCredential, OIF:UserLogin"/>
      <property name="audit.loader.jndi" value="jdbc/AuditDB"/>
      <property name="audit.loader.interval" value="15" />
      <property name="audit.maxDirSize" value="102400" />
      <property name="audit.maxFileSize" value="10240" />      
      <property name=" audit.loader.repositoryType " value="Db" />      
   </serviceInstance>
  </serviceInstances>

See Also:

 

<serviceInstanceRef>

This element refers to service instances.

Attributes

Name Description

ref              

Refers to a service instance that are part of the context defined in the <jpsContext> parent element. The ref value of a <serviceInstanceRef> element must match the name of a <serviceInstance> element.

Values: string

Default: n/a (required)

Parent Element

<jpsContext>

Child Element

None

Occurrence

Required within a <jpsContext>, one or more.

<jpsContexts> {1}
    <jpsContext> {1 or more}
        <serviceInstanceRef> {1 or more}

Example

See <jpsContext> for an example.

 

<serviceInstances>

This element is the parent of a <serviceInstance> element.

Parent Element

<jpsConfig>

Child Element

<serviceInstance>

Occurrence

Optional, zero or one.

<jpsConfig>
    <serviceInstances> {0 or 1}
        <serviceInstance> {1 or more}
            <description> {0 or 1}
            <property> {0 or more}
            <propertySetRef> {0 or more}
            <extendedProperty> {0 or more}
                <name> {1}
                <values> {1}
                    <value> {1 or more}
            <extendedPropertySetRef> {0 or more}

Example

See <serviceInstance> for an example.

 

<serviceProvider>

This element defines a service provider. Each provider specifies the type of the provider, such as credential store, authenticators, policy store, or login module; the name of the provider, used to refer to the provider within the configuration file; and the Java class that implements the provider and that is instantiated when the provider is created. Furthermore, the element property specifies settings used to instantiate the provider.

It specifies the following data:

  • The type of service provider (specified in the type attribute)

  • A designated name of the service provider (to be referenced in each <serviceInstance> element that defines an instance of this service provider)

  • The class that implements this service provider and is instantiated for instances of this service provider

  • Optionally, properties that are generic to any instances of this service provider

Attributes

Name Description

type

Specifies the type of service provider being declared; it must be either of the following:

CREDENTIAL_STORE

IDENTITY_STORE

POLICY_STORE

AUDIT

LOGIN

ANONYMOUS

KEY_STORE

IDM (for pluggable identity management)

CUSTOM

The implementation class more specifically defines the type of provider, such as by implementing a file-based identity store or LDAP-based policy store, for example.

Values: string (a value above)

Default: n/a (required)

name

Designates a name for this service provider. This name is referenced in the provider attribute of <serviceInstance> elements to create instances of this provider. No two <serviceProvider> elements may have the same name attribute setting within a configuration file.

Values: string

Default: n/a (required)

class

Specifies the fully qualified name of the Java class that implements this service provider (and that is instantiated to create instances of the service provider).

Values: string

Default: n/a (required)

Parent Element

<serviceProviders>

Child Elements

<description> or <property>

Occurrence

Required within the <serviceProviders> element, one or more.

<serviceProviders> {0 or 1}
    <serviceProvider> {1 or more}
        <description> {0 or 1}
        <property> {0 or more}

Examples

The following example illustrates the specification of a login module service provider:

<serviceProviders>
   <serviceProvider type="LOGIN" name="jaas.login.provider"
        class="oracle.security.jps.internal.login.jaas.JaasLoginServiceProvider">
      <description>This is Jaas Login Service Provider and is used to configure
       login module service instances</description>
   </serviceProvider>
</serviceProviders>

The following example illustrates the definition of an audit service provider:

 <serviceProviders>
     <serviceProvider name="audit.provider" type="AUDIT" class="oracle.security.jps.internal.audit.AuditProvider">
     </serviceProvider>
    </serviceProviders>

See <serviceInstance> for other examples.

 

<serviceProviders>

This element specifies a set of service providers.

Parent Element

<jpsConfig>

Child Element

<serviceProvider>

Occurrence

Optional, one only.

<jpsConfig>
    <serviceProviders> {0 or 1}
        <serviceProvider> {1 or more}
            <description> {0 or 1}
            <property> {0 or more}

Example

See <serviceProvider> for an example.

 

<value>

This element specifies a value of an extended property, which can have multiple values. Each <value> element specifies one value.

Parent Element

<values>

Child Element

None.

Occurrence

Required within <values>, one or more.

    <extendedProperty> {0 or more}
        <name> {1}
        <values> {1}
            <value> {1 or more}

Example

See <extendedProperty> for an example.

 

<values>

This element is the parent element of a <value> element.

Parent Element

<extendedProperty>

Child Element

<value>

Occurrence

Required within <extendedProperty>, one only.

<extendedProperty> {0 or more}
    <name> {1}
    <values> {1}
        <value> {1 or more}

Example

See <extendedProperty> for an example.