The following sections describe how to configure security for your Web Service:
Message-level security specifies whether the SOAP messages between a client application and the Web Service invoked by the client should be digitally signed or encrypted or both. It also can specify a shared security context between the Web Service and client in the event that they exchange multiple SOAP messages. You can use message-level security to assure:
See Configuring Simple Message-Level Security: Main Steps for the basic steps you must perform to configure simple message-level security. This section discusses configuration of the Web Services runtime environment, as well as configuration of message-level security for a particular Web Service and how to code a client application to invoke the service.
You can also configure message-level security for a Web Service at runtime, after a Web Service has been deployed. See Associating Policy Files at Runtime Using the Administration Console for details.
Note: | You cannot digitally sign or encrypt a SOAP attachment. |
WebLogic Web Services implement the following OASIS Standard 1.1 Web Services Security (WS-Security 1.1) specifications, dated February 1, 2006:
These specifications provide security token propagation, message integrity, and message confidentiality. These mechanisms can be used independently (such as passing a username token for user authentication) or together (such as digitally signing and encrypting a SOAP message and specifying that a user must use X.509 certificates for authentication).
WebLogic Web Services also implement the Web Services Trust Language (WS-Trust) and Web Services Secure Conversation Language (WS-SecureConversation 1,2) specifications which together provide secure communication between Web Services and their clients (either other Web Services or standalone Java client applications). In particular, the WS-SecureConversation specification defines mechanisms for establishing and sharing security contexts, and deriving keys from security contexts, to enable a secure conversation. Together, the security context and derived keys potentially increase the overall performance and security of the subsequent exchanges.
The WS-Policy specification defines a framework for allowing Web Services to express their constraints and requirements. Such constraints and requirements are expressed as policy assertions. WS-SecurityPolicy defines a set of security policy assertions for use with the WS-Policy framework to describe how messages are to be secured in the context of WSS: SOAP Message Security, WS-Trust and WS-SecureConversation. You configure message-level security for a Web Service by attaching one or more policy files that contain security policy statements, as specified by the WS-SecurityPolicy specification. See Using Policy Files for Message-Level Security Configuration for detailed information about how the Web Services runtime environment uses security policy files. The Web Services SecurityPolicy specification is not final as of this release of WebLogic Server. For information about the elements of the Web Services SecurityPolicy 1.2 draft dated 21 February 2007, that are not supported in this release of WebLogic Server, see Unsupported WS-SecurityPolicy 1.2 Assertions.
The BEA implementation of the Web Services Security: SOAP Message Security specification supports the following use cases:
You specify the details of message-level security for a WebLogic Web Service with one or more security policy files. The WS-SecurityPolicy specification provides a general purpose model and XML syntax to describe and communicate the security policies of a Web Service.
Note: | Previous releases of WebLogic Server, released before the formulation of the WS-SecurityPolicy specification, used security policy files written under the WS-Policy specification, using a proprietary BEA schema for security policy. This release of WebLogic Server supports either security policy files that conform to the WS-SecurityPolicy 1.2 specification or the BEA Web Services security policy schema first included in WebLogic Server 9. For information about the packaged WS-SecurityPolicy 1.2 security policy files, see Using WS-SecurityPolicy 1.2 Policy Files. For information about the packaged BEA Web Services security policy schema files, see BEA Web Services Security Policy Files. |
The security policy files used for message-level security are XML files that describe whether and how the SOAP messages resulting from an invoke of an operation should be digitally signed or encrypted. They can also specify that a client application authenticate itself using a username, SAML, or X.509 token.
You use the @Policy
and @Policies
JWS annotations in your JWS file to associate policy files with your Web Service. You can associate any number of policy files with a Web Service, although it is up to you to ensure that the assertions do not contradict each other. You can specify a policy file at both the class- and method-level of your JWS file.
The following procedure describes how to configure simple message-level security for the Web Services security runtime, a particular WebLogic Web Service, and a client application that invokes an operation of the Web Service. In this document, simple message-level security is defined as follows:
WARNING: | If you plan to deploy the Web Service to a cluster in which different WebLogic Server instances are running on different computers, you must use a keystore and key pair other than the out-of-the-box ones, even for testing purposes. The reason is that the key pairs in the default WebLogic Server keystore, DemoIdentity.jks , are not guaranteed to be the same across WebLogic Servers running on different machines. If you were to use the default keystore, the WSDL of the deployed Web Service would specify the public key from one of these keystores, but the invoke of the service might actually be handled by a server running on a different computer, and in this case the server’s private key would not match the published public key and the invoke would fail. This problem only occurs if you use the default keystore and key pairs in a cluster, and is easily resolved by using your own keystore and key pairs. |
Later sections describe some of the preceding scenarios in more detail, as well as additional Web Services security uses cases that build on the simple message-level security use case.
It is assumed in the following procedure that you have already created a JWS file that implements a WebLogic Web Service and you want to update it so that the SOAP messages are digitally signed and encrypted. It is also assumed that you use Ant build scripts to iteratively develop your Web Service and that you have a working build.xml
file that you can update with new information. Finally, it is assumed that you have a client application that invokes the non-secured Web Service. If these assumptions are not true, see:
To configure simple message-level security for a WebLogic Web Service:
@Policy
and @Policies
JWS annotations to specify the pre-packaged policy files that are attached to either the entire Web Service or to particular operations.See Updating the JWS File with @Policy and @Policies Annotations, which describes how to specify any policy file.
See Iterative Development of WebLogic Web Services.
You can use the Cert Gen utility or Sun Microsystem's keytool utility to perform this step. For development purposes, the keytool
utility is the easiest way to get started.
See Obtaining Private Keys and Digital Signatures.
Make sure that the certificate’s key usage allows both encryption and digital signatures. Also see Ensuring That WebLogic Server Can Validate the Client’s Certificate for information about how WebLogic Server ensures that the client’s certificate is valid.
WARNING: | BEA requires a key length of 1024 bits or larger. |
You can use Sun Microsystem's keytool utility to perform this step.
See Obtaining Private Keys and Digital Signatures.
See Users, Groups, and Security Roles.
See Using a Client-Side Security Policy File.
See Invoking Web Services for general information.
See the following sections for information about additional Web Service security uses cases that build on the basic message-level security use case:
See Using System Properties to Debug Message-Level Security for information on debugging problems with your message-secured Web Service.
You must ensure that WebLogic Server is able to validate the X.509 certificate that the client uses to digitally sign its SOAP request, and that WebLogic Server in turn uses to encrypt its SOAP responses to the client. Do one of the following:
For more information, see SSL Certificate Validation.
Use the @Policy
and @Policies
annotations in your JWS file to specify that the Web Service has one or more policy files attached to it. You can use these annotations at either the class or method level.
The @Policies
annotation simply groups two or more @Policy
annotations together. Use the @Policies
annotation if you want to attach two or more policy files to the class or method. If you want to attach just one policy file, you can use @Policy
on its own.
The @Policy
annotation specifies a single policy file, where it is located, whether the policy applies to the request or response SOAP message (or both), and whether to attach the policy file to the public WSDL of the service.
WARNING: | As is true for all JWS annotations, the @Policy annotation cannot be overridden at runtime, which means that the policy file you specify at buildtime using the annotation will always be associated with the Web Service. This means, for example, that although you can view the associated policy file at runtime using the Administration Console, you cannot delete (unassociate) it. You can, however, associate additional policy files, as described in Associating Policy Files at Runtime Using the Administration Console. |
Use the uri
attribute to specify the location of the policy file, as described below:
policy:
prefix and the name of one of the policy files, as shown in the following example:@Policy(uri="policy:Wssp1.2-Https-BasicAuth.xml")
If you use the pre-packaged policy files, you do not have to create one yourself or package it in an accessible location. For this reason, BEA recommends that you use the pre-packaged policy files whenever you can.
See Using Policy Files for Message-Level Security Configuration for information on the various types of message-level security provided by the pre-packaged policy files.
@Policy(uri="../policies/MyPolicy.xml")
In the example, the MyPolicy.xml
file is located in the policies
sibling directory of the one that contains the JWS file.
In this case, it is assumed that the policy file is in the META-INF/policies
or WEB-INF/policies
directory of the shared J2EE library. Be sure, when you package the library, that you put the policy file in this directory.
To specify a policy file in a shared J2EE library, use the policy
prefix and then the name of the policy file, as shown in the following example:
@Policy(uri=”policy:MySharedPolicy.xml”)
See Creating Shared J2EE Libraries and Optional Packages for information on creating shared libraries and setting up your environment so the Web Service can find the shared policy files.
You can also set the following attributes of the @Policy
annotation:
direction
—Specifies whether the policy file should be applied to the request (inbound) SOAP message, the response (outbound) SOAP message, or both. The default value if you do not specify this attribute is both. The direction
attribute accepts the following values:attachToWsdl
—Specifies whether the policy file should be attached to the WSDL file that describes the public contract of the Web Service. The default value of this attribute is false
.
The following example shows how to use the @Policy
and @Policies
JWS annotations, with the relevant sections shown in bold:
package wssp12.wss10;
import weblogic.jws.WLHttpTransport;import weblogic.jws.Policy;
import weblogic.jws.Policies;
import javax.jws.WebService;
import javax.jws.WebMethod;
import javax.jws.Oneway;
/**
* This Web Service demonstrates how to use WS-SecurityPolicy 1.2
* to enable message-level security specified in WS-Security 1.0.
*
* The service authenticates the client with a username token.
* Both the request and response messages are signed and encrypted with X509
certificates.
*
*/@WebService(name="Simple", targetNamespace="http://example.org")
public class UsernameTokenPlainX509SignAndEncrypt {
@WLHttpTransport(contextPath="/wssp12/wss10",
serviceUri="UsernameTokenPlainX509SignAndEncrypt")
@Policy(uri="policy:Wssp1.2-Wss1.0-UsernameToken-Plain-X509-Basic256.xml")
@WebMethod
@Policies({
public String echo(String s) {
@Policy(uri="policy:Wssp1.2-SignBody.xml"),
@Policy(uri="policy:Wssp1.2-EncryptBody.xml")})
return s;
}
@WebMethod@Policies({
public String echoWithWsa(String s) {
@Policy(uri="policy:Wssp1.2-SignBody.xml"),
@Policy(uri="policy:Wssp1.2-Sign-Wsa-Headers.xml")})
return s;
}
@WebMethod
@Policy(uri="policy:Wssp1.2-SignBody.xml",
public void echoOneway(String s) {
direction=Policy.Direction.inbound)
@Oneway
System.out.println("s = " + s);
}
@WebMethod
@Policies({
@Policy(uri="policy:Wssp1.2-Wss1.0-X509-Basic256.xml",
})
direction=Policy.Direction.inbound),
@Policy(uri="policy:Wssp1.2-SignBody.xml",
direction=Policy.Direction.inbound)
@Oneway
public void echoOnewayX509(String s) {
System.out.println("X509SignEncrypt.echoOneway: " + s);
}
}
The following section of the example is the binding policy for the Web Service, specifying the policy:
@WebService(name="Simple", targetNamespace="http://example.org")
@WLHttpTransport(contextPath="/wssp12/wss10",
serviceUri="UsernameTokenPlainX509SignAndEncrypt")
@Policy(uri="policy:Wssp1.2-Wss1.0-UsernameToken-Plain-X509-Basic256.xml")
In the example, security policy files are attached to the Web Service at the method level. The specified policy files are those pre-packaged with WebLogic Server, which means that the developers do not need to create their own files or package them in the corresponding archive.
The Wssp1.2-SignBody.xml
policy file specifies that the body and WebLogic system headers of both the request and response SOAP message be digitally signed. The Wssp1.2-EncryptBody.xml
policy file specifies that the body of both the request and response SOAP messages be encrypted.
In the simple message-level configuration procedure, documented in Configuring Simple Message-Level Security: Main Steps, it is assumed that the Web Services runtime uses the private key and X.509 certificate pair that is provided out-of-the-box with WebLogic Server; this same key pair is also used by the core security subsystem for SSL and is provided mostly for demonstration and testing purposes. In production environments, the Web Services runtime typically uses its own two private key and digital certificate pairs, one for signing and one for encrypting SOAP messages.
The following procedure describes the additional steps you must take to enable this use case.
Although not required, BEA recommends that you obtain two pairs that will be used only by WebLogic Web Services. You must also ensure that both of the certificate’s key usage matches what you are configuring them to do. For example, if you are specifying that a certificate be used for encryption, be sure that the certificate’s key usage is specified as for encryption or is undefined. Otherwise, the Web Services security runtime will reject the certificate.
WARNING: | BEA requires that the key length be 1024 bits or larger. |
You can use the Cert Gen utility or Sun Microsystem's keytool utility to perform this step. For development purposes, the keytool
utility is the easiest way to get started.
See Obtaining Private Keys and Digital Signatures.
If you have already configured WebLogic Server for SSL, then you have already created a identity keystore which you can also use in this step.
You can use WebLogic’s ImportPrivateKey
utility and Sun Microsystem’s keytool utility to perform this step. For development purposes, the keytool
utility is the easiest way to get started.
See Creating a Keystore and Loading Private Keys and Trusted Certificate Authorities Into the Keystore.
See Configuring Keystores for Production.
default_wss
. The default Web Service security configuration is used by all Web Services in the domain unless they have been explicitly programmed to use a different configuration.See Create a Web Service security configuration.
See
Specify the Key Pair Used to Sign SOAP Messages. In the procedure, when you create the properties used to identify the keystore and key pair, enter the exact value for the Name of each property (such as IntegrityKeyStore
, IntegrityKeyStorePassword
, and so on), but enter the value that identifies your own previously-created keystore and key pair in the Value fields.
See
Create keystore used by SOAP message encryption. In the procedure, when you create the properties used to identify the keystore and key pair, enter the exact value for the Name of each property (such as ConfidentialityKeyStore
. ConfidentialityKeyStorePassword
, and so on), but enter the value that identifies your own previously-created keystore and key pair in the Value fields.
When you update your Java code to invoke a message-secured Web Service, you must load a private key and digital certificate pair from the client’s keystore and pass this information, along with a username and password for user authentication if so required by the security policy, to the secure WebLogic Web Service being invoked.
If the security policy file of the Web Service specifies that the SOAP request must be encrypted, then the Web Services client runtime automatically gets the server’s certificate from the policy file that is attached to the WSDL of the service, and uses it for the encryption. If, however, the policy file is not attached to the WSDL, or the entire WSDL itself is not available, then the client application must use a client-side copy of the policy file; for details, seeUsing a Client-Side Security Policy File.
Listing 3-2 shows a Java client application that invokes the message-secured WebLogic Web Service described by the JWS file in Updating the JWS File With the Security-Related Annotations. The client application takes five arguments:
The security-specific code in the sample client application is shown in bold (and described after the example):
package examples.webservices.security_jws.client;
import weblogic.security.SSL.TrustManager;
import weblogic.xml.crypto.wss.provider.CredentialProvider;
import weblogic.xml.crypto.wss.WSSecurityContext;
import weblogic.wsee.security.bst.ClientBSTCredentialProvider;
import weblogic.wsee.security.unt.ClientUNTCredentialProvider;
import javax.xml.rpc.Stub;
import java.util.List;
import java.util.ArrayList;
import java.security.cert.X509Certificate;
/**
* Copyright (c) 2005 by BEA Systems. All Rights Reserved.
*/
public class SecureHelloWorldClient {
public static void main(String[] args) throws Throwable {
//username or password for the UsernameToken
String username = args[0];
String password = args[1];
//client private key file
String keyFile = args[2];
//client certificate
String clientCertFile = args[3];
String wsdl = args[4];
SecureHelloWorldService service = new SecureHelloWorldService_Impl(wsdl + "?WSDL" );
SecureHelloWorldPortType port = service.getSecureHelloWorldServicePort();
//create credential provider and set it to the Stub
List credProviders = new ArrayList();
//client side BinarySecurityToken credential provider -- x509
CredentialProvider cp = new ClientBSTCredentialProvider(clientCertFile, keyFile);
credProviders.add(cp);
//client side UsernameToken credential provider
cp = new ClientUNTCredentialProvider(username, password);
credProviders.add(cp);
Stub stub = (Stub)port;
stub._setProperty(WSSecurityContext.CREDENTIAL_PROVIDER_LIST, credProviders);
stub._setProperty(WSSecurityContext.TRUST_MANAGER,
new TrustManager(){
public boolean certificateCallback(X509Certificate[] chain, int validateErr){
return true;
}
} );
String response = port.sayHello("World");
System.out.println("response = " + response);
}
}
The main points to note about the preceding code are:
TrustManager
API:import weblogic.security.SSL.TrustManager;
import weblogic.xml.crypto.wss.provider.CredentialProvider;
import weblogic.xml.crypto.wss.WSSecurityContext;
import weblogic.wsee.security.bst.ClientBSTCredentialProvider;
import weblogic.wsee.security.unt.ClientUNTCredentialProvider;
ClientBSTCredentialProvider
WebLogic API to create a binary security token credential provider from the client’s certificate and private key:CredentialProvider cp =
new ClientBSTCredentialProvider(clientCertFile, keyFile);
ClientUNTCredentialProvider
WebLogic API to create a username token from the client’s username and password, which are also known by WebLogic Server:cp = new ClientUNTCredentialProvider(username, password);
WSSecurityContext.CREDENTIAL_PROVIDER_LIST
property to pass a List
object that contains the binary security and username tokens to the JAX-RPC Stub:stub._setProperty(WSSecurityContext.CREDENTIAL_PROVIDER_LIST, credProviders)
weblogic.security.SSL.TrustManager
WebLogic security API to verify that the certificate used to encrypt the SOAP request is valid. The Web Services client runtime gets this certificate from the deployed WSDL of the Web Service, which in production situations is not automatically trusted, so the client application must ensure that it is okay before it uses it to encrypt the SOAP request:stub._setProperty(WSSecurityContext.TRUST_MANAGER,
new TrustManager(){
public boolean certificateCallback(X509Certificate[] chain, int validateErr){
return true;
}
} );
This example shows the TrustManager API on the client side. The Web Service application must implement proper verification code to ensure security.
In the simple Web Services configuration procedure, described in Configuring Simple Message-Level Security: Main Steps, it is assumed that a stand-alone client application invokes the message-secured Web Service. Sometimes, however, the client is itself running in a WebLogic Server instance, as part of an EJB, a servlet, or another Web Service. In this case, you can use the core WebLogic Server security framework to configure the credential providers and trust manager so that your EJB, servlet, or JWS code contains only the simple invoke of the secured operation and no other security-related API usage. The following procedure describes the high level steps you must perform to make use of the core WebLogic Server security framework in this use case.
CredentialProvider
object that contains username or X.509 tokens, and do not use the TrustManager
core security API to validate the certificate from the WebLogic Server hosting the secure Web Service. The reason you should not use these APIs in your client code is that the Web Services runtime will perform this work for you.Note: | WebLogic Server includes a credential mapping provider for username/passwords and X.509. However, only username/password is configured by default. |
You are not required to configure the core WebLogic Server security framework, as described in this procedure, if your client application does not want to use the out-of-the-box credential provider and trust manager. Rather, you can override all of this configuration by using the same APIs in your EJB, servlet, and JWS code as in the stand-alone Java code described in Using a Client-Side Security Policy File. However, using the core security framework standardizes the WebLogic Server configuration and simplifies the Java code of the client application that invokes the Web Service.
Although WebLogic Server includes a number of pre-packaged Web Services security policy files that typically satisfy the security needs of most programmers, you can also create and use your own WS-SecurityPolicy file if you need additional configuration. See Using Policy Files for Message-Level Security Configuration for general information about security policy files and how they are used for message-level security configuration.
When you create a custom policy file, you can separate out the three main security categories (authentication, encryption, and signing) into three separate policy files, as do the pre-packaged files, or create a single policy file that contains all three categories. You can also create a custom policy file that changes just one category (such as authentication) and use the pre-packaged files for the other categories (Wssp1.2-SignBody.xml
and Wssp1.2-EncryptBody
). In other words, you can mix and match the number and content of the policy files that you associate with a Web Service. In this case, however, you must always ensure yourself that the multiple files do not contradict each other.
Your custom policy file needs to comply with the standard format and assertions defined in WS-SecurityPolicy 1.2. Note, however, that this release of WebLogic Server does not completely implement WS-SecurityPolicy 1.2. For more information, see Unsupported WS-SecurityPolicy 1.2 Assertions. The root element of your WS-SecurityPolicy file must be <Policy>
and include the following namespace declarations:
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512"
>
You can also use the pre-packaged WS-SecurityPolicy files as templates to create your own custom files. See Using WS-SecurityPolicy 1.2 Policy Files.
If there are multiple available transport-level assertions in your security policies, WebLogic Server uses the policy that requires https. If more than one policy alternative requires https, WebLogic Server randomly picks one of them. You should therefore avoid using multiple policy alternatives that contain mixed transport-level policy assertions.
BEA provides three pre-packaged WS-SecurityPolicy files (Wssp1.2-Wssc200502-Bootstrap-Https.xml
, Wssp1.2-Wssc200502-Bootstrap-Wss1.0.xml
, and Wssp1.2-Wssc200502-Bootstrap-Wss1.1.xml
) to configure security contexts and derived keys, as described by the WS-SecureConversation 1.2 (2005/2) specification. It is recommended that you use the pre-packaged files if you want to configure security contexts, because these security policy files provide most of the required functionality and typical default values. See WS-SecureConversation 2005/2 Policies for more information about these files.
WARNING: | If you are deploying a Web Service that uses shared security contexts to a cluster, then you are required to also configure cross-cluster session state replication. For details, see Failover and Replication in a Cluster. |
WS-SecureConversation is pinned to a particular WebLogic Server instance in the cluster. If a SecureConversation request lands in the wrong server, it is automatically rerouted to the correct server. If the server instance hosting the WS-SecureConversation fails, the SecureConversation will not be available until the server instance is brought up again.
A client application that negotiates security contexts when invoking a Web Service is similar to a standard client application that invokes a message-secured Web Service, as described in Using a Client-Side Security Policy File. The only real difference is that you can use the weblogic.wsee.security.wssc.utils.WSSCClientUtil API to explicitly cancel the secure context token.
Note: | WebLogic Server provides the WSSCCLientUtil API for your convenience only; the Web Services runtime automatically cancels the secure context token when the configured timeout is reached. Use the API only if you want to have more control over when the token is cancelled. |
Listing 3-3 shows a simple example of a client application invoking a Web Service that is associated with a pre-packaged security policy file that enables secure conversations; the sections in bold which are relevant to security contexts are discussed after the example:
package examples.webservices.wssc.client;
import weblogic.security.SSL.TrustManager;
import weblogic.xml.crypto.wss.provider.CredentialProvider;
import weblogic.xml.crypto.wss.WSSecurityContext;
import weblogic.wsee.security.bst.ClientBSTCredentialProvider;
import weblogic.wsee.security.bst.StubPropertyBSTCredProv;import weblogic.wsee.security.wssc.utils.WSSCClientUtil;
import weblogic.wsee.security.util.CertUtils;
import javax.xml.rpc.Stub;
import java.util.List;
import java.util.ArrayList;
import java.security.cert.X509Certificate;
/**
* Copyright (c) 2004 by BEA Systems. All Rights Reserved.
*/
public class WSSecureConvClient {
public static void main(String[] args) throws Throwable {
String clientKeyStore = args[0];
String clientKeyStorePass = args[1];
String clientKeyAlias = args[2];
String clientKeyPass = args[3];
String serverCert = args[4];
String wsdl = args[5];
WSSecureConvService service = new WSSecureConvService_Impl(wsdl);
WSSecureConvPortType port = service.getWSSecureConvServicePort();
//create credential provider and set it to the Stub
List credProviders = new ArrayList();
//use x509 to secure wssc handshake
credProviders.add(new ClientBSTCredentialProvider(clientKeyStore, clientKeyStorePass, clientKeyAlias, clientKeyPass));
Stub stub = (Stub)port;
stub._setProperty(WSSecurityContext.CREDENTIAL_PROVIDER_LIST, credProviders);stub._setProperty(StubPropertyBSTCredProv.SERVER_ENCRYPT_CERT, CertUtils.getCertificate(serverCert));
stub._setProperty(WSSecurityContext.TRUST_MANAGER,
new TrustManager(){
public boolean certificateCallback(X509Certificate[] chain, int validateErr){
//need to validate if the server cert can be trusted
return true;
}
}
);
System.out.println (port.sayHelloWithWSSC("Hello World, once"));
System.out.println (port.sayHelloWithWSSC("Hello World, twice"));
System.out.println (port.sayHelloWithWSSC("Hello World, thrice"));
//cancel SecureContextToken after done with invocationWSSCClientUtil.terminateWssc(stub);
}
System.out.println("WSSC terminated!");
}
The points to notice in the preceding example are:
import weblogic.wsee.security.wssc.utils.WSSCClientUtil;
stub._setProperty(StubPropertyBSTCredProv.SERVER_ENCRYPT_CERT, CertUtils.getCertificate(serverCert));
terminateWssc()
method of the WSSClientUtil
class to terminate the secure context token:WSSCClientUtil.terminateWssc(stub);
The simple message-level configuration procedure, documented in Configuring Simple Message-Level Security: Main Steps, describes how to use the @Policy
and @Policies
JWS annotations in the JWS file that implements your Web Service to specify one or more policy files that are associated with your service. This of course implies that you must already know, at the time you program your Web Service, which policy files you want to associate with your Web Service and its operations. This might not always be possible, which is why you can also associate policy files at runtime, after the Web Service has been deployed, using the Administration Console.
You can use no @Policy
or @Policies
JWS annotations at all in your JWS file and associate policy files only at runtime using the Administration Console, or you can specify some policy files using the annotations and then associate additional ones at runtime. However, once you associate a policy file using the JWS annotations, you cannot change this association at runtime using the Administration Console.
At runtime, the Administration Console allows you to associate as many policy files as you want with a Web Service and its operations, even if the policy assertions in the files contradict each other or contradict the assertions in policy files associated with the JWS annotations. It is up to you to ensure that multiple associated policy files work together. If any contradictions do exist, WebLogic Server returns a runtime error when a client application invokes the Web Service operation.
See Associate a policy file with a Web Service for detailed instructions on using the Administration Console to associate a policy file at runtime.
In the simple Web Services configuration procedure, described in Configuring Simple Message-Level Security: Main Steps, it is assumed that users use username tokens to authenticate themselves. Because WebLogic Server implements the Web Services Security: SAML Token Profile of the Web Services Security specification, users can also use SAML tokens in the SOAP messages to authenticate themselves when invoking a Web Service operation, as described in this section.
Use of SAML tokens works server-to-server. This means that the client application is running inside of a WebLogic Server instance and then invokes a Web Service running in another WebLogic Server instance using SAML for identity. Because the client application is itself a Web Service, the Web Services security runtime takes care of all the SAML processing.
When you configure a Web Service to require SAML tokens for identity, you can specify one of the following confirmation methods:
See SAML Token Profile Support in WebLogic Web Services, as well as the Web Services Security: SAML Token Profile specification itself, for details about these confirmation methods.
Note: | It is assumed in this section that you understand the basics of SAML and how it relates to core security in WebLogic Server. For general information, see Security Assertion Markup Language (SAML). |
Note: | It is also assumed in the following procedure that you have followed the steps in Configuring Simple Message-Level Security: Main Steps and now want to enable the additional use case of using SAML tokens, rather than usename tokens, for identity. |
To use SAML tokens for identity, follow these steps:
sender-vouches
or holder-of-key
). Note that this release of WebLogic Server does not support the use of SAML with WS-SecurityPolicy 1.2 policy files. Instead, you must use security policy files written under BEA’s security policy schema. The exact syntax depends on the type of confirmation method you want to configure (sender-vouches
or holder-of-key
).To specify the sender-vouches confirmation method:
<SecurityToken>
child element of the <Identity><SupportedTokens>
elements and set the TokenType
attribute to a value that indicates SAML token usage.<Claims><Confirmationmethod>
child element of <SecurityToken>
and specify sender-vouches
.<?xml version="1.0"?>
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wssp="http://www.bea.com/wls90/security/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part"
>
<wssp:Identity>
<wssp:SupportedTokens>
<wssp:SecurityToken
TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-saml-token-profile-1.0#SAMLAssertionID
">
<wssp:Claims>
<wssp:ConfirmationMethod>sender-vouches</wssp:ConfirmationMethod>
</wssp:Claims>
</wssp:SecurityToken>
</wssp:SupportedTokens>
</wssp:Identity>
</wsp:Policy>
To specify the holder-of-key confirmation method:
<SecurityToken>
child element of the <Integrity><SupportedTokens>
elements and set the TokenType
attribute to a value that indicates SAML token usage.
The reason you put the SAML token in the <Integrity>
assertion for the holder-of-key
confirmation method is that the Web Service runtime must prove the integrity of the message, which is not required by sender-vouches
.
<Claims><Confirmationmethod>
child element of <SecurityToken>
and specify holder-of-key
.<?xml version="1.0"?>
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wssp="http://www.bea.com/wls90/security/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part">
<wssp:Integrity>
<wssp:SignatureAlgorithm
URI="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<wssp:CanonicalizationAlgorithm
URI="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<wssp:Target>
<wssp:DigestAlgorithm
URI="http://www.w3.org/2000/09/xmldsig#sha1" />
<wssp:MessageParts
Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
wsp:Body()
</wssp:MessageParts>
</wssp:Target>
<wssp:SupportedTokens>
<wssp:SecurityToken
IncludeInMessage="true"
TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-saml-token-profile-1.0#SAMLAssertionID
">
<wssp:Claims>
<wssp:ConfirmationMethod>holder-of-key</wssp:ConfirmationMethod>
</wssp:Claims>
</wssp:SecurityToken>
</wssp:SupportedTokens>
</wssp:Integrity>
</wsp:Policy>
<KeyInfo>
assertion of any associated WS-Policy file. To disable this validation when using SAML holder-of-key assertions, you must configure the Web Service security configuration associated with the Web service by setting a property on the SAML token handler. See
Disable X.509 certificate validation when using SAML holder_of_key assertions for information on how to do this using the Administration Console.See Creating and Using a Custom Policy File for additional information about creating your own security policy file. See Security Policy Assertion Reference for reference information about the assertions.
@Policy
annotations in the JWS file that implements the Web Service to point to the security policy file from the preceding step. For example, if you want invokes of all the operations of a Web Service to SAML for identity, specify the @Policy
annotation at the class-level.
You can mix and match the policy files that you associate with a Web Service, as long as they do not contradict each other and as long as you do not combine OASIS WS-SecurityPolicy 1.2 files with security policy files written under BEA’s security policy schema. For example, you can create a simple MyAuth.xml
file that contains only the <Identity>
security assertion to specify use of SAML for identity and then associate it with the Web Service together with the pre-packaged Wssp1.2-EncryptBody.xml
and Wssp1.2-SignBody.xml
files. It is, however, up to you to ensure that multiple associated policy files do not contradict each other; if they do, you will either receive a runtime error or the Web Service might not behave as you expect.
See Iterative Development of WebLogic Web Services.
Many use cases previously discussed require you to use the Administration Console to create the default Web Service security configuration called default_wss
. After you create this configuration, it is applied to all Web Services that either do not use the @weblogic.jws.security.WssConfiguration
JWS annotation or specify the annotation with no attribute.
There are some cases, however, in which you might want to associate a Web Service with a security configuration other than the default; such use cases include specifying different timestamp values for different services.
To associate a Web Service with a security configuration other than the default:
default_wss
.@WssConfiguration
annotation to specify the name of this security configuration. See
weblogic.jws.security.WssConfiguration for additional information and an example.WARNING: | If you are going to package additional Web Services in the same Web application, and these Web Services also use the @WssConfiguration annotation, then you must specify the same security configuration for each Web Service. See
weblogic.jws.security.WssConfiguration for more details. |
WARNING: | All Web Services security configurations are required to specify the same password digest use. Inconsistent password digest use in different Web Service security configurations will result in a runtime error. |
The following table lists the system properties you can set to debug problems with your message-secured Web Service.
The section Using Policy Files for Message-Level Security Configuration describes how a WebLogic Web Service can be associated with one or more security policy files that describe the message-level security of the Web Service. These policy files are XML files that describe how a SOAP message should be digitally signed or encrypted and what sort of user authentication is required from a client that invokes the Web Service. Typically, the policy file associated with a Web Service is attached to its WSDL, which the Web Services client runtime reads to determine whether and how to digitally sign and encrypt the SOAP message request from an operation invoke from the client application.
Sometimes, however, a Web Service might not attach the policy file to its deployed WSDL or the Web Service might be configured to not expose its WSDL at all. In these cases, the Web Services client runtime cannot determine from the service itself the security that must be enabled for the SOAP message request. Rather, it must load a client-side copy of the policy file. This section describes how to update a client application to load a local copy of a policy file.
The client-side policy file is typically exactly the same as the one associated with a deployed Web Service. If the two files are different, and there is a conflict in the security assertions contained in the files, then the invoke of the Web Service operation returns an error.
You can specify that the client-side policy file be associated with the SOAP message request, response, or both. Additionally, you can specify that the policy file be associated with the entire Web Service, or just one of its operations.
The following procedure describes the high-level steps to associate a security policy file with the client application that invokes a Web Service operation.
It is assumed that you have created the client application that invokes a deployed Web Service, and that you want to update it by associating a client-side policy file. It is also assumed that you have set up an Ant-based development environment and that you have a working build.xml
file that includes a target for running the clientgen
Ant task. See
“Invoking a Web Service from a Stand-alone Client: Main Steps.
See Creating and Using a Custom Policy File for information about creating security policy files.
build.xml
file that builds your client application by specifying to the clientgen
Ant task that it should generate additional get
XXX
Port()
methods in the JAX-RPC stub, where XXX
refers to the name of the Web Service. These methods are later used by the client application to load the client-side policy files. See Updating clientgen to Generate Methods That Load Policy Files.
get
XXX
Port()
methods that the clientgen
Ant task generates.See Updating a Client Application To Load Policy Files.
prompt> ant build-client
When you next run the client application, it will load local copies of the policy files that the Web Service client runtime uses to enable security for the SOAP request message.
Note: | If you have a Web Services operation that already have a security policy (for example, one that was set in the WSDL file that was stored when generating the client from the server policy), then when you use this procedure to programmatically set the client-side security policy, all previously-existing policies will be removed. |
Set the generatePolicyMethods
attribute of the clientgen
Ant task to true
to specify that the Ant task should generate additional getXXX()
methods in the implementation of the JAX-RPC Service
interface for loading client-side copies of policy files when you get a port, as shown in the following example:
<clientgen
wsdl="http://ariel:7001/policy/ClientPolicyService?WSDL"
destDir="${clientclass-dir}"
generatePolicyMethods="true"
packageName="examples.webservices.client_policy.client"/>
See Updating a Client Application To Load Policy Files for a description of the additional methods that are generated and how to use them in a client application.
When you set generatePolicyMethods="true"
for clientgen
, the Ant task generates additional methods in the implementation of the JAX-RPC Service
interface that you can use to load policy files, where XXX
refers to the name of the Web Service. You can use either an Array or Set of policy files to associate multiple files to a Web Service. If you want to associate just a single policy file, create a single-member Array or Set.
get
XXX
Port(String operationName, java.util.Set<java.io.InputStream> inbound, java.util.Set<java.io.InputStream> outbound)
Loads two different sets of client-side policy files from InputStreams and associates the first set to the SOAP request and the second set to the SOAP response. Applies to a specific operation, as specified by the first parameter.
get
XXX
Port(String operationName, java.io.InputStream[] inbound, java.io.InputStream[] outbound)
Loads two different arrays of client-side policy files from InputStreams and associates the first array to the SOAP request and the second array to the SOAP response. Applies to a specific operation, as specified by the first parameter.
get
XXX
Port(java.util.Set<java.io.InputStream> inbound, java.util.Set<java.io.InputStream> outbound)
Loads two different sets of client-side policy files from InputStreams and associates the first set to the SOAP request and the second set to the SOAP response. Applies to all operations of the Web Service.
get
XXX
Port(java.io.InputStream[] inbound, java.io.InputStream[] outbound)
Loads two different arrays of client-side policy files from InputStreams and associates the first array to the SOAP request and the second array to the SOAP response. Applies to all operations of the Web Service.
Use these methods, rather than the normal getXXXPort()
method with no parameters, for getting a Web Service port and specifying at the same time that invokes of all, or the specified, operation using that port have an associated policy file or files.
Note: | The following methods from a previous release of WebLogic Server have been deprecated; if you want to associate a single client-side policy file, specify a single-member Array or Set and use the corresponding method described above. |
get
XXX
Port(java.io.InputStream policyInputStream);
Loads a single client-side policy file from an InputStream and applies it to both the SOAP request (inbound) and response (outbound) messages.
get
XXX
Port(java.io.InputStream policyInputStream, boolean inbound, boolean outbound);
Loads a single client-side policy file from an InputStream
and applies it to either the SOAP request or response messages, depending on the Boolean value of the second and third parameters.
Listing 3-4 shows an example of using these policy methods in a simple client application; the code in bold is described after the example.
package examples.webservices.client_policy.client;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import javax.xml.rpc.Stub;
import java.io.FileInputStream;
import java.io.IOException;
/**
* This is a simple standalone client application that invokes the
* the <code>sayHello</code> operation of the ClientPolicyService Web service.
*
* @author Copyright (c) 2004 by BEA Systems. All Rights Reserved.
*/
public class Main {
public static void main(String[] args)
throws ServiceException, RemoteException, IOException {
FileInputStream [] inbound_policy_array = new FileInputStream[2];
inbound_policy_array[0] = new FileInputStream(args[1]);
inbound_policy_array[1] = new FileInputStream(args[2]);
FileInputStream [] outbound_policy_array = new FileInputStream[2];
outbound_policy_array[0] = new FileInputStream(args[1]);
outbound_policy_array[1] = new FileInputStream(args[2]);
ClientPolicyService service = new ClientPolicyService_Impl(args[0] + "?WSDL");
// standard way to get the Web Service portClientPolicyPortType normal_port = service.getClientPolicyPort();
// specify an array of policy files for the request and response
// of a particular operationClientPolicyPortType array_of_policy_port = service.getClientPolicyPort("sayHello", inbound_policy_array, outbound_policy_array);
try {
String result = null;result = normal_port.sayHello("Hi there!");
System.out.println( "Got result: " + result );
result = array_of_policy_port.sayHello("Hi there!");
} catch (RemoteException e) {
throw e;
}
}
}
The second and third argument to the client application are the two policy files from which the application makes an array of FileInputStreams
(inbound_policy_array
and outbound_policy_array
). The normal_port
uses the standard parameterless method for getting a port; the array_of_policy_port
, however, uses one of the policy methods to specify that an invoke of the sayHello
operation using the port has multiple policy files (specified with an Array of FileInputStream
) associated with both the inbound and outbound SOAP request and response:
ClientPolicyPortType array_of_policy_port = service.getClientPolicyPort("sayHello", inbound_policy_array, outbound_policy_array);
WebLogic Server includes a number of WS-SecurityPolicy files you can use in most Web Services applications. The policy files are located in BEA_HOME/WL_HOME/server/lib/weblogic.jar
. Within weblogic.jar
, the policy files are located in /weblogic/wsee/policy/runtime
.
These security policy files conform to the OASIS WS-SecurityPolicy 1.2 specification and have the following namespace:
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512"
>
Note: | This release of WebLogic Server also includes five security policy files (first included in WebLogic Server 9) written under a proprietary BEA Web Services security policy schema. These security policy files, described in BEA Web Services Security Policy Files have the following namespace: |
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wssp="http://www.bea.com/wls90/security/policy"
>
The following sections describe the available WS-SecurityPolicy 1.2 policy files:
In addition, see Choosing a Policy and Smart Policy Selection for information about how to choose the best security policy approach for your Web Services implementation and for information about WS-SecurityPolicy 1.2 elements that are not supported in this release of WebLogic Server.
These policies require use of the https
protocol to access WSDL and invoke Web Services operations:
Protection assertions are used to identify what is being protected and the level of protection provided. Protection assertion policies can not be used alone; they should be used only in combination with X.509 Token Policies. For example, you might use Wssp1.2-Wss1.1-X509-Basic256.xml
together with Wssp1.2-SignBody.xml
. The following policy files provide for the protection of message parts by signing or encryption:
The following policies support the Username Token or X.509 Token specifications of WS-Security 1.0:
The following policies support the Username Token or X.509 Token specifications of WS-Security 1.1:
The following policies implement WS-SecureConversation 2005/2:
WebLogic Server's implementation of WS-SecurityPolicy 1.2 makes a wide variety of security policy alternatives available to you. When choosing a security policy for your Web Service, you should consider your requirements in these areas:
Whenever possible, BEA recommends that you:
Wssp1.2-Https-*.xml
) only where message-level security is not required.You can configure multiple policy alternatives for a single Web Service by creating a custom policy. At runtime, WebLogic Server selects which of the configured policies to apply. It excludes policies that are not supported or have conflicting assertions and selects the appropriate policy to verify incoming messages and build the response messages. For example, a single Web Service can be configured with security policies that can handle either WS-Security 1.0 or WS-Security 1.1 requests.
Listing 3-5 gives an example of a security policy that supports both WS-Security 1.0 and WS-Security 1.1. Each policy alternative is enclosed in a <wsp:All> element.
<?xml version="1.0"?>
<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512">
<wsp:ExactlyOne>
<wsp:All>
<sp:AsymmetricBinding>
<wsp:Policy>
<sp:InitiatorToken>
<wsp:Policy>
<sp:X509Token
sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512/IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:WssX509V3Token10/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:InitiatorToken>
<sp:RecipientToken>
<wsp:Policy>
<sp:X509Token
sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512/IncludeToken/Never">
<wsp:Policy>
<sp:WssX509V3Token10/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:RecipientToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic256/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Lax/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
<sp:ProtectTokens/>
<sp:OnlySignEntireHeadersAndBody/>
</wsp:Policy>
</sp:AsymmetricBinding>
<sp:SignedParts>
<sp:Body/>
</sp:SignedParts>
<sp:Wss10>
<wsp:Policy>
<sp:MustSupportRefKeyIdentifier/>
<sp:MustSupportRefIssuerSerial/>
</wsp:Policy>
</sp:Wss10>
</wsp:All>
<wsp:All>
<sp:AsymmetricBinding>
<wsp:Policy>
<sp:InitiatorToken>
<wsp:Policy>
<sp:X509Token
sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512/IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:RequireThumbprintReference/>
<sp:WssX509V3Token11/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:InitiatorToken>
<sp:RecipientToken>
<wsp:Policy>
<sp:X509Token
sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512/IncludeToken/Never">
<wsp:Policy>
<sp:RequireThumbprintReference/>
<sp:WssX509V3Token11/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:RecipientToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic256/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Lax/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
<sp:ProtectTokens/>
<sp:OnlySignEntireHeadersAndBody/>
</wsp:Policy>
</sp:AsymmetricBinding>
<sp:SignedParts>
<sp:Body/>
</sp:SignedParts>
<sp:Wss11>
<wsp:Policy>
<sp:MustSupportRefKeyIdentifier/>
<sp:MustSupportRefIssuerSerial/>
<sp:MustSupportRefThumbprint/>
<sp:MustSupportRefEncryptedKey/>
<sp:RequireSignatureConfirmation/>
</wsp:Policy>
</sp:Wss11>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>
The Web Services SecurityPolicy specification is not final as of this release of WebLogic Server. The implementation of WS-SecurityPolicy in this release of WebLogic Server is based on OASIS WS-SecurityPolicy 1.2 Editors Draft dated 19 June 2006 (WS-SX WSSP 1.2 (06/2006). Table 3-7 details the elements of the Web Services SecurityPolicy 1.2 draft dated 21 February 2007, that are not supported in this release of WebLogic Server:
Previous releases of WebLogic Server, released before the formulation of the WS-SecurityPolicy specification, used security policy files written under the WS-Policy specification, using a proprietary BEA schema for security policy. This release of WebLogic Server supports both security policy files that conform to the WS-SecurityPolicy 1.2 specification and the files written under the BEA Web Services security policy schema first included in WebLogic Server 9.
WARNING: | WS-SecurityPolicy 1.2 policy files and BEA proprietary Web Services security policy schema files are not mutually compatible; you cannot define both types of policy file in the same Web Service. If you want to use WS-Security 1.1 features, you must use the WS-SecurityPolicy 1.2 policy file format. |
This section describes the set of pre-packaged BEA Web Services security policy schema files included in WebLogic Server. These policy files are all abstract; see Abstract and Concrete Policy Files for details.
Note: | The policy assertions used in these security policy files to configure message-level security for a WebLogic Web Service are based on the assertions described in the December 18, 2002 version of the Web Services Security Policy Language (WS-SecurityPolicy) specification. This means that although the exact syntax and usage of the assertions in WebLogic Server are different, they are similar in meaning to those described in the specification. The assertions are not based on later updates of the specification. |
The pre-packaged BEA Web Services security policy files are:
Sign.xml
and Encrypt.xml
.Auth.xml
and Encrypt.xml
.Auth.xml
and Sign.xml
.Note: | This pre-packaged policy file is meant to be used on its own and not together with Auth.xml , Sign.xml , Encrypt.xml , or Wssc-sct.xml . Also, BEA recommends that you use this policy file, rather than Wssc-sct.xml, if you want the client and service to share a security context, due to its higher level of security. |
Note: | This pre-packaged policy file is meant to be used on its own and not together with Auth.xml , Sign.xml , Encrypt.xml , or Wssc-dk.xml . Also, BEA provides this policy file to support the various use cases of the WS-SecureConversation specification; however, BEA recommends that you use the Wssc-dk.xml policy file, rather than Wssc-sct.xml, if you want the client and service to share a security context, due to its higher level of security. |
The WebLogic Web Services runtime environment recognizes two slightly different types of security policy files: abstract and concrete.
Abstract policy files do not explicitly specify the security tokens that are used for authentication, encryption, and digital signatures, but rather, the Web Services runtime environment determines the security tokens when the Web Service is deployed. Specifically, this means the <Identity>
and <Integrity>
elements (or assertions) of the policy files do not contain a <SupportedTokens><SecurityToken>
child element, and the <Confidentiality>
element policy file does not contain a <KeyInfo><SecurityToken>
child element.
If your Web Service is associated with only the pre-packaged policy files, then client authentication requires username tokens. Web Services support only one type of token for encryption and digital signatures (X.509
), which means that in the case of the <Integrity>
and <Confidentiality>
elements, concrete and abstract policy files end up being essentially the same.
If your Web Service is associated with an abstract policy file and it is published as an attachment to the WSDL (which is the default behavior), the static WSDL file packaged in the Web Service archive file (JAR or WAR) will be slightly different than the dynamic WSDL of the deployed Web Service. This is because the static WSDL, being abstract, does not include specific <SecurityToken>
elements, but the dynamic WSDL does include these elements because the Web Services runtime has automatically filled them in when it deployed the service. For this reason, in the code that creates the JAX-RPC stub in your client application, ensure that you specify the dynamic WSDL or you will get a runtime error when you try to invoke an operation:
HelloService service = new HelloService(Dynamic_WSDL);
You can specify either the static or dynamic WSDL to the clientgen
Ant task in this case. See
Browsing to the WSDL of the Web Service for information on viewing the dynamic WSDL of a deployed Web Service.
Concrete policy files explicitly specify the details of the security tokens at the time the Web Service is programmed. Programmers create concrete security policy files when they know, at the time they are programming the service, the details of the type of authentication (such as using x509
or SAML
tokens); whether multiple private key and certificate pairs from the keystore are going to be used for encryption and digital signatures; and so on.
The WebLogic Server Auth.xml
file, shown below, specifies that the client application invoking the Web Service must authenticate itself with one of the tokens (username or X.509) that support authentication.
Because the pre-packaged BEA Web Services security policy schema files are abstract, there is no specific username or X.509 token assertions in the Auth.xml
file at development-time. Depending on how you have configured security for WebLogic Server, either a username token, an X.509 token, or both will appear in the actual runtime-version of the Auth.xml
policy file associated with your Web Service. Additionally, if the runtime-version of the policy file includes an X.509 token and it is applied to a client invoke, then the entire body of the SOAP message is signed.
If you want to specify that only X.509, and never username tokens, be used for identity, or want to specify that, when using X.509 for identity, only certain parts of the SOAP message be signed, then you must create a custom security policy file.
<?xml version="1.0"?>
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wssp="http://www.bea.com/wls90/security/policy"
>
<wssp:Identity/>
</wsp:Policy>
The WebLogic Server Sign.xml
file specifies that the body and WebLogic-specific system headers of the SOAP message be digitally signed. It also specifies that the SOAP message include a Timestamp, which is digitally signed, and that the token used for signing is also digitally signed. The token used for signing is included in the SOAP message.
The following headers are signed when using the Sign.xml
security policy file:
The WebLogic Server Sign.xml
file is shown below:
<?xml version="1.0"?>
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wssp="http://www.bea.com/wls90/security/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part"
>
<wssp:Integrity>
<wssp:SignatureAlgorithm URI="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<wssp:CanonicalizationAlgorithm
URI="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<wssp:Target>
<wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1" />
<wssp:MessageParts
Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
wls:SystemHeaders()
</wssp:MessageParts>
</wssp:Target>
<wssp:Target>
<wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1" />
<wssp:MessageParts
Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
wls:SecurityHeader(wsu:Timestamp)
</wssp:MessageParts>
</wssp:Target>
<wssp:Target>
<wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1" />
<wssp:MessageParts
Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
wsp:Body()
</wssp:MessageParts>
</wssp:Target>
</wssp:Integrity>
<wssp:MessageAge/>
</wsp:Policy>
The WebLogic Server Encrypt.xml
file specifies that the entire body of the SOAP message be encrypted. By default, the encryption token is not included in the SOAP message.
<?xml version="1.0"?>
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wssp="http://www.bea.com/wls90/security/policy"
>
<wssp:Confidentiality>
<wssp:KeyWrappingAlgorithm URI="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
<wssp:Target>
<wssp:EncryptionAlgorithm
URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
<wssp:MessageParts
Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
wsp:Body()
</wssp:MessageParts>
</wssp:Target>
<wssp:KeyInfo/>
</wssp:Confidentiality>
</wsp:Policy>
Specifies that the client and Web Service share a security context, as described by the WS-SecureConversation specification, and that a derived key token is used. This ensures the highest form of security.
This policy file provides the following configuration:
If you need to change the default security context and derived key behavior, you will have to create a custom security policy file, described in later sections.
WARNING: | If you specify this pre-packaged security policy file, you should not also specify any other pre-packaged security policy file. |
<?xml version="1.0"?>
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wssp="http://www.bea.com/wls90/security/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part"
>
<wssp:Integrity SupportTrust10="true">
<wssp:SignatureAlgorithm URI="http://www.w3.org/2000/09/xmldsig#hmac-sha1"/>
<wssp:CanonicalizationAlgorithm URI="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<wssp:Target>
<wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
<wssp:MessageParts Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
wls:SystemHeaders()
</wssp:MessageParts>
</wssp:Target>
<wssp:Target>
<wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
<wssp:MessageParts Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
wls:SecurityHeader(wsu:Timestamp)
</wssp:MessageParts>
</wssp:Target>
<wssp:Target>
<wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
<wssp:MessageParts Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
wsp:Body()
</wssp:MessageParts>
</wssp:Target>
<wssp:SupportedTokens>
<wssp:SecurityToken IncludeInMessage="true"
TokenType="http://schemas.xmlsoap.org/ws/2005/02/sc/dk"
DerivedFromTokenType="http://schemas.xmlsoap.org/ws/2005/02/sc/sct">
<wssp:Claims>
<wssp:Label>WS-SecureConversationWS-SecureConversation</wssp:Label>
<wssp:Length>16</wssp:Length>
</wssp:Claims>
</wssp:SecurityToken>
</wssp:SupportedTokens>
</wssp:Integrity>
<wssp:Confidentiality SupportTrust10="true">
<wssp:Target>
<wssp:EncryptionAlgorithm URI="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
<wssp:MessageParts Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
wsp:Body()</wssp:MessageParts>
</wssp:Target>
<wssp:KeyInfo>
<wssp:SecurityToken IncludeInMessage="true"
TokenType="http://schemas.xmlsoap.org/ws/2005/02/sc/dk"
DerivedFromTokenType="http://schemas.xmlsoap.org/ws/2005/02/sc/sct">
<wssp:Claims>
<wssp:Label>WS-SecureConversationWS-SecureConversation</wssp:Label>
<wssp:Length>16</wssp:Length>
</wssp:Claims>
</wssp:SecurityToken>
</wssp:KeyInfo>
</wssp:Confidentiality>
<wssp:MessageAge/>
</wsp:Policy>
Specifies that the client and Web Service share a security context, as described by the WS-SecureConversation specification. In this case, security context tokens are used to encrypt and sign the SOAP messages, which differs from Wssc-dk.xml in which derived key tokens are used. The Wssc-sct.xml
policy file is provided to support all the use cases of the specification; for utmost security, however, BEA recommends you always use Wssc-dk.xml when specifying shared security contexts due to its higher level of security.
This security policy file provides the following configuration:
If you need to change the default security context and derived key behavior, you will have to create a custom security policy file, described in later sections.
WARNING: | If you specify this pre-packaged security policy file, you should not also specify any other pre-packaged security policy file. |
<?xml version="1.0"?>
<wsp:Policy
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
xmlns:wssp="http://www.bea.com/wls90/security/policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part"
>
<wssp:Integrity SupportTrust10="true">
<wssp:SignatureAlgorithm URI="http://www.w3.org/2000/09/xmldsig#hmac-sha1"/>
<wssp:CanonicalizationAlgorithm URI="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<wssp:Target>
<wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/> <wssp:MessageParts Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
wls:SystemHeaders()
</wssp:MessageParts>
</wssp:Target>
<wssp:Target>
<wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
<wssp:MessageParts Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
wls:SecurityHeader(wsu:Timestamp)
</wssp:MessageParts>
</wssp:Target>
<wssp:Target>
<wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
<wssp:MessageParts Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
wsp:Body()
</wssp:MessageParts>
</wssp:Target>
<wssp:SupportedTokens>
<wssp:SecurityToken IncludeInMessage="true"
TokenType="http://schemas.xmlsoap.org/ws/2005/02/sc/sct">
</wssp:SecurityToken>
</wssp:SupportedTokens>
</wssp:Integrity>
<wssp:Confidentiality SupportTrust10="true">
<wssp:Target>
<wssp:EncryptionAlgorithm URI="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
<wssp:MessageParts Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
wsp:Body()</wssp:MessageParts>
</wssp:Target>
<wssp:KeyInfo>
<wssp:SecurityToken IncludeInMessage="true"
TokenType="http://schemas.xmlsoap.org/ws/2005/02/sc/sct">
</wssp:SecurityToken>
</wssp:KeyInfo>
</wssp:Confidentiality>
<wssp:MessageAge />
</wsp:Policy>