Web Services Security SOAP Message Security (WS-Security) is an international standard for interoperable web services security that was developed in OASIS by a collaboration of all the major providers of web services technology (including Sun Microsystems). WS-Security is a message security mechanism that uses XML Encryption and XML Digital Signature to secure web services messages sent over SOAP. The WS-Security specification defines the use of various security tokens including X.509 certificates, SAML assertions, and username and password tokens to authenticate and encrypt SOAP Web Services messages. This section also includes the following sections:
Understanding message security in the Web Server
Securing a web service
Securing a sample application
Configuring the Web Server for message security
Admin Console tasks for message security
The Web Server offers integrated support for the WS-Security standard in the server-side container. This functionality is integrated with Web Services security and enforced by the container of the Web Server on behalf of applications. Web Server can protect any web service application without requiring changes to the implementation of the application. The Web Server achieves this effect by providing facilities to bind SOAP layer message security providers and message protection policies to container and to applications deployed in container.
In the Web Server, the system administrator and application deployer roles are expected to take primary responsibility for configuring message security. In some situations, the application developer also contribute, although in the typical case either of the roles might secure an existing application without changing its implementation and therefore without involving the developer. The responsibilities of the various roles are defined in the following sections.
The system administrator is responsible for the following tasks:
Configuring message security providers on the Web Server
Managing user databases
Managing the keystore and truststore files
Deploying the samples program fromwsdl-soap12, which demonstrates the message layer web services security
A system administrator uses the Admin Console to manage server security settings. Web Server stores certificates and private keys in an NSS database, the administrator can manage them using certutil. For an overview of message security tasks, see Configuring the Web Server for Message Security.
The application deployer is responsible for the following tasks:
Specifying at application assembly any required application-specific message protection policies if such policies have not already been specified by upstream roles (the developer or assembler).
Modifying Sun deployment descriptors to specify application-specific message protection policies information message-security-binding elements to a web service endpoint.
The application developer can setup message security but is not responsible for doing so. The system administrator can set the message security so that all Web Services are secured. The application deployer can set the message security when the provider or protection policy bound to the application must be different from that bound to the container.
The application developer or assembler is responsible for the following tasks:
Determining whether an application-specific message protection policy is required by the application. If the policy is required, the developer or assembler works with the application deployer and ensures that the required policy is specified during application assembly.
The WS-Security specification provides an extensible mechanism for using security tokens to authenticate and encrypt SOAP Web Services messages. Use the SOAP-layer message security providers installed with the Web Server to employ username, password and X.509 certificate security tokens to authenticate and encrypt SOAP Web Services messages.
The Web Server uses username tokens in the SOAP messages to establish the authentication identity of the message sender. The recipient of a message containing a Username token within an embedded password validates that the message sender is authorized to act as the user (identified in the token) by confirming that the sender knows the users secret password.
When using a Username token, a valid user database must be configured on the Web Server.
The Web Server uses XML Digital signatures to bind an authentication identity to the message content. Clients use digital signatures to establish their caller identity, analogous to basic authentication or SSL client certificate authentication. Digital signatures are verified by the message receiver to authenticate the source of the message content, which might be different from the sender of the message. When using digital signatures, valid keystore and truststore files must be configured on the Web Server.
The purpose of encryption is to modify the data such that it can only be understood by its intended audience. This modification is accomplished by substituting an encrypted element for the original content. When predicated on public key cryptography, encryption establishes the identity of the parties who can read the message.
Message protection policies are defined for request message processing and response message processing. These policies are expressed in terms of requirements for source or recipient authentication. A source authentication policy requires that the identity of the entity that sent a message or that defined the content of a message be established in the message so that the message receiver can authenticate it. A recipient authentication policy represents a requirement that the message be sent such that the identity of the entities that can receive the message can be established by the message sender. The providers apply specific message security mechanisms so that the message protection policies are in SOAP Web Services messages.
Request and response message protection policies are defined when a provider is configured in a container. You can also configure application-specific message protection policies at the granularity of the web service port or operation within the Sun deployment descriptors of the application or application client. Where message protection policies are defined, the request and response message protection policies of the client must match the request and response message protection policies of the server.
Web Services deployed on the Web Server are secured by binding SOAP-layer message security providers and message protection policies to the container in which the applications are deployed or to web service endpoints served by the applications. When the Web Server is installed, SOAP-layer message security providers are configured in the server-side container of the Web Server. The container or individual applications in the container can bind to them or to individual applications in the container. During installation, the providers are configured with a simple message protection policy that, if bound to a container or to an application, would cause the source of the content in all request and response messages to be authenticated by an XML digital signature.
Use the Admin Console and CLI to perform the following tasks:
To bind the existing providers for use by the server-side containers of the Web Server
To modify the message protection policies enforced by the providers
To create new provider configurations with alternative message protection policies
By default, message layer security is disabled on the Web Server. For more information about how to configure message layer security for the Web Server, seeConfiguring the Web Server for Message Security. For more information about how to use Web Services security to protect all Web Services applications deployed on the Web Server, see Enabling Providers for Message Security.
Once this security is established, Web Services security will be applied to all Web Services applications deployed on the Web Server.
Configure application-specific web services during application assembly by defining message-security-binding elements in the applications Sun deployment descriptors. Use these message-security-binding elements to associate a specific provider or message protection policy with a web services endpoint or service reference. You can also qualify these elements so that they apply to a specific port or method of the corresponding endpoint or referenced service.
All the steps for setting up the Web Server for using message security can be accomplished using the Admin Console or the wadm command-line tool. For more information on message security, see Sun Java System Web Server 7.0 Update 6 Administrator’s Guide.
Support for message-layer security is integrated into the Web Server in the form of pluggable authentication modules. By default, message layer security is disabled on the Web Server. The tasks in this section provide the details for enabling, creating, editing, and deleting message security configurations and providers.
To create a message security provider
To enable providers for message security
To delete a message security provider
To enable message security for stand-alone clients
In most cases, you need to restart or reconfigure the Web Server after performing these tasks, especially to apply the change to applications already deployed on Web Server.
You can add or edit or modify the message protection policy. The provider type, implementation class, and provider-specific configuration properties should be modified.
Login to the Admin Console.
Select the configuration you want to modify and click Edit Configuration.
Click the Java tab.
Click the Authentication tab and scroll down to the SOAP Authentication.
Click New to add a provider.
Add the new provider information
In this page, following information is available for modification.
Only Name and class Name are required. If these two fields are not specified, no authentication is applied to request or response messages. All other values are optional.
Name: Identifier for this provider. You can use this identifier name to specify the default provider when using wadm.
Class Name: The Java implementation class of the provider. Server-side providers must implement the com.sun.enterprise.security.jauth.ServerAuthModule interface.
The request policy defines the authentication policy requirements associated with request processing performed by the authentication provider. Type the policies in message-sender order. For example, a requirement that encryption occur after content means that the message receiver expects to decrypt the message before validating the signature.
Request Authentication Source— Possible values are:
sender: Message-layer sender authentication, such as username and password
content: Content authentication, for example, digital signature
null: Source authentication of the request is not required
Click the Add Property button to add additional properties.
The provider shipped with the Web Server requires the server-config property. If other providers are used, refer to their documentation for more information on properties and valid values.
server.config: The directory and file name of an XML file that contains the server configuration information. This file is in the following location install_dir/samples/java/webapps/webservices/security/etc/wss-server-config-2.0.xml.
Create a message security provider msgsecurity-provider:../bin/wadm create-soap-auth-provider --port=8989 --user=admin --password-file=/tmp/admin.passwd --config=test --class=com.sun.xml.wss.provider.ServerSecurityAuthModule --request-policy-auth-source=content --request-policy-auth-recipient=before-content --request-policy-auth-recipient=before-content --request-policy-auth-recipient=before-content msgsecurity-provider
Add the required property server.config:../bin/wadm set-soap-auth-provider-prop --port=8989 --user=admin --password-file=/tmp/admin.passwd --config=test --provider=msgsecurity-provider request-policy-auth-source=sender
List the provider properties: ../bin/wadm get-soap-auth-provider-prop --port=8989 --user=admin --password-file=/tmp/admin.passwd --config=test --provider=msgsecurity-provider
For more information about wadm commands and properties, see Sun Java System Web Server 7.0 Update 6 Administrator’s Configuration File Reference
You can enable the message security Web Services endpoints by specifying the default provider on the server side or by specifying in the message-binding element in sun-web.xml.
If you enable a default provider for message security, you also need an appropriate message security on the client side.
You cannot specify a default provider using the Admin Console. You have to specify the default provider through the wadm command-line interface.
../bin/wadm set-config-prop --port=8989 --user=admin --password-file=/tmp/admin.passwd --config=test default-soap-auth-provider-name=msgsecurity-provider
Login to the Admin Console.
Select the configuration you want to modify and click Edit Configuration.
Click the Java tab.
Click the Authentication tab and scroll down to SOAP Authentication.
To delete a message security provider through the command-line interface, type the following command:wadm delete-soap-auth-provider --port=8989 --user=admin --password-file=/tmp/admin.passwd --config=test msgsecurity-provider
Configure the message protection policies of client so that they are equivalent to the message protection policies of the server-side providers with which they interact. A typical stand-alone client is illustrated by the bundled sample fromwsdl-soap12.