46 Enabling Security with Policies and Message Encryption

This chapter describes how to attach policies to binding components and service components during design-time in SOA composite applications and encrypt and decrypt specific fields of messages. Policies apply security to the delivery of messages. This chapter also describes how to override policy configuration property values.

This chapter includes the following sections:

• Introduction to Policies

• Attaching Policies to Binding Components and Service Components

• Encrypting and Decrypting Specific Fields of Messages

46.1 Introduction to Policies

Oracle Fusion Middleware uses a policy-based model to manage and secure Web services across an organization. Policies apply security to the delivery of messages. Policies can be managed by both developers in a design-time environment and system administrators in a runtime environment.

Policies are comprised of one or more assertions. A policy assertion is the smallest unit of a policy that performs a specific action. Policy assertions are executed on the request message and the response message, and the same set of assertions is executed on both types of messages. The assertions are executed in the order in which they appear in the policy.

Table 46-1 describes the supported policy categories.

---

Table 46-1 Supported Policy Categories

Category	Description
Message Transmission Optimization Mechanism (MTOM)	Ensures that attachments are in MTOM format. This format enables binary data to be sent to and from web services. This reduces the transmission size on the wire.
Reliability	Supports the WS-Reliable Messaging protocol. This guarantees the end-to-end delivery of messages.
Addressing	Verifies that simple object access protocol (SOAP) messages include WS-Addressing headers in conformance with the WS-Addressing specification. Transport-level data is included in the XML message rather than relying on the network-level transport to convey this information.
Security	Implements the WS-Security 1.0 and 1.1 standards. They enforce authentication and authorization of users. identity propagation, and message protection (message integrity and message confidentiality).
Management	Logs request, response, and fault messages to a message log. Management policies can also include custom policies.

---

Within each category there are one or more policy types that you can attach. For example, if you select the reliability category, the following types are available for selection:

• oracle/no_reliable_messaging_policy

  Supports the disabling of reliable messaging configured at a higher scope

• oracle/no_wsrm_policy

  Supports the disabling of a globally attached Web Services Reliable Messaging policy

• oracle/reliable_messaging_policy

  Supports the enabling of Web services reliable messaging

• oracle/wsrm10_policy

  Supports version 1.0 of the Web Services Reliable Messaging protocol

• oracle/wsrm11_policy

  Supports version 1.1 of the Web Services Reliable Messaging protocol

For more information about available policies, details about which ones to use in your environment, and global policies, see Securing Web Services and Managing Policies with Oracle Web Services Manager.

46.2 Attaching Policies to Binding Components and Service Components

You can attach or detach policies to and from service binding components, service components, and reference binding components in a SOA composite application. Use Oracle JDeveloper to attach policies for testing security in a design-time environment. When your application is ready for deployment to a production environment, you can attach or detach runtime policies in Oracle Enterprise Manager Fusion Middleware Control.

For more information about runtime management of policies, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.

46.2.1 How to Attach Policies to Binding Components and Service Components

To attach policies to binding components and service components:

1. In the SOA Composite Editor, right-click a service binding component or reference binding component.
2. Select Configure SOA WS Policies.

   Depending upon the interface definition of your SOA composite application, you may be prompted with an additional menu of options.

   • If the selected service or reference is interfacing with a synchronous BPEL process or Oracle Mediator service component, a single policy is used for both request and response messages. The Configure SOA WS Policies dialog immediately appears. Go to Step 4.

   • If the service or reference is interfacing with an asynchronous BPEL process or Oracle Mediator service component, the policies must be configured separately for request and response messages. The policy at the callback is used for the response sent from service to client. An additional menu is displayed. Go to Step 3.

3. Select the type of binding to use:

   • For Request:

     Select the request binding for the service component with which to bind. You can only select a single request binding. This action enables communication between the binding component and the service component.

     When request binding is configured for a service in the Exposed Services swimlane, the service acts as the server. When request binding is configured for a reference in the External References swimlane, the reference acts as the client.

   • For Callback: (only for interactions with asynchronous processes)

     Select the callback binding for the service component with which to bind. This action enables message communication between the binding component and the service component. You can only select a single callback binding.

     When callback binding is configured for a service in the Exposed Services swimlane, the service acts as the client. When callback binding is configured for a reference in the External References swimlane, the reference acts as the server.

   The Configure SOA WS Policies dialog shown in Figure 46-1 appears. For this example, the For Request option was selected for a service binding component. The same types of policy categories are also available if you select For Callback.

   Figure 46-1 Configure SOA WS Policies Dialog

   
   Description of "Figure 46-1 Configure SOA WS Policies Dialog"
4. Click the Add icon next to the type of policy to attach:

   • MTOM

   • Reliability

   • Addressing

   • Security

   • Management

   For this example, Security is selected. The dialog shown in Figure 46-2 is displayed.

   Figure 46-2 Security Policies

   
   Description of "Figure 46-2 Security Policies"
5. Click the icon to the right of the policy name to display a description of policy capabilities.
6. Select the type of policy to attach.
7. Click OK.

   You are returned to the Configure SOA WS Policies dialog shown in Figure 46-3. The attached security policy displays in the Security section.

   Figure 46-3 Attached Security Policy

   
   Description of "Figure 46-3 Attached Security Policy"
8. If necessary, add additional policies.

   You can temporarily disable a policy by clicking the Disable selected policies icon. Figure 46-4 provides details. This action does not detach the policy.

   Figure 46-4 Disable Selected Policies Icon

   
   Description of "Figure 46-4 Disable Selected Policies Icon"
9. To enable the policy again, click the Enable selected policies icon to the left.
10. To detach a policy, click the Delete icon.
11. When complete, click OK in the Configure SOA WS Policies dialog.

    You are returned to the SOA Composite Editor.

12. Place your cursor over the icon on the service binding component to display details about the attached policy. Figure 46-5 provides details.

    Figure 46-5 Policy Description Icon

    
    Description of "Figure 46-5 Policy Description Icon"

46.2.1.1 To attach a policy to a service component:

1. Right-click a service component.

2. Select Configure SOA WS Policies.

   The Configure SOA WS Policies dialog shown in Figure 46-6 appears.

   Figure 46-6 Configure SOA WS Policies Dialog

   
   Description of "Figure 46-6 Configure SOA WS Policies Dialog"

3. Click the Add icon next to the type of policy to attach.

   • Security

   • Management

   The dialog for your selection appears.

4. Select the type of policy to attach.

5. Click OK.

6. If necessary, add additional policies.

7. When complete, click OK in the Configure SOA WS Policies dialog.

For information about attaching policies during runtime in Oracle Enterprise Manager Fusion Middleware Control, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.

46.2.2 How to Override Policy Configuration Property Values

Your environment may include multiple clients or servers with the same policies. However, each client or server may have their own specific policy requirements. You can override the policy property values based on your runtime requirements.

46.2.2.1 Overriding Client Configuration Property Values

You can override the default values of client policy configuration properties on a per client basis without creating new policies for each client. In this way, you can override client policies that define default configuration values and customize those values based on your runtime requirements.

1. Right-click one of the following binding components:

   • A service binding component in the Exposed Services swimlane, and select For Callback.

   • A reference binding component in the External References swimlane, and select For Request.

2. Go to the Security and Management sections. These instructions assume you previously attached policies in these sections.

   The Edit icon is enabled for both sections. Figure 46-7 provides details.

   Figure 46-7 Client Policy Selection

   
   Description of "Figure 46-7 Client Policy Selection"
3. Click the Edit icon.
4. In the Override Value column, enter a value to override the default value shown in the Value column. Figure 46-8 provides details.

   Figure 46-8 Client Policy Override Value

   
   Description of "Figure 46-8 Client Policy Override Value"
5. Click OK to exit the Config Override Properties dialog.
6. Click OK to exit the Configure SOA WS Policies dialog.

For more information about overriding policy settings, see Securing Web Services and Managing Policies with Oracle Web Services Manager.

46.2.2.2 Overriding Server Configuration Property Values

You can override the default values of server policy configuration properties on a per server basis without creating new policies for each server. In this way, you can override server policies that define default configuration values and customize those values based on your runtime requirements.

To override server configuration property values:

1. Right-click one of the following binding components:

   • A service binding component in the Exposed Services swimlane, and select For Request.

   • A reference binding component in the External References swimlane, and select For Callback.

2. Go to the Security or Management section. These instructions assume you previously attached policies in these sections.

   The Edit icon is not enabled by default for both sections. You must explicitly select a policy to enable this icon. This is because you can override fewer property values for the server. Figure 46-9 provides details.

   Figure 46-9 Server Policy Selection

   
   Description of "Figure 46-9 Server Policy Selection"
3. Select an attached policy that permits you to override its value, and click the Edit icon.
4. In the Override Value column, enter a value to override the default value shown in the Value column. Figure 46-10 provides details. If the policy store is unavailable, the words no property store found in the store display in red in the Value column.

   Figure 46-10 Server Policy Override Value

   
   Description of "Figure 46-10 Server Policy Override Value"
5. Click OK to exit the Config Override Properties dialog.
6. Click OK to exit the Configure SOA WS Policies dialog.

   For more information about overriding policy settings, see Securing Web Services and Managing Policies with Oracle Web Services Manager.

46.3 Encrypting and Decrypting Specific Fields of Messages

You can encrypt and decrypt fields of a message to protect sensitive data (known as personally identifiable information (PII)) flowing in web services and JCA adapters in Oracle SOA Suite and Oracle Service Bus. This feature provides for the obfuscation of certain fields (for example, SSNs) to prevent this data from appearing in administration consoles in clear text.

Figure 46-11 shows an incoming message being encrypted when entering the SOA composite application in a service binding component and an outgoing message being decrypted when exiting the SOA composite application in a reference binding component. Messages outside the composite can be protected with other message protection policies (WS-Security/SSL).

Figure 46-11 Message Encryption and Decryption in a SOA Composite Application

Description of "Figure 46-11 Message Encryption and Decryption in a SOA Composite Application"

The following code shows an example of an unencrypted message. The PII fields are name and driversLicense.

<person>
  <name>John</name>
  <driversLicense>B1234</driversLicense>
  <ssn>123-456-789</ssn>
</person>

The following code shows an example of the encrypted message with the name and driversLicense fields in encrypted format.

<person>
  <name>John</name>
 <driversLicense>encrypted:fdslj[lmsfwer09fsn;keyname=pii-csf-key</driversLicense>
  <ssn>encrypted:gdf45md%mfsd103k;keyname=pii-csf-key</ssn>
</person>

The encryption format is as follows:

encrypted:<CIPHER_TEXT>;keyname:<CSF_KEY_NAME>

Note:

If both a PII policy and authorization policy are attached to a SOA composite application, the authorization policy is executed before the PII policy. This is because the PII policy may encrypt the field used for authorization.

If the authorization policy is attached to a component and it requires an already-encrypted field, authorization fails.

46.3.1 How to Encrypt and Decrypt Specific Fields of Messages

Note:

• You must decrypt PIIs when an encrypted message leaves the composite. If you attach a PII policy to a service binding component and do not attach a PII policy to a reference binding component, PIIs in the outbound message are not decrypted. This is not a recommended practice, and you receive a runtime error.

• PIIs encrypted in one SOA composite application cannot be decrypted in another SOA composite application.

To encrypt and decrypt specific fields of messages:

1. Right-click a service binding component, and select Protect Sensitive Data > Encrypt Request Data.

   The PII Configuration dialog is displayed, as shown in Figure 46-12.

   You must now perform the initial encryption on the incoming message.

   Figure 46-12 PII Configuration Dialog for Encryption

   
   Description of "Figure 46-12 PII Configuration Dialog for Encryption"
2. Click the Edit icon to identify the elements in the schema to encrypt.

   The Input tab of the Select fields to encrypt dialog is displayed.

3. Click the Add icon to create an XPath expression that identifies the fields of the request message to encrypt (for example, a user's name, credit card number, or social security number).
4. Click the CSF tab.
5. Select the credential store framework (CSF) key to use. The credential store is used for the secure storage of credential keys.

   After encryption is complete, the message proceeds through the service components of the SOA composite application.

   When the message reaches a reference binding component and is ready to exit the SOA composite application, you must decrypt the encrypted message.

6. Right-click the reference binding component, and select Decrypt Sensitive Data. Figure 46-13 provides details.

   Figure 46-13 PII Configuration Dialog for Decryption

   
   Description of "Figure 46-13 PII Configuration Dialog for Decryption"
7. Click the Edit icon.

   The Input tab of the Select fields to decrypt dialog is displayed. For asynchronous processes, there are two steps: one for the input message and one for the output message.

8. Click the Add icon to invoke the Expression Builder dialog for creating an XPath expression that identifies the fields to decrypt (for example, a credit card number or driver's license field).
9. Click OK when complete.

   After configuring composites with oracle/pii_security_policy, you must add keys and user credentials to the credential store.

10. Use the createCred WLST command to create entries in the oracle.wsm.security credential map for any csf-key user credentials.

    connect("weblogic","password","t3://myAdminServer.example.com:7001")
    
    wls:/DefaultDomain/serverConfig> createCred(map="oracle.wsm.security",
    key="pii-csf-key", user="weblogic", password="password", desc="Key for
    pii_security_policy")
    

    If you do not perform this task, the following error occurs:

    oracle.wsm.security.SecurityException: WSM-00016 : The
    username/password credentials or certificates pii-csf-key are missing.