This chapter includes the following sections:
The Web Services Secure Conversation Language (WS-SecureConversation) specification 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).
Link to the specification document: http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.doc
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.
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 OWSM Policies Supported for 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 OWSM Policies Supported for 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 Oracle Web Services Manager Predefined Assertion Templates for additional information.
This section contains the following topics:
This topic describes the steps that you need to perform to configure WS-SecureConversation using Fusion Middleware Control.
To configure the WS-SecureConversation:
You can configure WS-SecureConversation using WSLT.
To configure WS-SecureConversation:
For more information about the WLST commands and their arguments, see "Web Services Custom WLST Commands" in WLST Command Reference for WebLogic Server.
You can attach a WS-SecureConversation policy at design time by using the annotations API.
The API is described in Understanding Attaching Policies to Web Services and Clients at Design Time.
The following examples attach the oracle/wss11_username_token_with_message_protection_wssc_service_policy policy alone and in a policy set.
@PortableWebService
@oracle.webservices.annotations.SecurityPolicy(
"oracle/wss11_username_token_with_message_protection_wssc_service_policy")
public class TestService {
...... }
@PortableWebService @PolicySet(references= {@PolicyReference(value="oracle/wss11_username_token_with_message_protection_wssc_service_policy"), @PolicyReference(value="oracle/wsrm11_policy") }) public class TestService { ...... }
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.
For more information, see "Persistence" in Understanding Oracle Web Services Manager.
This section contains the following topics:
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.
Note:
You can configure persistence as described in this section only for Oracle Infrastructure web services and clients.
For WebLogic (Java EE) web services, you configure persistence as described in "Configuring Web Service Persistence" in Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server.
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.
This topic describes how to 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 Understanding 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 About Attaching Policies to Web Services and Clients Using Fusion Middleware Control and About Attaching Policies to Web Services and Clients Using WLST respectively.
This topic describes how to 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 About Attaching Policies to Web Services and Clients Using Fusion Middleware Control and About Attaching Policies to Web Services and Clients Using WLST respectively.
OWSM maintains the client and server secure conversation session information based on a computed Session ID. OWSM (via an internal session mechanism) computes the Session ID at runtime for each message, and associates one or more requests to a session.
This is described in "WS-SecureConversation Architecture".
The session ID is generally reused if:
A subsequent request comes from the same client and the session ID has not already been freed. (If the session ID has already been freed, a new session ID is created.)
The sc.token.lifetime property has not expired.
Once created, Secure Conversation session ID's are not removed automatically until the underlying Java virtual machine used to start the WebLogic Server instance shuts down.
The session management WLST commands provide a way for you to free up the session ID's on the server in the following situations:
You detect any issue with server performance and you want to free up the resources on the server.
The SCT token has expired. There is an expiration time displayed by the getWebServiceSessionInfo() command. If the SCT token has expired, you can remove the session ID.
Note:
The scope of session is the current Persistence provider. That is, you can list and remove only those session ID's that are stored within the current Persistence provider.
OWSM provides the following WLST commands that you can use to manage Secure Conversation sessions.
Note:
All of the WebLogic Server instances within a domain must be running in order for the WLST commands to succeed.
listWebServiceSessionNames() — Lists the names of all sessions visible within the instance of a running server. The returned names are appropriate for use as the name parameter in subsequent calls to getWebServiceSessionInfo(String) and removeWebServiceSession(String) commands.
For example:
wls:/base_domain/serverConfig> listWebServiceSessionNames()
215d0d4a5ebbc3fec662f46adedc5bc74ecbc87b
getWebServiceSessionInfo() — Given a session name, get a data object representing current information for that session. The returned information is as follows.
name
creation time
last update time
expiration time
KeyInfo[] user-defined keys, where KeyInfo is keyName and keyValue.
For example:
wls:/base_domain/serverConfig>
getWebServiceSessionInfo('215d0d4a5ebbc3fec662f46adedc5bc74ecbc87b')
Name: 215d0d4a5ebbc3fec662f46adedc5bc74ecbc87b
Creation time: Mon Nov 04 17:47:39 PST 2013
Last update time: Mon Nov 04 17:47:42 PST 2013
Expiration time: Mon Nov 04 18:17:41 PST 2013
Key info: [oracle.wsm.security.secconv.util.property.SCT, 0x0000014225F1A1260AE4F30351FD1544DC10ED14201988C8CFEDFDBE8E0E4B09
]
listWebServiceSessionNamesForKey() — Lists the names of all sessions identified by keyName and keyValue.
The returned names are appropriate for use as the name parameter in subsequent calls to getWebServiceSessionInfo(String) and removeWebServiceSession(String) commands.
For example:
wls:/base_domain/serverConfig> listWebServiceSessionNamesForKey('oracle.wsm.security.secconv.util.property.SCT', '0x0000014225F1A1260AE4F30351FD1544DC10ED14201988C8CFEDFDBE8E0E4B09') 215d0d4a5ebbc3fec662f46adedc5bc74ecbc87b
removeWebServiceSession() — Given a session name, removes the session object associated with that session name.
For example:
wls:/base_domain/serverConfig>
removeWebServiceSession('215d0d4a5ebbc3fec662f46adedc5bc74ecbc87b')
For more information about the WLST commands and their arguments, see "Session Management WLST Commands" in WLST Command Reference for WebLogic Server.