Web Services Security, Part 3
by Bilal Siddiqui | Pages: 1, 2

Attribute Associations

We have now explored our example SAML assertion in detail. Recall the meaning of the assertion in simple English:

The entity (person or an organization) named "MyTourOperator" is the owner of a public key named "MyTourOperatorKey". The asserting authority has authenticated MyTourOperator using XML digital signatures. This assertion is valid from time1 until time2.

This assertion is only about the identity of an entity. It does not assert any further information about the subject. If someone wants to know if Bilal Siddiqui is an XML.com author or not, we need the assertion to assert something like the following:

It is asserted that the subject with name Bilal Siddiqui is the owner of such and such key. Moreover, Bilal Siddiqui is an XML.com author. This assertion is valid for a period starting at time1 and ending at time2.

Being an XML.com author is an attribute associated with the subject named Bilal Siddiqui. SAML defines the concept of attribute assertions, which we can use whenever we need to assert whether certain attributes are associated with subjects or not. Have a look at Listing 2.

Instead of an AuthenticationStatement element, we now have an AttributeStatement element. If you compare the AuthenticationStatement element of the first listing with the AttributeStatement element of Listing 2, you won't find much difference. The AttributeStatement element contains an extra child element named Attribute, which defines the attribute that we want to associate with the subject.

There are three things related to a security attribute, namely an attribute namespace, an attribute name, and an attribute value. We need to understand these three things.

The Attribute element has two XML attributes, namely AttributeName and AttributeNamespace.

The AttributeName attribute specifies the name of the security attribute that we want to assert. For example, in Listing 2 the value of this attribute is "PartnershipStatus", which means the partnership status of the subject named MyTourOperator. The content of AttributeValue child element provides the value of this security attribute. In our case, it is the string "MostPreferredBusinessPartner". This represents the partnership status of the tour operator.

Also look at the AttributeNamespace attribute of the Attribute element, which identifies an attribute namespace (http://www.myEMarketPlace.com/AttributeService) to which the security attribute (PartnershipStatus) belongs. In Listing 2, we are using the namespace of our fictitious marketplace. This idea of namespaces allows organizations to have security attribute names without the fear of any collision between names defined by different naming services.

Notice that the SAML specification does not define any security attributes by itself. SAML users are expected to design their own security attribute namespaces.

Now you can see that Listing 2 provides an assertion about the security attribute of a subject. We can write this assertion in simple English as follows:

It is asserted that the subject named MyTourOperator is the owner of such and such key. Moreover, MyTourOperator enjoys the status of being the most favored business partner of MyEMarketPlace.com. This assertion is valid for a period between time1 and time2.

We have discussed two types of SAML assertions, the information they convey, and their syntax. Now let's see how an application can get hold of an assertion.

How an Application Requests a SAML Assertion

An SAML-aware requester application (e.g. the tour operator) will send a request for an SAML assertion as shown in Listing 3 to a SAML authority. The SAML authority will provide a SAML response. We have shown a sample response in the listing. Let's see this request-response mechanism in detail.

Listing 3 uses two namespaces: urn:oasis:names:tc:SAML:1.0:protocol and urn:oasis:names:tc:SAML:1.0:assertion, both defined by SAML. The assertion namespace is the one that we have been using in Listings 1 and 2. The protocol namespace is used to query for assertions.

The root element is Request, containing simple attributes such as a request identifier (the RequestID attribute), version of the request (the MajorVersion and MinorVersion attributes), and the time when the request was issued (the IssueInstant attribute).

A Request contains an AttributeQuery element. This in turn contains a subject, which we discussed with regard to Listing 1. So the entire request is like asking "provide all attributes associated with this subject". Naturally the response will be a list of attribute assertions associated with MyTourOperator, as shown in Listing 4.

You can see from Listing 4 that it is a simple response to the request. The Response element has several attributes. We have already discussed the MajorVersion, MinorVersion, and IssueInstant attributes. The ResponseID attribute specifies an identifier for this response. The InResponseTo attribute specifies the request for which this response has been authored. The value of the RequestID attribute in Listing 3 matches with the value of the InResponseTo attribute of Listing 4.

The Response element contains three child elements. The first child is a Status element, which in turn has a child element named StatusCode which reports the status of this response as Success.

The second child is an Assertion element. I have omitted the details of the Assertion element from Listing 4, as this element will be exactly the same as Listing 2. There can be any number of Assertion elements, but we have shown just one.

The third element is a ds:Signature element to ensure the message integrity of the SAML response.

Protocol

How will the request and response of Listings 3 and 4 travel from the tour operator to the marketplace and back? The SAML Bindings and Profiles specification defines a SOAP over HTTP protocol for the transport of SAML assertion requests and responses. Listing 5 shows a SOAP message that wraps the SAML assertion request of Listing 3, and Listing 6 is another SOAP message that wraps the response of Listing 4. Notice that assertion requests and responses simply travel as part of the SOAP body.

We have seen the syntax of SAML assertions and demonstrated how an application will request assertions from an asserting authority and how an asserting authority will respond with the required assertions. It's now time to demonstrate how we will use SAML assertions in our XML firewall applications.

Recall the last section of the second article, where we introduced the use of security tokens in WSS messages. We used an X509 certificate as a security token. SAML assertions can also play the role of a security token.

Using SAML Assertions in WSS Applications

In Listing 7 we have wrapped an SAML assertion in a WSS message.

In order to understand what information Listing 7 contains, you need to compare it with Listing 9 from the second article. There are some differences between the two:

1. There is no BinarySecurityToken element in Listing 7. Instead of a security token, we have an assertion. The Assertion element appears as a child of the wsse:Security element, just like the BinarySecurityToken element in Listing 9 of the second article.

2. There are two ds:Signature elements in Listing 7. The first appears within the Assertion element. The marketplace produced this signature while issuing the assertion, so that any application who receives this assertion can verify its integrity. We have not shown the details of this signature for the sake of simplicity.

   The second ds:Signature appears as a direct child of the wsse:Security element. This signature is from the tour operator, which produced the signature over the GetSepcialDiscountedBookingForPartners element in the SOAP body while authoring the request.

   Compare the ds:Signature element in Listing 9 of the second article with the tour operator's ds:Signature element in Listing 7. Both these Signature elements were produced by the tour operator application. The one difference is their ds:KeyInfo elements.

   In Listing 9 of the second article, the ds:KeyInfo element referred to the tour operator's certificate wrapped inside the BinarySecurityToken element. But in Listing 7, there is no BinarySecurityToken element. Instead, we have an Assertion element acting as a security token. Therefore it makes sense to refer to the assertion from the ds:KeyInfo element.

3. As already explained, the ds:KeyInfo element in Listing 7 refers to the assertion. When the message reaches the relying party (the hotel), the hotel will need to validate the signature in order to verify requester's identity as well as the integrity of the message. Therefore the recipient will need a public key to verify the signature. Where is the tour operator's public key that the hotel application can use to verify the tour operator's signature? The Assertion element is the most relevant place to look for the tour operator's public key.

   There is only one key inside the Assertion element. Its name is "MyTourOperatorKey". The hotel will use this key to verify the tour operator's signature.

4. Notice the SubjectConfirmation element within the Assertion element, which specifies the relationship between the subject and the author of the message that contains the assertion.

   The SubjectConfirmation element should specify that the subject authored the message that contains this assertion. The SubjectConfirmation element has two child elements, namely a SubjectConfirmation and a ds:KeyInfo element. The two child elements form a pair.

   The ConfirmationMethod element wraps the string identifier for the holder-of-key method that we discussed earlier. The holder-of-key method simply specifies that the author of this message is the subject of the assertion and it holds the key wrapped by the accompanying ds:KeyInfo element. Notice that the accompanying ds:KeyInfo element, which is a sibling of the ConfirmationMethod element, wraps the key named "MyTourOperatorKey"

   I have already said that the tour operator uses the same key (named MyTourOperatorKey) to sign the GetSepcialDiscountedBookingForPartners element. This provides a link between the WSS message author and the subject of the assertion. The hotel applications will simply need to verify the integrity of the assertion (by verifying the signature of the marketplace) and the signature of the tour operator. If the two signatures validate, the hotel application can be sure that the assertion is not fake and it is really asserting the author of the WSS message.

So far in this series, I have discussed four important components of XML-based security for web services: XML signatures, XML encryption, WSS, and SAML. Our discussion till now has been largely focused on one component at a time. The next article of this series will put the pieces together and demonstrate various possibilities of using them to accomplish the goal of securing web services.

Resources Check out the SAML Core (Assertions) and Bindings specifications at the main Security Services page on OASIS web site. Read the working draft of the WSS SAML Token Profile specification on Web Services Security main page also at OASIS web site. This specification dictates the use of SAML security tokens inside WSS messages. We mentioned dateTime data type. Read the official W3C Schema Datatypes specification.

---

---

2. 
   2003-08-10 23:45:50 Alejandro Montenegro
4. 
   2003-06-29 03:16:42 Mauricio Henriquez