This chapter describes how 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 includes the following sections:
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 Section 3.9, "Which OWSM 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 Section 3.9, "Which OWSM 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 18, "Oracle Web Services Manager Predefined Assertion Templates" for additional information.
This section contains the following topics:
This section describes the steps that you need to perform to configure WS-SecureConversation using Fusion Middleware Control. They are as follows:
Optionally, configure WS-Secure Conversation at the domain level, as described in Section 14.5.4, "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 Section 3.9, "Which OWSM Policies Support WS-SecureConversation?" and make a copy.
Edit the clone of the policy.
Select the Assertions tab.
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.
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.
The following additional controls are available. The default settings depend on the policy type.
Version. OWSM supports both Secure Conversation versions 1.3 and 1.4. Although the policy displays the 1.3 version number, you use this policy for 1.4 as well.
The following Bootstrap Message Security options are available
Inherit From Application Setting. This is the default: the message security settings for the inner policy are derived from the outer policy.
Use Independent Setting.
When selected, the following options are available: Algorithm Suite, Encrypt Signature, Confirm Signature, and Include Timestamp.
Click Configuration.
The Configuration page displays a list of the configuration properties for the policy.
The sc.token.lifetime property specifies the default number of milliseconds after which the secure conversation session should expire. The security context is shared by the client and web service for the lifetime of a communication session. This is the time after which the SCT is expired.
If you do not explicitly set this value, the domain-wide setting applies, as described in Section 14.5.4, "Configuring Secure Conversation for the Domain Using Fusion Middleware Control."
If this policy is not already attached to your web service, attach it as described in Chapter 4, "Attaching Policies to Manage and Secure Web Services."
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.
Begin a session using the beginWSMSession command, as described in Section 4.4.3.2, "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 Section 4.4.3.1, "Identifying and Selecting the Policy Subject Using WLST."
Use the attachWSMPolicy command to attach a secure conversation policy to a web service port, as described in Section 4.4.3.2, "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 Section 5.5.1, "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.
You can attach a WS-SecureConversation policy at design time by using the annotations API, as described in Section 4.2, "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 { ...... }
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.
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 section 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 Section 4.2, "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 Section 4.3, "Attaching Policies to Web Services and Clients Using Fusion Middleware Control" and Section 4.4, "Attaching Policies to Web Services and Clients Using WLST" respectively.
This section 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 Section 4.3, "Attaching Policies to Web Services and Clients Using Fusion Middleware Control" and Section 4.4, "Attaching Policies to Web Services and Clients Using WLST" respectively.
As described in "WS-SecureConversation Architecture", 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.
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.