WS-Security

Web Services Security (WS-Security) describes enhancements to SOAP messaging to provide quality of protection through message integrity, message confidentiality, and single message authentication. WS-Security mechanisms can be used to accommodate a wide variety of security models and encryption technologies. WS-Security is a message-level standard that is based on securing SOAP messages through XML digital signature, confidentiality through XML encryption, and credential propagation through security tokens. The Web services security specification defines the facilities for protecting the integrity and confidentiality of a message and provides mechanisms for associating security-related claims with the message. WS-Security provides a general-purpose mechanism for associating security tokens with messages. No specific type of security token is required by WSSecurity. It is designed to be extensible, for example, to support multiple security token formats. WS-Security also describes how to encode binary security tokens and attach them to SOAP messages. Specifically, the WS-Security profile specifications describe how to encode the following tokens: Username tokens X.509 certificates SAML assertions Kerberos tickets LTPA binary tokens With WS-Security, the domain of these mechanisms can be extended by carrying authentication information in Web services requests. WS-Security also includes extensibility mechanisms that can be used to further describe the credentials that are included with a message. WS-Security is a building block that can be used in conjunction with other Web service protocols to address a wide variety of application security requirements. There are numerous advantages to using WS-Security. Different parts of a message can be secured in a variety of ways. For example, you can use integrity on the security token (user ID and password) and confidentiality on the SOAP message body. Intermediaries can be used and end-to-end message-level security can be provided through any number of intermediaries. WS-Security works across multiple transports and is independent of the underlying transport protocol.

Authentication of both individual users and multiple party identities is possible.

Traditional Web security mechanisms, such as HTTPS, might be insufficient to manage the security requirements of all Web service scenarios. For example, when an application sends a SOAP message using HTTPS, the message is secured only for the HTTPS connection, meaning during the transport of the message between the service requester (the client) and the service. However, the application might require that the message data be secured beyond the HTTPS connection, or even beyond the transport layer. By securing Web services at the message level, message-level security is capable of meeting these expanded requirements. Message-level security, or securing Web services at the message level, addresses the same security requirements as for traditional Web security. These security requirements include: identity, authentication, authorization, integrity, confidentiality, nonrepudiation, and basic message exchange. Both traditional Web and message-level security share many of the same mechanisms for handling security, including digital certificates, encryption, and digital signatures. With message-level security, the SOAP message itself either contains the information needed to secure the message or it contains information about where to get that information to handle security needs. The SOAP message also contains information relevant to the protocols and procedures for processing the specified message-level security. However, message-level security is not tied to any particular transport mechanism. Because the security information is part of the message, it is independent of a transport protocol, such as HTTPS. The client adds to the SOAP message header security information that applies to that particular message. When the message is received, the Web service endpoint, using the security information in the header, verifies the secured message and validates it against the policy. For example, the service endpoint might verify the message signature and check that the message has not been tampered with. It is possible to add signature and encryption information to the SOAP message headers, as well as other information such as security tokens for identity (for example, an X.509 certificate) that are bound to the SOAP message content. Without message-level security, the SOAP message is sent in clear text, and personal information such as a user ID or an account number is not protected. Without applying message-level security, there is only a SOAP body under the SOAP envelope in the SOAP message. By applying features

from the WS-Security specification, the SOAP security header is inserted under the SOAP envelope in the SOAP message when the SOAP body is signed and encrypted. To keep the integrity or confidentiality of the message, digital signatures and encryption are typically applied. Confidentiality specifies the confidentiality constraints that are applied to generated messages. This includes specifying which message parts within the generated message must be encrypted, and the message parts to attach encrypted Nonce and time stamp elements to. Integrity is provided by applying a digital signature to a SOAP message. Confidentiality is applied by SOAP message encryption. You can add an authentication mechanism by inserting various types of security tokens, such as the Username token (element). When the Username token is received by the Web service server, the user name and password are extracted and verified. Only when the user name and password combination is valid, will the message be accepted and processed at the server. Using the Username token is just one of the ways of implementing authentication. This mechanism is also known as basic authentication. The OASIS Web Services Security Specification provides a set of mechanisms to help developers of Web Services secure SOAP message exchanges. For details of the OASIS Web Services Security Specification, see OASIS Standard for WS-Security Specification.

WS-Security mechanisms
The WS-Security specification provides three mechanisms for securing Web services at the message level: authentication, integrity, and confidentiality.

Authentication
This mechanism uses a security token to validate the user and determine whether a client is valid in a particular context. A client can be a user, computer, or application. Without authentication, an attacker can use spoofing techniques to send a modified SOAP message to the service provider. In authentication, a security token is inserted in the request message. Depending on the type of security token that is being used, the security

token can also be inserted in the response message. The following types of security token are supported for authentication:

Username tokens X.509 certificates SAML assertions Kerberos tickets LTPA binary tokens

Username tokens are used to validate user names and passwords. When a Web service server receives a username token, the user name and password are extracted and passed to a user registry for verification. If the user name and password combination is valid, the result is returned to the server and the message is accepted and processed. When used in authentication, username tokens are typically passed only in the request message, not the response message. X.509 tokens are validated by using a certificate path. The broker support for SAML assertions is restricted to passing the token to a WS-Trust security token server (STS) for validation. Kerberos tickets are validated against the host's Kerberos keytab file. The broker support for LTPA binary tokens is restricted to passing the token to a WS-Trust STS for validation.
All types of token must be protected. For this reason, if you send them over an untrusted network, take one of the following precautions:

Use HTTPS Configure the policy set to protect the appropriate elements in the SOAP header

Integrity
This mechanism uses message signing to ensure that information is not changed, altered, or lost accidentally. When integrity is implemented, an XML digital signature is generated on the contents of a SOAP message. If unauthorized changes are made to the message data, the signature is not validated. Without integrity, an attacker can use tampering techniques to intercept a SOAP message between the Web service client and server, and modify it.

Confidentiality
This mechanism uses message encryption to ensure that no party or process can access or disclose the information in the message. When a SOAP message is encrypted, only a service that knows the appropriate key can decrypt and read the message.

WS-Addressing
Web Services Addressing (WS-Addressing) is a World Wide Web Consortium (W3C) specification that aids interoperability between Web services by defining a standard way to address Web services and provide addressing information in messages. Start here to find out how WebSphere Message Broker supports WSAddressing.
The WS-Addressing specification introduces two primary concepts: endpoint references, and message addressing properties. This topic contains an overview of each concept. For further details, select the following links to access the WSAddressing specifications:

W3C WS-Addressing specifications W3C submission WS-Addressing specification

Endpoint references (EPRs)

EPRs provide a standard mechanism to encapsulate information about specific endpoints. EPRs can be propagated to other parties and then used to target the Web service endpoint that they represent. The following table summarizes the information model for EPRs.

Abstract Property name

Property type

Multiplicity

Description

[address]

xs:anyURI

1..1

The absolute URI that specifies the address of the endpoint.

[reference parameters]*

xs:any

0..unbounded

Namespace qualified element information items that are required to interact with the endpoint.

Abstract Property name

Property type

Multiplicity

Description

[metadata]

xs:any

0..unbounded

Description of the behavior, policies and capabilities of the endpoint.

The following prefix and corresponding namespace is used in the previous table.

Prefix

Namespace

xs

http://www.w3.org/2001/XMLSchema

The following XML fragment illustrates an endpoint reference. This element references the endpoint at the URI http://example.com/fabrikam/acct, has metadata specifying the interface to which the endpoint reference refers, and has application-defined reference parameters of the http://example.com/fabrikam namespace.
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" xmlns:fabrikam="http://example.com/fabrikam" xmlns:wsdli="http://www.w3.org/2005/08/wsdl-instance" wsdli:wsdlLocation="http://example.com/fabrikam http://example.com/fabrikam/fabrikam.wsdl"> <wsa:Address>http://example.com/fabrikam/acct</wsa:Address> <wsa:Metadata> <wsaw:InterfaceName>fabrikam:Inventory</wsaw:InterfaceName> </wsa:Metadata> <wsa:ReferenceParameters> <fabrikam:CustomerKey>123456789</fabrikam:CustomerKey> <fabrikam:ShoppingCart>ABCDEFG</fabrikam:ShoppingCart> </wsa:ReferenceParameters> </wsa:EndpointReference>

Message addressing properties (MAPs)

MAPs are a set of well defined WS-Addressing properties that can be represented as elements in SOAP headers. MAPs can provide either a standard way of conveying information, such as the endpoint to which message replies should be directed, or information about the relationship that the message has with other messages. The MAPs that are defined by the WS-Addressing specification are summarized in the following table.

Abstract WSAddressing MAP name

MAP content type

Multiplicity

Description

[action]

xs:anyURI

1..1

An absolute URI that uniquely identifies the semantics of the message. This proprety corresponds to the [address] property of the endpoint reference to which the message is addressed. This value is required.

[destination]

xs:anyURI

1..1

The absolute URI that specifies the address of the intended receiver of this message. This value is optional because, if not present, it defaults to the anonymous URI that is defined in the specification, indicating that the address is defined by the underpinning protocol.

[reference parameters]*

xs:any

0..unbounded

Correspond to the [reference parameters] property of the endpoint reference to which the message is addressed. This value is optional.

[source endpoint]

EndpointReference

0..1

A reference to the endpoint from which the message originated. This value is optional.

[reply endpoint]

EndpointReference

0..1

An endpoint reference for the intended receiver of replies to this message. This value is optional.

Abstract WSAddressing MAP name

MAP content type

Multiplicity

Description

[fault endpoint]

EndpointReference

0..1

An endpoint reference for the intended receiver of faults relating to this message. This value is optional.

[relationship]*

xs:anyURI plus optional attribute of type xs:anyURI

0..unbounded

A pair of values that indicate how this message relates to another message. The content of this element conveys the [message id] of the related message. An optional attribute conveys the relationship type. This value is optional.

[message id]

xs:anyURI

An absolute URI that uniquely identifies the message. This value is optional.

The abstract names in the previous tables are used to refer to the MAPs throughout this documentation. The following example of a SOAP message contains WS-Addressing MAPs:
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:fabrikam="http://example.com/fabrikam"> <S:Header> ... <wsa:To>http://example.com/fabrikam/acct</wsa:To> <wsa:ReplyTo> <wsa:Address> http://example.com/fabrikam/acct</wsa:address> </wsa:ReplyTo> <wsa:Action>...</wsa:Action> <fabrikam:CustomerKey wsa:IsReferenceParameter='true'>123456789 </fabrikam:CustomerKey> <fabrikam:ShoppingCart wsa:IsReferenceParameter='true'>ABCDEFG

</fabrikam:ShoppingCart> ... </S:Header> <S:Body> ... </S:Body> </S:Envelope>

Related concepts: What is SOAP? Related tasks: Processing Web service messages