SAML and WS-Security | Web Services Security

During the early part of 2002, when SAML and WS-Security were receiving a lot of press attention, it was commonplace for journalists to write articles with a “WS-Security vs. SAML” theme. This was misleading because WS-Security and SAML solve different problems: SAML explains how security assertions may be expressed in XML format, whereas WS-Security explains how security information is contained in SOAP messages.

The WS-Security Profile for XML-based Tokens, published in August 2002, explains how SAML information is enclosed inside SOAP messages. A “SOAP binding” for SAML was lacking in the SAML 1.0 specification, so this is now provided by WS-Security.

The following code listing explains how a SAML v1.0 assertion is contained within a SOAP message:

<?xml version="1.0" encoding="utf-8"?> <S:Envelope xmlns:S="http://www.w3.org/2001/12/soap-envelope"             xmlns:ds="http://www.w3.org/2000/09/xmldsig#"             xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/04/secext">     <S:Header>         <wsse:Security>             <saml:Assertion                       MajorVersion="1"                       MinorVersion="0"                       Assertion                       Issuer="CompanyX"                       IssueInstant="2002-07-23T11:32:05.6228146-07:00"                     xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">                 ...             </saml:Assertion>             ...         </wsse:Security>     </S:Header>     <S:Body>     </S:Body> </S:Envelope>

The SAML assertion is contained within a Security block, which is contained inside the SOAP header. A SAML assertion may be digitally signed or encrypted, in a similar manner to how other security tokens may be signed and encrypted using WS-Security. The processing of a SAML assertion, contained in a WS-Security formatted SOAP message, should not be different from the processing of any other type of security token expressed using WS-Security.

Code Example: Using the Microsoft WSE

The Microsoft WSE is a downloadable tool that allows Visual Studio .NET developers to build Web Services applications that make use of technologies such as WS-Security. It is available at the following URL: http://msdn.microsoft.com/webservices/building/wse.

The code examples provided with the Microsoft WSE make use of C# as their programming language. The .NET Common Language Framework (CLR) is used.

Let’s look at a code example for the creation of a SOAP message containing a digital signature and an X.509 digital certificate.

First, the security and XML processing functionality from the .NET platform is required for this program, so the following code pulls in the required packages:

using System; using System.Collections; using System.ComponentModel; using System.Windows.Forms; using System.Security.Cryptography; using System.Text; using Microsoft.Web.Services; using Microsoft.Web.Services.Security; using Microsoft.Web.Services.Security.X509; using Microsoft.Web.Services.QuickStart.X509;

Let’s look at code that calls a Web Service that adds two numbers, similar to the Web Service we encountered in Chapter 3. This code is based on an example provided with the WSE in the \Samples\QuickStart\Clients\X509Signing\ folder.

// Instantiate an instance of the web service proxy AddNumbers serviceProxy = new AddNumbers(); SoapContext requestContext = serviceProxy.RequestSoapContext; // Configure the proxy ConfigureProxy(serviceProxy); // Get our security token X509SecurityToken token = GetSecurityToken(); if (token == null)  throw new ApplicationException("No key provided for signature."); // Add the signature element to a security section on the request // to sign the request requestContext.Security.Tokens.Add(token); requestContext.Security.Elements.Add(new Signature(token)); // Call the service Console.WriteLine("Calling {0}", serviceProxy.Url); int sum = serviceProxy.AddInt(a, b);

You can see that the WS-Security model is reflected in the preceding code listing. An X.509 security token is requested and then a digital signature is added to the SOAP message, referencing this X.509 token. The code to request the X.509 certificate is shown here:

public X509SecurityToken GetSecurityToken() {   X509SecurityToken securityToken;   // open the current user's certificate store   // X509CertificateStore store =      X509CertificateStore.CurrentUserStore(X509CertificateStore.MyStore);   bool open = store.OpenRead();   try   {     // Open a dialog to allow user to select the certificate to use     //     StoreDialog dialog = new StoreDialog(store);     Microsoft.Web.Services.Security.X509.X509Certificate cert = null;     cert = dialog.SelectCertificate(IntPtr.Zero, "Select     Certificate", "Choose a Certificate below for signing.");     if (cert == null)     {       throw new ApplicationException("You chose not to select an X509       certificate for signing your messages.");     }     else if (!cert.SupportsDigitalSignature || !cert.key == null)     {       throw new ApplicationException("The certificate must support digital       signatures and have a private key available.");     }     else     {       securityToken = new X509SecurityToken(cert);     }     }     finally     {       if (store != null) { store.Close(); }     }     return securityToken;   } } }

A dialog box is used to ask the user to choose which certificate they will employ from their local certificate store. The StoreDialog object is used for this purpose. An X509Certificate object is used to load the certificate, and it is checked to ensure that it supports the use of a digital signature, and that the corresponding private key is available. As we know from Chapter 2, it is the private key that is used to produce a digital signature, and the corresponding public key may be enclosed with the signature in the message. Providing the private key is available, the X.509 certificate is loaded into an X509SecurityToken object and returned.

As you can see from the code listings, the use of WS-Security does not presuppose any knowledge of the structure of the SOAP messages that are created. However, it is important to understand the model and abstractions of WS-Security—the use of tokens and the signing and encryption of these tokens, as well as other data in the SOAP message. The .NET platform allows the developer to take advantage of the power of these abstractions without the requirement to delve into the XML itself.