Secure web services applications using the WSS APIs at the message level

Standards and profiles address how to provide protection for messages that are exchanged in a web service environment. Web Services Security is a message-level standard based on securing SOAP messages through XML digital signature, confidentiality through XML encryption, and credential propagation through security tokens.

To secure web services, you must consider a broad set of security requirements, including authentication, authorization, privacy, trust, integrity, confidentiality, secure communications channels, delegation, and auditing across a spectrum of application and business topologies. One of the key requirements for the security model in today's business environment is the ability to interoperate between formerly incompatible security technologies in heterogeneous environments. The complete Web Services Security protocol stack and technology roadmap is described in the web services roadmap.

The Organization for the Advancement of Structured Information Standards (OASIS) Web Services Security: SOAP Message Security Version 1.1 specification is the basic messaging transport for all web services. SOAP 1.2 adds extensions to the existing SOAP 1.1 extensions so that we can build secure web services. Attachments can be added to SOAP messages by using Message Transmission Optimization Mechanism (MTOM) and XML-binary Optimized Packaging (XOP) instead of the SOAP with Attachments (SWA) profile.

The OASIS Web Services Security (WS-Security) Version 1.1 specification is the building block used in conjunction with other web service and application-specific protocols to accommodate a wide variety of security models. Web Services Security for WebSphere Application Server is based on specific standards that are included in the OASIS Web Services Security Version 1.1 specification and profiles.

The Version 1.1 specification defines additional facilities for protecting the integrity and confidentiality of a message. The Version 1.1 specification also provides the mechanisms for associating security-related claims with the message. The Web Services Security Version 1.1 standards that are supported by WebSphere Application Server include the signature confirmation, encrypted header elements, the Username Token Profile and the X.509 Token Profile. The Username Token Profile and the X.509 Token Profile have been updated as Version 1.1 profiles. For the X.509 Certificate Token Profile, one new type of security token reference is the Thumbprint reference, which is specified in the binding.

XML Schema, Part 1 and Part 2 are specifications that explain how schemas are organized in XML documents. The two WS-Security Version 1.0 schemas have been updated to the Version 1.1 specifications plus a new Version 1.1 schema has been added. Note that the Version 1.1 schema does not replace the Version 1.0 schema but instead builds upon it by defining an additional set of capabilities within a Version 1.1 namespace.

Use the following methods to configure Web Services Security and to define policy types to secure the SOAP messages:

• Use the administrative console to configure policy sets.

  This method uses the bootstrap policy defined in the policy set. Use policy sets, or assertions about how services are defined, to simplify the security configuration for web services. Use the administrative console to create, modify, and delete custom policy sets. A set of default policy sets are available.

  For example, we can define the bootstrap policy in the policy set to secure the Web Services Trust (WS-Trust) SOAP messages.

  We can also use the administrative console to perform policy set management tasks and to secure web services using encryption, signing information, and security tokens.

  The following steps high-level steps describe how to configure WebSphere Application Server to use WS-Security and to secure the SOAP messages using the administrative console. The generator and consumer tasks that are discussed in the following steps use WS-Security Versions 1.0 and 1.1.

  • Create and configure the application policy sets or the system policy sets for trust service.

  • Define the policy types to be used to secure the SOAP messages when creating and configuring the policy sets.

  • Configure the policy set binding. Select either the symmetric or asymmetric binding assertion to describe the token type and the algorithm to be used for message protection.

  • Assemble your Web Services Security-enabled application by using an assembly tool.

• Use the Web Services Security APIs (WSS API) to configure the SOAP message context (only for the client)

  WAS uses a new API programming model. In addition to the existing JAX-RPC programming model, a new programming model, JAX-WS, has been added. The JAX-WS programming standard aligns with the document-centric messaging model and replaces the remote procedure call programming model defined by the Java API for XML-based RPC (JAX-RPC) specification.

  For example, an application could create system policy sets and then use the WAS WSS API to acquire the security context token for programmatic API-based Web Services Secure Conversation (WS-SecureConversation).

  We can also use the administrative console to perform the encryption, signing, and token configuration tasks that the WSS APIs perform to secure web services.

  The following high-level steps describe how to configure WebSphere Application Server to use WS-Security and to secure the SOAP messages using the WSS APIs. The generator and consumer tasks that are discussed in the following steps use WS-Security Versions 1.0 and 1.1.

  • Use the WSSSignature API to configure the signing information for the request generator (client side) binding.

    Different message parts can be specified in the message protection for a request on the generator side. The default required parts are BODY, ADDRESSING_HEADERS and TIMESTAMP.

    The WSSSignature API also specifies the different algorithm methods to be used with the signature for message protection. The default signature method is RSA_SHA1. The default canonicalization method is EXC_C14N.

  • Use the WSSSignPart API to change the digest method and the transform method.

    The default signed parts are WSSSignature.BODY, WSSSignature.ADDRESSING_HEADERS and WSSSignature.TIMESTAMP.

    The WSSSignPart API also specifies the different algorithm methods to be used if we added or changed the signed parts. The default digest method is SHA1. The default transform method is TRANSFORM_EXC_C14N. For example, use the WSSSignPart API to generate the signature for the SOAP message using the SHA256 digest method instead of the default value of SHA1.

  • Use the WSSEncryption API to configure the encryption information on the request generator side.

    The encryption information on the generator side is used for encrypting an outgoing SOAP message for the request generator (client side) bindings. The default targets of encryption are BODY_CONTENT and SIGNATURE.

    The WSSEncryption API also specifies the different algorithm methods to be used to protect message confidentiality. The default data encryption method is AES128. The default key encryption method is KW_RSA_OAEP.

  • Use the WSSEncryptPart API to set the transform method only.

    For example, to change the data encryption method from the default value of AES128 to TRIPLE_DES.

    No algorithm methods are required for encrypted parts.

  • Use the WSS API to configure the token on the generator side.

    The requirements for the security token depend on the token type. The JAAS Login Module and the JAAS CallbackHandler are responsible for creating the security token on the generator side. Different stand-alone tokens can be sent in request and response. The default token is the X509Token. The other token that can be used for signing is the DerivedKeyToken, which is used only with Web Services Secure Conversation (WS-SecureConversation).

  • Use the WSSVerification API to verify the signature for the response consumer (client side) binding.

    Different message parts can be specified in the message protection for a response on the consumer side. The required targets for verification are BODY, ADDRESSING_HEADERS and TIMESTAMP.

    The WSSVerification API also specifies the different algorithm methods to be used for verifying the signature and for message protection. The default signature method is RSA_SHA1. The default canonicalization method is EXC_C14N.

  • Use the WSSVerifyPart API to change the digest method and the transform method. The required verify parts are WSSVerification.BODY, WSSVerification.ADDRESSING_HEADERS and WSSVerification.TIMESTAMP.

    The WSSVerifyPart API also specifies the different algorithm methods to be used if we added or changed the verification parts. The default digest method is SHA1. The default transform method is TRANSFORM_EXC_C14N.

  • Use the WSSDecryption API to configure the decryption information for the response consumer (client side) binding.

    The decryption information on the consumer side is used for decrypting an incoming SOAP message. The targets of decryption are BODY_CONTENT and SIGNATURE. The default key encryption method is KW_RSA_OAEP.

    No algorithm methods are required for decryption.

  • Use the WSSDecryptPart API to set the transform method only.

    For example, to change the data encryption method from the default value of AES128 to TRIPLE_DES.

    No algorithm methods are required for decrypted parts.

  • Use the WSS API to configure the token on the consumer side.

    The requirements for the security token depend on the token type. The JAAS Login Module and the JAAS CallbackHandler are responsible for validating (authenticating) the security token on the consumer side. Different stand-alone tokens can be sent in request or response.

    The WSS API adds the information for the candidate token used for decryption. The default token is X509Token.

• Use the wsadmin administrative scripting tool to configure policy sets.

  This method allows us to create, manage, and delete policy sets from the command-line or to create scripts to automate your tasks. Use wsadmin.sh and the PolicySetManagement command group to manage default policy sets, create custom policy sets, configure policies, and manage attachments and bindings. For more information, use the policy set scripting topics in the information center.

To secure web services with WebSphere Application Server, configure the generator and the consumer security constraints. Specify several different configurations. Although there is no specific sequence to specify these different configurations, some configurations reference other configurations. For example, decryption configurations reference encryption configurations.

Subtopics

• Secure messages at the request generator using WSS APIs
  We can secure SOAP messages by configuring signing information, encryption, and generator tokens to protect message integrity, confidentiality, and authenticity, respectively. This request (client-side) generator configuration defines the Web Services Security requirements for the outgoing SOAP message request.

• Secure messages at the response consumer using WSS APIs
  We can secure SOAP messages with signature verification, decryption, and consumer tokens to protect message integrity, confidentiality, and authenticity, respectively. The response consumer (client-side) configuration defines the Web Services Security requirements for the incoming SOAP response.

• Configure Web Services Security using the WSS APIs
  The Web Services Security APIs (WSS API) provide support for securing SOAP message.

• Encrypted SOAP headers
  The encrypted header element provides a standard way of encrypting SOAP headers. As one of the extensions to the OASIS SOAP message security specification, the encrypted header element indicates that the responder has processed the request. Encrypting SOAP headers and parts help to provide more secure message-level security.

• Signature confirmation
  Web Services Security signature confirmation is an enhanced XML digital signature, and it is included in the Web Services Security standard. XML digital signature is used for signing elements of the SOAP envelope.

Results

After completing these high-level steps for WebSphere Application Server, we have secured web services by configuring policy sets and using the WSS API to configure encryption and decryption, the signature and signature verification information, and the consumer and generator tokens.

Subtopics

• Secure messages at the request generator using WSS APIs
  We can secure SOAP messages by configuring signing information, encryption, and generator tokens to protect message integrity, confidentiality, and authenticity, respectively. This request (client-side) generator configuration defines the Web Services Security requirements for the outgoing SOAP message request.

• Secure messages at the response consumer using WSS APIs
  We can secure SOAP messages with signature verification, decryption, and consumer tokens to protect message integrity, confidentiality, and authenticity, respectively. The response consumer (client-side) configuration defines the Web Services Security requirements for the incoming SOAP response.

• Configure Web Services Security using the WSS APIs
  The Web Services Security APIs (WSS API) provide support for securing SOAP message.

• Encrypted SOAP headers
  The encrypted header element provides a standard way of encrypting SOAP headers. As one of the extensions to the OASIS SOAP message security specification, the encrypted header element indicates that the responder has processed the request. Encrypting SOAP headers and parts help to provide more secure message-level security.

• Signature confirmation
  Web Services Security signature confirmation is an enhanced XML digital signature, and it is included in the Web Services Security standard. XML digital signature is used for signing elements of the SOAP envelope.

Related concepts

Web Services Security API programming model

Related tasks

Configure application and system policy sets for web services

Configure secure transmission of SOAP messages by using WS-Security

Get WS-Security information from our owning parties

Web Services Security APIs

PolicySetManagement (AdminTask)

Web services specifications and APIs

Related information:

Web Services Security: SOAP Message Security Version 1.1 specification

Security in a Web Services World: A Proposed Architecture and Roadmap