11 Configuring Secure Conversation

OWSM implements the Web Services Trust (WS-Trust 1.3) and Web Services Secure Conversation (WS-SecureConversation 1.3) specifications, which together provide secure communication between Web services and their clients. You can use WS-SecureConversation to increase the performance and security of your Web services.

The Web Services Secure Conversation Language (WS-SecureConversation) specification (http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.doc) defines extensions that build on Web Services Security (WS-Security) 1.1 and 1.0 and Web Services Trust Language (WS-Trust) to provide secure communication across one or more messages. Specifically, this specification defines mechanisms for establishing and sharing security contexts, and deriving keys from established security contexts (or any shared secret).

A particularly important use of WS-SecureConversation is to provide security for WS-ReliableMessaging (WS-RM) policies, as described in "Using WS-SecureConversation With WS-ReliableMessaging" in Understanding Oracle Web Services Manager. When you attach both a WS-SecureConversation policy and a WS-RM policy, the WS-RM policy benefits from the use of secure conversation to prevent sequence attacks.

You can also attach a WS-SecureConversation policy to an asynchronous Web service either with or without a WS-RM policy. The following combinations are possible:

WS-RM policy and a WS-SecureConversation policy
Asynchronous Web service, a WS-RM policy, and a WS-SecureConversation policy

For more information on secure conversation and when you might want to use it, see "Understanding Secure Conversation" in Understanding Oracle Web Services Manager.

This chapter contains the following sections:

Section 11.1, "Configure Secure Conversation"
Section 11.2, "Configure Secure Conversation: Advanced Management"
Section 11.3, "Attaching a Secure Conversation Policy at Design Time"
Section 11.4, "Configure Persistence"

11.1 Configure Secure Conversation

In most cases, you do not need to perform any WS-SecureConversation-specific configuration other than creating a policy and enabling secure conversation. If you use the preconfigured WS-SecureConversation policies described in "Which Policies Support WS-SecureConversation?", WS-SecureConversation is already enabled. All of the other configuration that is needed is the same as for the policy without WS-SecureConversation.

If you configure WS-SecureConversation, you must configure it for both the Web service and client policies. This is because the OWSM client and server agents participate in the handshake process to establish the Security Context Token (SCT) used to secure the conversation. The OWSM client sends the RST (Request Security Token) to the service, which then returns the RSTR (Request Security Token Response) containing the SCT.

The OWSM security policies described in "Which Policies Support WS-SecureConversation?" include a configuration setting that allows you to enable and configure WS-SecureConversation for that policy. You may find that using these preconfigured policies makes your security tasks easier to view at a glance and manage.

In addition, policies based on many of the predefined assertion templates also support WS-SecureConversation. See Chapter 19, "Predefined Assertion Templates" for additional information.

Perform the following steps to configure WS-SecureConversation:

Optionally, configure WS-Secure Conversation at the domain level, as described in "Configuring Secure Conversation for the Domain Using Fusion Middleware Control". You need to do this only if the defaults do not meet your needs.
In the content pane, click WebLogic Domain, then Web Services, and then Policies.
Select one of the preconfigured WS-SecureConversation policies, or another security policy for which you want to enable WS-SecureConversation from the list in "Which Policies Support WS-SecureConversation?" and make a copy.
If you selected one of the preconfigured WS-SecureConversation policies, skip to the last step to attach the policy.
If you did not select one of the preconfigured WS-SecureConversation policies, edit the copy of the policy.
Scroll down to the Secure Conversation section of the page.

For the preconfigured WS-SecureConversation policies, secure conversation is enabled by default. For all of the other policies, secure conversation is disabled by default, as shown in Figure 11-1.

Figure 11-1 Secure Conversation Default Settings
If you want to simply enable secure conversation for this policy without changing any of the default settings, click Enabled and then click Save to complete your changes.

You can enable the re-authenticate control only for SAML sender vouches policies when the propagate.identity.context configuration attribute is set to True, as described in "When to Use Re-Authentication."

If you need to make additional changes, continue with "Configure Secure Conversation: Advanced Management".
If this policy is not already attached to your Web service, attach it as described in Chapter 4, "Attaching Policies".

11.1.1 Configure Secure Conversation With WLST

Perform the following steps to configure WS-SecureConversation using WLST:

Connect to the running instance of WebLogic Server, as described in "Accessing the Web Services Custom WLST Commands" in Administering Web Services with Oracle Fusion Middleware.
Begin a session using the beginWSMSession command, as described in "Attaching Policies Directly Using WLST". For example:
```
wls:/wls_domain/serverConfig> beginWSMSession()

Session started for modification.
```
Select the policy subject that you want to work with. See "Identifying and Selecting the Policy Subject Using WLST".

Use the attachWSMPolicy command to attach a copy of the secure conversation policy to a Web service port, as described in "Attaching Policies Directly Using WLST". For example:

wls:/wls_domain/serverConfig> attachWSMPolicy('oracle/wss_username_token_over_ssl_wssc_client_policy')

Policy reference "oracle/wss_username_token_over_ssl_wssc_client_policy" added.

Use the setWSMPolicyOverride command to override policy properties, as described in "Overriding Configuration Properties for Directly Attached Service Policies Using WLST".
```
setWSMPolicyOverride(policyURI,property, value)
```
Write the contents of the current session to the repository using the commitWSMSession() command.

For more information about the WLST commands and their arguments, see "Web Services Custom WLST Commands" in WLST Command Reference for WebLogic Server.

11.2 Configure Secure Conversation: Advanced Management

As described in "Using Basic Mode Versus Advanced Mode" in Understanding Oracle Web Services Manager, a secure conversation policy has actually two policies: inner and outer.

Note:

The Bootstrap Message Security control that exposes the inner and outer policies is not applicable to SSL-based policies.

The bootstrap (inner) policy is used to obtain the token and establish the handshake between the client and the Web service. The outer policy is used for application messages when making requests with the token.

The message security settings for the outer policy are obtained from the original OWSM WS-Security policy, such as such as oracle/wss11_username_with_message_protection. The message security settings for the inner policy are then derived from the outer policy.

Although in most cases you do not need to be concerned with the details of the inner and outer policies, the OWSM WS-SecureConversation implementation provides an Advanced setting that provides additional control. For example, you might want the encrypt signature to be different from that of the outer policy.

Perform the following steps to configure the Advanced mode:

In the navigator pane, expand WebLogic Domain to show the domain for which you need to configure WS-SecureConversation. Select the domain.
In the content pane, click WebLogic Domain, then Web Services, and then Policies.
Select one of the preconfigured WS-SecureConversation policies, or another security policy for which you want to enable WS-SecureConversation from the list in "Which Policies Support WS-SecureConversation?", and make a copy.
Edit the copy.
Scroll down to the Secure Conversation section of the page.

For the preconfigured WS-SecureConversation policies, secure conversation is enabled by default. For all of the other policies, secure conversation is disabled by default, as shown in Figure 11-2.

Figure 11-2 Secure Conversation Default Settings
Click Enabled.

You can enable the re-authenticate control only for SAML sender vouches policies when the propagate.identity.context configuration attribute is set to True, as described in "When to Use Re-Authentication."
Select Advanced from the View Mode to show additional WS-SecureConversation settings. The settings shown in Figure 11-2 become available.

Figure 11-3 Secure Conversation Advanced Fields

The following Advanced options are available:
- Client entropy — This is used as key material for the requested proof token.
- Server entropy — This is used as key material for the requested proof token.
- Derived Keys — Instead of using the same SCT across multiple requests, a different key derived from the SCT is used in each request, which improves overall security.)
- Bootstrap Message Security: (Not applicable to SSL policies.)
  - Inherit From Application Setting
  - Use Independent Setting. When selected, the following options are available: Algorithm Suite, Encrypt Signature, Signature Confirmation, and Include Timestamp.
Edit the policy as needed.
Click Save to complete your changes.
If this policy is not already attached to your Web service, attach it as described in Chapter 4, "Attaching Policies".

11.3 Attaching a Secure Conversation Policy at Design Time

You can attach a WS-SecureConversation policy at design time by using the annotations API, as described in Attaching Policies to Web Services and Clients at Design Time.

Consider the examples shown in Example 11-1 and Example 11-2, which attach the oracle/wss11_username_token_with_message_protection_wssc_service_policy policy alone and in a policy set.

Example 11-1 Attaching the WS-SecureConversation Policy

@PortableWebService @oracle.webservices.annotations.SecurityPolicy(
"oracle/wss11_username_token_with_message_protection_wssc_service_policy")
 
public class TestService { 
 
...... }

Example 11-2 Attaching the WS-SecureConversation Policy in a Policy Set

@PortableWebService 
@PolicySet(references=
{@PolicyReference(value="oracle/wss11_username_token_with_message_protection_wssc_service_policy"), 
  @PolicyReference(value="oracle/wsrm11_policy")
}) 
 
public class TestService { 
 
...... }

11.4 Configure Persistence

As described in "Persistence" in Understanding Oracle Web Services Manager, each client and Web service can specify one or more (one per port) persistence providers, which can be either the Coherence provider or the in-memory provider.

Note:

You can configure persistence only for Oracle Infrastructure Web services and clients. For WebLogic (Java EE) Web services that attach WS-SecureConversation policies, the default persistence configuration is in effect.

The Coherence persistence provider is the default when running in WebLogic Server, for both the Web service client and Web service. Otherwise, the in-memory persistence provider is the default.

The following configuration rules apply:

By default, the client uses the Coherence provider if it is running in WebLogic Server; otherwise, the client uses the in-memory provider. The Web service uses the Coherence provider if deployed to WebLogic Server; otherwise, it uses the in-memory provider.
You can specify one persistence mechanism (per port) for the Web service and one for the client, as dictated by your quality of service requirements. There is no requirement that the client and Web service use the same providerName type, as their configurations may not be the same.
No matter which mechanism you choose, if providerName is blank, oracle:jrf:Coherence is used if available; otherwise oracle:jrf:Memory is used.
If you explicitly set oracle:jrf:Coherence and it is not available, an error is returned.

To configure persistence, you can use any of the following mechanisms. In each case, you specify only the providerName, which can be only oracle:jrf:Memory or oracle:jrf:Coherence.

Configure Persistence for a Web Service

Use the @Persistence policy annotation in the Web service at design time, as described in "@Persistence" and shown in the following example:

@PortableWebService
@SecurityPolicy("oracle/wss11_username_token_with_message_protection_wssc_service_policy") 
@Persistence(providerName="oracle:jrf:Coherence") 
 
public class TestService {
 ...... 
}

Use the @PolicyReference policy annotation in the Web service at design time, as described in "Attaching Policies to Web Services and Clients at Design Time" and shown in the following example:

@PortableWebService
@SecurityPolicy("oracle/wss11_username_token_with_message_protection_wssc_service_policy") 
@PolicySet(references={
  @PolicyReference(value="oracle/wss11_username_token_with_message_protection_wssc_service_policy"),
  @PolicyReference(value="oracle/persistence_policy")
 }) 
 
public class TestService {
 ...... 
}

Attach the oracle/persistence_policy policy and set the providerName attribute via Fusion Middleware Control or WLST post deployment, as described in "Attaching Policies to Web Services and Clients Using Fusion Middleware Control" and "Attaching Policies to Web Services and Clients Using WLST", respectively.

Configure Persistence for a Client

Use the policy-reference element in the client at design time and set the provider.name property, as shown in the following example:

String configString = 
"<port-info>\n" + 
" <policy-references>\n" + 
" <policy-reference uri=\"oracle/wss11_username_token_with_message_protection_wssc_client_policy\" category=\"security\"/>\n" + 
" <policy-reference uri=\"oracle/persistence_policy\" category=\"wsconfig\">" + 
" <property name=\"provider.name\" value=\"oracle:jrf:Memory\"/>" + 
" </policy-reference>" + " </policy-references>\n" + "</port-info>";
 // convert configString to Element 
 
((BindingProvider) port).getRequestContext().put(
         ClientConstants.CLIENT_CONFIG, configElement);

Set PersistenceFeature at design time, as shown in the following example:

PersistenceFeature persistenceFeature =
    PersistenceFeature.builder().providerName("oracle:jrf:Memory").build(); 
 
port = service.getPort(new WebServiceFeature[] {persistenceFeature});

Attach the oracle/persistence_policy policy and set the providerName attribute via Fusion Middleware Control or WLST post deployment, as described in "Attaching Policies to Web Services and Clients Using Fusion Middleware Control" and "Attaching Policies to Web Services and Clients Using WLST", respectively.