Web Services Security, Part 3

May 13, 2003

Bilal Siddiqui

In the first article of this series, I explained why traditional network firewalls are inadequate to provide security to web service applications, which is why we need to implement web service security at the XML messaging layer.

In the second article, I discussed signed and encrypted XML messages and a B2B scenario to elaborate the application of XML signature and encryption in web services. At the end of the second article, I introduced Web Services Security (WSS) and explained how WSS applies XML signature and XML encryption to SOAP messages. I also introduced the concept of security tokens and demonstrated the use of digital certificates as security tokens in WSS messages.

In this article I discuss XML-based authentication and the sharing of authentication information across different applications, known as Single Sign-On (SSO). The Security Assertions Markup Language (SAML, often pronounced "sam-ull") from OASIS helps reach this goal by wrapping authentication information in an XML format.

What is Authentication?

For our purposes, authentication means verifying the identity of a user. When you check your e-mail, you enter your username and password to get authenticated. It is assumed that you have kept your password confidential. Therefore the knowledge of your password is used to make sure that you are the one who is trying to check your email.

Similarly, in the second article I demonstrated the use of certificates as authentication tokens. Recall from Listing 9 of the second article that an X509 certificate was wrapped within the SOAP header of the GetSepcialDiscountedBookingForPartners method call. The certificate was actually a security token (just like a password) that the recipient of the WSS message can use in order to authenticate the user before allowing specially discounted rates for booking.

Sharing of Authentication Information

A security token is presented to a gatekeeper in order for a user to get authenticated. Now imagine that the gatekeeper is guarding the main gate of a large building with many offices. Visitors are required to show their ID cards and get authenticated at the main gate. The gatekeeper checks the ID card by matching it with his internal record and then allows the visitor to enter the building.

Let's suppose that you want to visit several offices in the building. Each office has an entrance with a gatekeeper guarding the entrance of each office. You need to get authenticated at the entrance of each office. The gatekeeper at the entrance of each office repeats the same authentication act.

What if individual offices in the building trust the authentication performed by the gatekeeper of the main gate? The building will become a trusted domain, of which each individual office will be a part. Naturally if this type of trust exists between different offices, they would like to share the processing load of the authentication act.

A possible solution to allow sharing of authentication information is to issue a temporary identification badge to a visitor at the main gate of the building. The gatekeeper at the main gate will issue a badge to each visitor after successful authentication. The identification badge will have a short expiry. The visitor will show the identification badge while entering each office. The office gatekeeper will check the validity of badge before allowing or disallowing a person to enter the office.

Such scenarios are common in Enterprise Application Integration and B2B applications. Whether applications are running within or across the boundaries of an enterprise, the sharing of authentication information forms an important part of application integration effort. Naturally, the sharing of authentication information prevents each application from having to perform the entire authentication process.

A B2B Application Scenario

Let's suppose that the hotel and tour operator enterprises that we introduced earlier in this series of articles are part of an electronic marketplace. The marketplace provides the basic B2B and B2C enabling framework, and different enterprises as well as final customers (e.g. tourists) use the framework to do business on the electronic marketplace. As part of the enabling framework, the marketplace provides financial services by maintaining relations with financial institutions. The marketplace issues its own credit cards and credit limits, while customers and enterprises can open their accounts with the marketplace and can perform monetary transactions.

As a result of providing financial services, the marketplace is in a position to issue assertions about different enterprises doing business on the marketplace. In this marketplace context, we will assume the following:

• The hotel and tour operator businesses are trusted business partners of the marketplace.
• The hotel and the tour operator are new to each other (i.e. they have no relationship of trust with each other).
• The tour operator wants to enjoy the specially discounted rates that the hotel offers.

So the tour operator will ask the marketplace to issue an identification and security badge (an assertion) stating that the tour operator is a trusted business partner of the marketplace. Once the tour operator gets the assertion, it will present it to the hotel and ask them to let it enjoy the specially discounted rates.

SAML is an XML vocabulary that defines the syntax necessary to exchange authentication information between applications. The authentication information is exchanged in the form of assertions. The marketplace is responsible to provide assertions about its trusted business partners and therefore acts as an SAML assertion authority.

The tour operator application will request an assertion from the marketplace (a SAML authority). The tour operator is a requester application and the subject of the assertion as well. After getting the assertion from the marketplace, the tour operator will wrap the assertion in a WSS message and send the WSS message to the hotel application. The hotel will rely on the assertion to decide whether to allow the tour operator the special discount or not. The hotel is a relying party.

The rest of the article discusses how all this is accomplished using SAML and WSS.

We have three areas to explain and demonstrate.

1. The syntax of a SAML assertion.
2. How an application will request an SAML authority for the issuance of an SAML assertion.
3. Using SAML assertions in WSS applications.

The Syntax of a SAML Assertion

Take a look at Listing 1. It wraps an authentication statement in the format of an SAML assertion. An authentication statement specifies the outcome of an act of authentication which took place in the past. The marketplace (an SAML authority) authenticates a user and issues the security badge (an assertion).

At this point, we are not concerned with the actual process of authentication that took place prior to issuing the assertion. The authentication process is a private issue for the marketplace and may be comprised of one of several methods: for example, a simple username password authentication that you use while checking email or the certificate-based WSS authentication that we demonstrated in Listing 9 of the second article.

However it is important that all applications relying on the SAML assertion issued by the marketplace trust the authentication process. That's why it will contain information regarding the means which were used to authenticate the user.

The assertion from Listing 1 can be stated in English thus:

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.

Here's an explanation of the XML format of Listing 1. The root Assertion element wraps three important bits of information: a Conditions element, an AuthenticationStatement element, and a ds:Signature element.

The Conditions element specifies two conditions for this assertion. The NotBefore attribute tells the time before which the assertion is not valid. Similarly, the NotOnOrAfter attribute specifies the time after which the assertion expires. (Both times are of dateTime data type according to the W3C Schema Datatypes specification.)

The AuthenticationStatement states the outcome (the final result) of an authentication process.The other two elements (Conditions and ds:Signature) are included for helper tasks.

Look at the AuthenticationStatement structure in Listing 1. It contains two attributes and one child element. The first attribute of the element is AuthenticationMethod. The value of this attribute that we have used in Listing 1 (urn:ietf:rfc:3075) specifies that we used XML signatures to authenticate the subject. The SAML specification defines identifiers for several authentication methods (refer to section 7 of the SAML core specification for a list of available authentication methods). The second attribute (AuthenticationInstant) specifies the instant of time when the authentication took place.

The only child element is an element named Subject, identifying the subject of this assertion. In our case, the tour operator is the subject. The Subject element contains two child elements, a NameIdentifier element and a SubjectConfirmation element.

The NameIdentifier element specifies the name of the subject. In addition to the name, we can optionally specify a name qualifier as value of the NameQualifer attribute. The concept of name qualifiers allows multiple username issuing authorities to work without causing any duplication. Each authority will issue names with its own name qualifier. This concept is similar to the concept of XML namespaces, in which each namespace has its own set of elements and two namespaces can have the same element name without producing any ambiguity.

Now look at the SubjectConfirmation element, which specifies the relationship between the subject of an assertion and the author of the message that contains the assertion. Listing 1 is just an assertion. The last section of this article will demonstrate how to wrap this assertion in a WSS message. For the moment, just note that the tour operator is the subject of this assertion and the tour operator itself will eventually author the WSS message to request specially discounted booking rates from the hotel. Therefore, we are interested in the simple case when the subject and the author of the message are the same.

In order to specify that the subject of an assertion and the author of the message that contains the assertion are the same, the SubjectConfirmation element includes two elements. The first is a ConfirmationMethod element and the second is a ds:KeyInfo element. The two elements form a pair inside the SubjectConfirmation element.

The ConfirmationMethod element specifies a method that the hotel (a relying party) will use to confirm the relationship between the subject of the assertion and the author of the message that contains the assertion. Look at the content of the ConfirmationMethod element. It is a string which says urn:oasis:names:tc:SAML:1.0:cm:holder-of-key; it identifies a method known as "holder of key", which means that the subject is the owner of a cryptographic key (e.g. a public key). The key is either included in or referenced from the accompanying ds:KeyInfo element. The ds:KeyInfo element wraps a key named "MyTourOperatorKey".

If the author of a message that contains an assertion can prove that it owns this key, then the relying party can be sure that the author is really the subject of the assertion.

The last section of this article will demonstrate one possible way for the tour operator to prove that it owns the public key named "MyTourOperator".

We have discussed all elements of Listing 1, except the last child of the root Assertion element, which is a ds:Signature element. As readers might have already guessed, this element is actually the signature of the assertion authority (the marketplace). The purpose of including the signature of the issuing authority is to allow the recipient of the assertion to verify that the assertion is not fake.

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.