5 Overriding Policy Configuration Properties
It includes the following topics:
5.1 Overview of Policy Configuration Overrides
Values for server-side configuration properties in a predefined or custom web service policy can be used each time you attach the policy to a web service or overridden on a per-attachment basis. For web service clients, configuration can be overridden on a per-client basis. One of the possible uses of overrides is to limit the number of policies you have to maintain: rather than creating multiple policies with slightly varied configurations, you can use the same generic policy and override specific values to meet your requirements.
Note:
Unless specified otherwise, the procedures in this chapter apply to Oracle Infrastructure web services and RESTful web services only.
Configuration properties that you can override are of two types:
-
Predefined policy configuration properties—The configuration properties included with the predefined service policies allow you to override certain domain-wide configuration settings, such as the CSF key used for storing the signature-key password. For predefined client policies, you can override a configuration property on a per-client basis or set it globally for any attachment of the policy.
The configuration properties that you can override in a predefined policy are inherited from the assertion templates that are included in the policy. To determine the configuration properties associated with each policy, see Oracle Web Services Manager Predefined Policies. An alphabetized list of the overrideable properties is provided in "Assertion Template Configuration Properties for Oracle Web Services". Note that you cannot override a property of type "constant".
-
User-defined policy configuration properties—For a user-defined property, you can add a property that has meaning in your environment. You can add a user-defined property to a cloned predefined policy, or to a custom policy. For more information about creating and configuring user-defined policy configuration properties, see "About Configuring User-Defined Properties for Web Service and Client Policies Using Fusion Middleware Control".
Note:
The predefined policies are read-only and cannot be edited. You can, however, create new policies using the predefined policies as a base. For information about creating a new policy, see "Creating and Editing Web Service Policies". Once you have created the new policy, you can edit the policy and set the configuration properties as desired.
When attaching OWSM 12c predefined policies, if you specify a value of blank (" ") in the Value field, the default value will be in effect. If you have imported 11g policies or any custom policies, ensure that the policy has a valid value in the Default field to achieve the same effect; otherwise, the specified value will be picked up.
5.2 Scope of Predefined Configuration Properties
The scope for the server-side configuration property value is limited to the specific policy attachment. That is, you could have two policies with the same server-side configuration property name, say P1, attached to the same web service endpoint, and the two P1 properties can have different values.
The scope for a client-side configuration property value is the client. There can be multiple policies that are attached to the same client that use the same property. For example, the oracle/wss_http_token_client_policy policy is one example of a policy that includes the csf-key property, which has a default value of basic.credentials. The value signifies a key that maps to a username/password. It might happen that you will always use the same key value any time you attach this policy to any number of web service clients. In this case, you can clone the oracle/wss_http_token_client_policy and set the value for the configuration property in the cloned version and the new value can apply to every instance. You also have the option to override the configuration property on a per-client basis when you attach the policy.
Note:
To clear an overridden configuration property, set it to an empty string. Before you clear it, remember that other policies could be using the same property. The properties are client-specific and there could be multiple policies that are attached to the same client that use the same property.
When you detach a client-side security policy, you must manually remove any configuration overrides because client configuration overrides are applied at the port level. Otherwise, the override remains in effect for all future policy attachments to this port, both globally and directly.
5.3 About Overriding Client Policy Configuration Properties at Design Time
You can override client policy configuration properties for an OWSM security policy programmatically at design time.
Note:
The procedures in this section apply to Java EE, RESTful, and Oracle Infrastructure web services.
Following methods are used to override client policy configuration:
5.3.1 Java EE Web Services
Client Policy Configuration can be overridden by using Java EE Web Services.
-
JAX-WS
RequestContext, as shown in xREFTBD . -
weblogic.wsee.jws.jaxws.owsm.Propertyannotation when attaching an OWSM security policy to Java EE web services and clients, as described in Attaching Policies to Java EE Web Services and Clients Using Annotations. -
Using JDeveloper, as described in "Attaching Policies" in Developing Applications with Oracle JDeveloper.
5.3.2 RESTful Web Services
You can override client policy configuration properties for an OWSM security policy by using RESTful Web Services method.
-
oracle.wsm.metadata.annotation.Propertyannotation when attaching an OWSM security policy to RESTful web services, as described in Attaching Policies to RESTful Web Services Using Annotations. -
oracle.wsm.metadata.feature.PropertyFeatureannotation when attaching an OWSM security policy to RESTful web service clients, as described in Attaching Policies to RESTful Web Service Clients Using Feature Classes. See also Example 5-*. -
Using JDeveloper, as described in "Attaching Policies" in Developing Applications with Oracle JDeveloper.
5.3.3 Understanding Oracle Infrastructure Web Services
OWSM security policy can be attached to Oracle Infrastructure Web services using annotations or JDeveloper.
-
oracle.wsm.metadata.annotation.Propertyannotation when attaching an OWSM security policy to Oracle Infrastructure web services, as described in Attaching Policies to Oracle Infrastructure Web Services Using Annotations. -
oracle.wsm.metadata.feature.PropertyFeatureannotation when attaching an OWSM security policy to Oracle Infrastructure web service clients, as described in Attaching Policies to Oracle Infrastructure Web Service Clients Using Feature Classes. -
Using JDeveloper, as described in "Attaching Policies" in Developing Applications with Oracle JDeveloper.
To clear a client policy configuration property, set it to the empty string. Before clearing it, consider the other policies that might be using the same property. For web service clients, configuration properties are client-specific; there may be multiple policies attached to the same client that use the same property.
For more information, refer to the following sections:
5.3.3.1 Client Policy Configuration Properties That Can Be Overridden at Design Time
You can override Client Policy Configuration Properties at design time.
Table 5-1 lists the client-side configuration properties you can override programmatically and the policies to which each property applies.
Note:
For JSE clients, you need to configure the jps-config-jse.xml in OPSS for access to the csf keys. For more information about configuring the jps-config-jse.xml file, see "Using OPSS in Java SE Applications" in Securing Applications with Oracle Platform Security Services.
Table 5-1 Client Policy Configuration Properties That Can Be Overridden at Design Time
| Property | Description |
|---|---|
|
|
User name for authentication. |
|
|
Password for authentication. |
|
|
Mapping attribute used to represent the attesting entity. Only the DN is currently supported. This attribute is applicable only to sender vouches message protection use cases. It is not applicable to SAML over SSL policies. |
|
|
Principal name of the client, as generated using the Note: |
|
|
Flag that specifies whether the request is on behalf of an another entity. When set to Otherwise, if the subject is already established, then the username from the subject will be sent as If |
|
|
Relying party, as a comma-separated URI. This property accepts wildcards. For more information, see "saml.audience.uri". |
|
|
Public key alias of the STS. |
|
|
User roles in a SAML assertion. |
|
|
The time in milliseconds for OWSM to request as the token lifetime when obtaining an issued token from a security token service (STS). See "issued.token.lifetime" for more information. |
|
|
Password for the RESTful web service client. Note: This property is valid for RESTful web service clients only. |
|
|
File containing the assertions for SAML HOK policies. |
|
|
On behalf of entity. If present, it will be given preference over Subject (if it exists). |
|
|
Username/password to authenticate to the STS. If |
|
|
X509 certificate for authenticating to the STS. If the |
|
|
Flag that specifies whether to use the OWSM subject. Set to |
|
|
Username for the RESTful web service client. Note: This property is valid for RESTful web service clients only. |
|
|
Username and password corresponding to the Alternatively, you can set the username and password explicitly. See the example later in this section. |
|
|
Alias of the key within the keystore that will be used to decrypt the response from the service. This property overrides any statically configured value. This property is not used in WSS11 policies. Type: java.lang.String |
|
|
Password for the key within the keystore that will be used for decryption. This property overrides any statically configured value. This property is not used in WSS11 policies. Type: java.lang.String |
|
|
Service principal name to use when trying to access a service that is protected using the Kerberos mechanism. This property overrides any static configuration value. Type: java.lang.String |
|
|
Location of the keystore file. For KSS, this is the KSS URI. This property overrides any statically configured value. Type: java.lang.String |
|
|
Password of the keystore file. This property overrides any statically configured value. Type: java.lang.String |
|
|
Type of keystore file. This property overrides any statically configured value. Valid values include: JKS and KSS (default). |
|
|
Alias for the recipient's public key that is used to encrypt type outbound message. This property overrides any static configuration value. Type: java.lang.String |
|
|
SAML issuer name to use when trying access a service that is protected using SAML mechanism. This property overrides any static configuration value. Type: java.lang.String |
|
|
Alias of the key within the keystore that is used for digital signatures. This property overrides any statically configured value. For WSS11 policies, this property is used for mutual authentication only. Type: java.lang.String |
|
|
Password for the alias of the key within the keystore that is used for digital signatures. This property overrides any statically configured value. For WSS11 policies, this property is used for mutual authentication only. Type: java.lang.String |
|
|
The endpoint URI of an STS WSDL, used to obtain STS information and invoke the STS for token exchange. |
|
|
The actual endpoint URI of the STS port. For example: |
|
|
The endpoint of the STS web service. For a WSDL 2.0 STS, the format is specified as |
|
|
The client policy URI that will be used by the client to communicate with the STS. The policy you choose depends on the authentication requirements of the STS, as identified in its WSDL. |
5.3.3.2 Example for Overriding the Client Policy Configuration Properties for Keystore, Username, and Password Using RequestContext
The RequestContext command override the client policy configuration properties for keystore, username, and password.
package example;
import oracle.wsm.security.utils.SecurityConstants;
...
public class MyClientJaxWs {
public static void main(String[] args) {
try {
URL serviceWsdl = new URL("http://localhost/myApp/myPort?WSDL");
QName serviceName = new QName("MyNamespace", "MyService");
Service service = Service.create(serviceWsdl, serviceName);
MyInterface proxy = service.getPort(MyInterface.class);
RequestContext context = (
(BindingProvider)proxy).getRequestContext();
context.put(oracle.webservices.ClientConstants.CLIENT_CONFIG,
new File( "c:/dat/client-pdd.xml" ) );
context.put(BindingProvider.USERNAME_PROPERTY,
getCurrentUsername() );
context.put(BindingProvider.PASSWORD_PROPERTY,
getCurrentPassword() );
context.put(SecurityConstants.ClientConstants.WSS_KEYSTORE_LOCATION,
"c:/mykeystore.jks");
context.put(SecurityConstants.ClientConstants.WSS_KEYSTORE_PASSWORD,
"keystorepassword" );
context.put(SecurityConstants.ClientConstants.WSS_KEYSTORE_TYPE,
"JKS" );
context.put(SecurityConstants.ClientConstants.WSS_SIG_KEY_ALIAS,
"your signature alias" );
context.put(SecurityConstants.ClientConstants.WSS_SIG_KEY_PASSWORD,
"your signature password" );
context.put(SecurityConstants.ClientConstants.WSS_ENC_KEY_ALIAS,
"your encryption alias" );
context.put(SecurityConstants.ClientConstants.WSS_ENC_KEY_PASSWORD,
"your encryption password" );
System.out.println(proxy.myOperation("MyInput"));
} catch (Exception e) {
e.printStackTrace();
}
}
}
WIP
The following example shows c:/dat/client-pdd.xml referenced in the previous example:
! -- The contents of c:/dat/client-pdd.xml file mentioned above -- >
<oracle-webservice-clients>
<webservice-client>
<port-info>
<policy-references>
<policy-reference uri="management/Log_Msg_Policy" category="management"/>
<policy-reference uri="oracle/wss10_username_token_with_message_protection_client_policy" category="security"/>
</policy-references>
</port-info>
</webservice-client>
</oracle-webservice-clients>
5.3.3.3 Example for Overriding the RESTful Web Service Client Policy Configuration Properties for the Username and Password
The following example shows an example of how to override the RESTful web service client policy configuration properties for the username and password.
package example;
import oracle.wsm.security.utils.SecurityConstants;
import com.sun.jersey.api.client.config.ClientConfig;
import com.sun.jersey.api.client.config.DefaultClientConfig;
import oracle.wsm.metadata.feature.PolicyReferenceFeature;
import oracle.wsm.metadata.feature.AbstractPolicyFeature;
import oracle.wsm.metadata.feature.PolicySetFeature;
import oracle.wsm.metadata.feature.PropertyFeature;
...
public class MyRESTfulClient {
public static void main(String[] args) {
...
PropertyFeature uname = new
PropertyFeature(SecurityConstants.ClientConstants.WSM_USERNAME_PROPERTY,"yourusername");
PropertyFeature pwd = new
PropertyFeature(SecurityConstants.ClientConstants.WSM_PASSWORD_PROPERTY,"yourpassword");
PropertyFeature[] propFeatures = new PropertyFeature[] { uname, pwd };
PolicyReferenceFeature clientPRF = new
PolicyReferenceFeature("oracle/wss_http_token_client_policy");
ClientConfig cc = new DefaultClientConfig();
Map<String, Object> properties = cc.getProperties();
properties.put(AbstractPolicyFeature.ABSTRACT_POLICY_FEATURE,new
PolicySetFeature(clientPRF, propFeatures));
...
}
}
5.4 About Overriding Policy Configuration Properties Using Fusion Middleware Control
Web services configuration can be overridden at the domain level, the web service application port level (direct attachments), and at the client application level.
Topics:
5.4.1 Overriding Configuration Properties at the Domain Level (Defining the Default Value)
To override configuration properties at the domain level, you can change the default value of a configuration override property in a policy. When you attach the policy to a web service or client, any web service to which the policy is attached can use these values, or you can override the value when you attach the policy.
For example, you may want to use domain level configuration overrides for keystore configuration and authorization settings:
-
The predefined OWSM message protection policies define a set of server-side override properties such as
keystore.sig.csf.keyandkeystore.enc.csf.key. By default, these properties have a blank value. If you set (or then override) any of the server-side configuration properties, then the new values are used in the attached web service instead of the keystore passwords you configure as part of setting up the keystore for message protection, as described in "Overview of Configuring Keystores for Message Protection".If you do not set these properties and leave the default values, then the values you configure as part of setting up the keystore for message protection are used instead, as described in "Overview of Configuring Keystores for Message Protection".
-
The predefined
oracle/binding_permission_authorization_policydefines a set of server-side override properties:actionandresource. If you set (or then override) these properties, the new values are used in the attached web service instead of the action and resource match patterns you configure as described in "Determining Authorization Permissions".
Note:
The predefined policies are read-only and cannot be edited. You can, however, create new policies using the predefined policies as a base. For information about creating a new policy, see "Creating and Editing Web Service Policies". Once you have created the new policy, you can edit the policy and set the configuration properties as desired.
Perform the following steps to set a value for a configuration property in a policy:
- Navigate to the Web Services Policies page, as described in "Navigating to the WSM Policies Page".
- From the WSM Policies page, select the cloned policy for which you want to set the default value and click Open.
- Select the Assertions tab, then click Configuration.
- In the Configuration page, enter the desired value in the Value field for the property.
- Click OK.
- Click Validate to validate the policy.
- Click Save.
5.4.2 Overriding Configuration Properties for Directly Attached Service Policies Using Fusion Middleware Control
To override configuration properties for directly attached policies, attach the policy to the endpoint in the application, and then override the value for the desired property in the attached policy. Note that you do not have to clone a predefined policy to configure policy overrides at the application level because you are not changing the policy.
Perform the following steps to override a configuration property for a directly attached policy using Fusion Middleware Control:
- Select Override Policy Configuration.
The Security Configuration Details window is displayed, as shown in Figure 5-1. This figure shows the overridable properties for the
oracle/wss10_message_protection_service_policy.Figure 5-1 Overriding a Policy Configuration Property
For example, assume that you have not changed the value of the keystore.sig.csf.key property for the oracle/wss10_message_protection_service_policy and that it is still blank. If web service A attaches the oracle/wss10_message_protection_service_policy and overrides the keystore.sig.csf.key property to be "sigkey," the keystore.sig.csf.key property has a value of "sigkey" only for the oracle/wss10_message_protection_service_policy attached to web service A.
For all other policies, keystore.sig.csf.key uses the value you configure as part of setting up the keystore for message protection, as described in "Overview of Configuring Keystores for Message Protection".
5.4.3 Overriding Configuration Properties at the Web Service Client Application Level Using Fusion Middleware Control
You can override configuration properties at the web service client application level for Java EE and Oracle Infrastructure web service.
Note:
The procedures in this section apply to Java EE and Oracle Infrastructure web service clients only.
Perform the following steps to to override a client configuration property using Fusion Middleware Control:
5.4.4 Overriding Configuration Properties for Globally Attached Policies Using Fusion Middleware Control
If a policy referenced in a policy set contains overridable properties, you can override the existing value of the property for that policy set using Fusion Middleware Control. Because global policy attachments can be scoped at a higher level than direct policy attachments, such as application or domain level, configuration overrides configured in the policy set also apply at the higher scope.
Note:
The procedure in this section applies to Java EE, RESTful, and Oracle Infrastructure web services.
Perform the following steps to override a configuration property in a policy referenced in a policy set:
- Select Override Policy Configuration.
The Override Policy Configuration page is displayed, as shown in Figure 5-2.
Figure 5-2 Policy Set Override Policy Configuration Page
5.5 About Overriding Policy Configuration Properties Using WLST
Web services configuration can be overridden at the web service application level, at the client application level, and for globally attached policies.
Topics:
5.5.1 Overriding Configuration Properties for Directly Attached Service Policies Using WLST
When you attach a policy that has an overridable property, you can override the existing value using the setWSMPolicyOverride command.
Note:
The procedure in this section applies to Oracle Infrastructure and RESTful web services only.
Perform the following steps to override configuration properties for directly attached service policies using WLST:
For more information about this WLST command and its arguments, see "Web Services Custom WLST Commands" in WLST Command Reference for Infrastructure Components.
5.5.2 Overriding Configuration Properties at the Web Service Client Application Using WLST
When you attach a client policy that has an overridable property, you can override the existing value using the setWebServiceClientStubProperty or setWebServiceClientStubProperties commands.
Note:
This procedure applies to Oracle Infrastructure web service clients only.
Perform the following steps to override a client configuration property using WLST:
Note:
You should not override the local.policy.reference.source property. This property is for informational purposes only, to identify the source of the direct policy attachment. For more information, see "Determining the Source of Policy Attachments".
For more information about this WLST command and its arguments, see "Web Services Custom WLST Commands" in WLST Command Reference for Infrastructure Components.
5.5.3 Overriding Configuration Properties for Globally Attached Policies Using WLST
You can specify a configuration override in a policy referenced in a policy set using the setWSMPolicyOverride command. This command can be used only during the creation or modification of a policy set within the context of a session.
Note:
-
The procedure in this section applies to Java EE, RESTful, and Oracle Infrastructure web services.
-
You can also set a configuration override scoped to a policy set using the
setWSMPolicySetOverridecommand. For more information, see "setWSMPolicySetOverride" in WLST Command Reference for Infrastructure Components
The following procedure describes how to specify a configuration override while editing an existing policy set, but you can also use this command in a session while creating a new policy set or creating a policy set from an existing policy set.
5.6 About Configuring User-Defined Properties for Web Service and Client Policies Using Fusion Middleware Control
You can add one or more user-defined server- or client-side properties that have meaning in your environment to a cloned copy of a predefined policy, or to a custom policy. Then, you can either use the user-defined property as-is, or override it when you attach the policy.
Note:
The procedures described in this section apply to Oracle Infrastructure and Restful web services only.
When you either use the user-defined property or override it when you attach the policy, the property must already exist in the policy before you can override it when attaching the policy to a web service or client. That is, you can override only those properties that are already present in the policy.
Therefore, you would typically add a user-supplied property with some default value to the cloned version of the predefined or custom policy, and then override it on a per-attachment basis.
You can add a user-defined property of type required, optional, or constant, but you cannot override a property of type constant.The following sections describe how to configure user-defined override properties:
5.6.1 Scope of User-Defined Configuration Properties
As with the predefined configuration properties, the scope for user-defined configuration properties in a policy differs for clients and web services.
Consider the following:
-
The scope for a client-side configuration property value is the client. There can be multiple policies that are attached to the same client that use the same property.
-
The scope for a server-side configuration property value is limited to the specific policy. That is, you can have two policies with the same server-side configuration property name, say P1, attached to the same web service endpoint, and the two P1 properties can have different values.
5.6.2 Adding a User-Defined Configuration Property
You can edit a cloned copy of a predefined policy, or a custom policy, to add a user-defined configuration property.
Perform the following steps to add a user-defined configuration property:
- Navigate to the WSM Policies page, as described in "Navigating to the WSM Policies Page".
- From the WSM Policies page, select the policy for which you want to add the property and click Open.
- Select the Assertions tab, and then click Configuration.
- In the Configuration page, click Add to add the new property.
- In the table, provide a name and a value for the new property. The Name field is required and must be unique for the policy.
- From the Type menu, select constant, optional, or required. You can subsequently override only properties of type optional and required.
- Click OK.
- Click Validate to validate the policy.
- Click Save.
5.6.3 Editing a User-Defined Configuration Property
User-defined configuration properties can be edited and validated.
Perform the following steps to edit a user-defined configuration property:
- Navigate to the WSM Policies page, as described in "Navigating to the WSM Policies Page".
- From the WSM Policies page, select the policy for which you want to edit the property and click Open.
- Select the Assertions tab, and then click Configuration.
- In the Configuration page, edit the property as required and click OK.
- Click Validate to validate the policy.
- Click Save.
5.6.4 Deleting a User-Defined Configuration Property
You can delete a user-defined configuration property if you no longer need it.
Perform the following steps to delete a user-defined configuration property:
- Navigate to the WSM Policies page, as described in "Navigating to the WSM Policies Page".
- From the WSM Policies page, select the policy for which you want to edit the property and click Open.
- Select the Assertions tab, and then click Configuration.
- In the Configuration page, select the user-defined property to be deleted and click Delete.
- Click OK.
- Click Validate to validate the policy.
- Click Save.