WS-Security language basics

Note

Only element descriptions are provided in this section. Concepts relating to WS-Security are covered in Chapter 7.

The WS-Security framework provides extensions that can be used to implement message-level security measures. These protect message contents during transport and during processing by service intermediaries. Additional extensions implement authentication and authorization control, which protect service providers from malicious requestors. WS-Security is designed to work with any of the WS-* specifications we discuss in this chapter, as shown in Figure 17.5.

Figure 17.5. How WS-Security relates to the other WS-* specifications discussed in this chapter.

The WS-Security framework is comprised of numerous specifications, many in different stages of acceptance and maturation. In this book we've concentrated on some of the more established ones, namely:

• WS-Security
• XML-Encryption
• XML-Signature

Note that WS-Security represents a framework but also a specification that defines language elements. Because the language element descriptions provided in this chapter originate from three separate specifications, we qualify each element name with its origin.

Additionally, as part of our exploration of Web services security in Chapter 7, we discussed the features of the SAML specification, which enable centralized authentication and authorization. Because single sign-on languages are beyond the scope of this book, we don't discuss SAML language elements. (However, we do provide an example of a SAML SOAP header later on.)

17.5.1. The Security element (WS-Security)

This construct represents the fundamental header block provided by WS-Security. The Security element can have a variety of child elements, ranging from XML-Encryption and XML-Signature constructs to the token elements provided by the WS-Security specification itself.

Security elements can be outfitted with actor attributes that correspond to SOAP actor roles (explained at the end of Chapter 5). This allows you to add multiple Security blocks to a SOAP message, each intended for a different recipient.

17.5.2. The UsernameToken, Username, and Password elements (WS-Security)

The UsernameToken element provides a construct that can be used to host token information for authentication and authorization purposes. Typical children of this construct are the Username and Password child elements, but custom elements also can be added.

17.5.3. The BinarySecurityToken element (WS-Security)

Tokens stored as binary data, such as certificates, can be represented in an encoded format within the BinarySecurityToken element.

17.5.4. The SecurityTokenReference element (WS-Security)

This element allows you to provide a pointer to a token that exists outside of the SOAP message document.

17.5.5. Composing Security element contents (WS-Security)

As previously mentioned, the WS-Security specification positions the Security element as a standardized container for header blocks originating from other security extensions. The following example illustrates this by showing how a SAML block is located within the Security construct. (As previously mentioned, single sign-on languages are beyond the scope of this book. The SAML-specific elements shown in this example therefore are not explained.)

17.5.6. The EncryptedData element (XML-Encryption)

This is the parent construct that hosts the encrypted portion of an XML document. If located at the root of an XML document, the entire document contents are encrypted.

The EncryptedData element's Type attribute indicates what is included in the encrypted content. For example, a value of http://www.w3.org/2001/04/xmlenc#Element indicates that the element and its contents will be encrypted, whereas the value of http://www.w3.org/2001/04/xmlenc#Content states that encryption will only be applied to the content within the opening and closing tags.

17.5.7. The CipherData, CipherValue, and CipherReference elements (XML-Encryption)

The CipherData construct is required and must contain either a CipherValue element hosting the characters representing the encrypted text or a CipherReference element that provides a pointer to the encrypted values.