Section 12.9. Putting the Pieces Together

12.9. Putting the Pieces Together

We now show how WS-Security uses these techniques to secure Web service interactions.

12.9.1. The Basic Model

In its simplest form, WS-Security carries a single signed security token asserting the requester's security information without further protection. The following SOAP envelope shows this:

<S:Envelope xmlns:S="..."     xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/...">   <S:Header>             ...         <wsse:Security>             <wsse:UsernameToken wsu:>                <wsse:Username>alice</wsse:Username>             </wsse:UsernameToken>         </wsse:Security>             ...   </S:Header>   ...   <S:Body>       ...   </S:Body> </S:Envelope> 

The WS-Security specification defines a header block called <wsse:Security>, which might contain one or more security tokens. A message might contain zero or more <wsse:Security> headers. If multiple security headers exist, each one must be targeted at a different SOAP Actor or Role. In this case, one security token, the <wsse:UsernameToken> element, asserts the identity of the requester.

This form is useful when the sender node and the receiver node are located in a controlled environment, or when the transport or lower layers provide sufficient protection (such as when the connection is protected by TLS or IPSec). One typical usage scenario is to propagate the end user's identity to back-end Web services. In Figure 12-6, the end user's identity is authenticated by the HTTP front-end server using HTTP Basic Authentication. The front-end server then forwards the identity information to the back-end Web service using the username token in WS-Security. Because the front-end server is located in the same security domain as the Web service, the Web service can trust the assertion regarding the end user's identity. Protection during transmission is provided by hop-by-hop SSL/TLS connections.

Figure 12-6. Propagating the end user's identity.

In this scenario, this might be the internal security model for CompanyABC. The company's application executes in a Web application server, which uses Web services to connect with other applications. The Web server uses an intraenterprise security system to authenticate the user ID and password. The Web services infrastructure trusts the Web server and simply accepts the security token.

WS-Security also protects messages against unauthorized access and modification during network transition. The following message structure shows WS-Security defined elements in a SOAP message whose body is protected by XML Signature for integrity and XML Encryption for confidentiality:

<S:Envelope xmlns:S="..."     xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/..."     xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'     xmlns:ds='http://www.w3.org/2000/09/xmldsig#' >     <S:Header>              ...         <wsse:Security>             <wsse:BinarySecurityToken>   ...(e.g., X.509 Certificate) ...              </wsse:BinarySecurityToken>              <xenc:ReferenceList>                 <xenc:DataReference URI="#bodyID"/>              </xenc:ReferenceList>              <ds:Signature>                ...(for the message body) ...               </ds:Signature>          </wsse:Security>              ...     </S:Header>     ...     <S:Body>        <xenc:EncryptedData >           ...        </xenc:EncryptedData>     </S:Body> </S:Envelope> 

In addition to security tokens, the WS-Security header block, <wsse:Security>, might also contain encryption directives (in the <xenc:ReferenceList> element) and signature directives (in the <ds:Signature> element). Typically, a security token carries an X.509 certificate that is used in conjunction with the signature. The receiving node will process these subelements in the order they appear. In this case, it processes the binary security token and extracts the X.509 certificate within, decrypts the message body that is referenced by the <xenc:ReferenceList> subelement, and verifies the signature contained in the <ds:Signature> element. Consequently, the sender node is responsible for prepending subelements as they are processed during the message's composition.

12.9.2. Model with Intermediary

Because the <wsse:Security> element is a SOAP header block, it can be targeted at any SOAP receiver that might be on the message path, using the role attribute (or the actor attribute if the envelope uses SOAP 1.1). Accordingly, a SOAP message can contain multiple <wsse:Security> header blocks, but each block must be targeted to a different receiver. The order of these header blocks doesn't matter because the SOAP specification does not specify any particular order when targeting headers to intermediaries. It is possible to have one security header block with no target, which is assumed to apply to the message and all actors. An intermediary node should process header blocks targeted at the node, then remove them, and optionally add new header blocks, before transferring the message to the next node in the message path. A message can still be protected against unauthorized accesses and modifications in the presence of un-trusted intermediaries if the originator signs it with its own signature and encrypts it with the key of the ultimate receiver.

In this example, CompanyABC can sign some of the request information it forwards to Fabrikam456, which defines the request for travel. Fabrikam456 can add information to the request as it interacts with the airline and hotel. Because the original request information is signed, the airline and hotel are assured that CompanyABC originated the travel request, and can process Fabrikam456's operations within the context of the original request. CompanyABC's application might encrypt the message also (with keys known to all parties) and send private information to the airline and hotel, which Fabrikam456 will not be able to examine. This information might include account and discount information, contract numbers, and so on.

12.9.3. Trust Relationships

A security token can be self-generated (as in the case of a username token) or vouched for by a trusted third party. If the message's sender and receiver are both in the same security domain (or have a direct trust relationship), and the communication channel is protected at the transport level, self-generated security tokens can be trusted. Otherwise, security tokens must be vouched for by a third party who is trusted by both the sender and the receiver. In the WS-Security model, this trusted third party is a Security Token Service. WS-Trust defines protocols and standard WSDL interfaces to communicate with an STS.

When a security token service is involved in establishing a trust relationship, two interaction models exist. One is the pull model, where the receiver checks the validity of a received security token with the security token service. The other is the push model, where the sender first requests that a token be issued by the security token service.

Figure 12-7 shows the pull model of trust establishment. The requester makes a request to the Web service, which is associated with explicit or implied security claims. An example is an identity claim, expressed as a username token along with a password as proof of possession. The Web service then verifies that the password belongs to the claimed requester by consulting with the STS. This corresponds to a directory lookup operation in conventional IT configurations.

Figure 12-7. The pull model of trust relationships.

For example, this model may be used if CompanyABC employees have an application on their notebooks that allows them to interact with Fabrikam456 while traveling. The notebook application produces a security token based on user ID and password for the user in CompanyABC. The notebook application encrypts this token with CompanyABC's public key. The notebook application and CompanyABC rely on the WellKnown Security provider for certificate support. Fabrikam456 receives a Web service request for the notebook application, which contains the security token. Fabrikam456 then calls (pulls) the validation from a WS-Trust interface that CompanyABC provides.

Another example is an authorization claim, which might be implicit in the request, that the requester is authorized to call the Web service. The Web service verifies the identity of the requester by examining other security tokens, and then it consults the security token service if the requester is allowed to access the service. This corresponds to the use of an access control server in a company's intranet.

In the push model (shown in figure 12-8) the requester obtains a cryptographically signed security token from an STS in advance and then binds the token to the request. For example, the requester can log in and obtain a Kerberos Ticket Granting Ticket (TGT) from the security token service. The requester then uses a derived Ticket Granting Service ticket (TGS) to make the subsequent requests.

Figure 12-8. The push mode of trust relationships.

In this example, the traveler's notebook application might directly contact CompanyABC's STS and receive a security token for access to Fabrikam456. The application then forwards this token on requests to Fabrikam456. Fabrikam456 can verify the token using several means, including signature verification (the token is signed) relying on the WellKnown Security certificate authority.

When one security token can be used repeatedly, the push model is more efficient in terms of the number of communications with the security token service. The downside is that any security token might be revoked, so the receiving Web service must check its validity anyway if the policy requires it.