Garrett's Tech Musings

The new Active Directory Federation Services (formerly named Geneva Server) is an extensible Secure Token Server (STS) that enables claims-based authentication. When an application requests for a user to be authenticated against AD FS, it not only expects back a valid token stating the user’s identity, but it can also specify a set of claims (user attributes) to be returned in the form of a SAML token. These claims are not stored within AD FS but instead reside in an externally configured Attribute Store.

Out of the box, AD FS provides several options for the Attribute Store: an LDAP source (such as Active Directory DS), SQL Server, or a custom store defined in a .NET library. In many situations, there may not be a single source for all of the user’s profile data (e.g., birth date, email address, phone numbers, etc.) In these situations, AD FS gives you the ability to have several stores and then determine which attribute store to use based on the claim being requested. Setting up this within AD FS (at least in the beta version) is not the most intuitive process.

Configuring Attribute Stores

The first step is to configure the attribute stores within AD FS, which is accomplished in the Attribute Stores section. An Active Directory store which points to the domain AD instance is setup by default so that’s taken care of. Next, we will need to add our secondary attribute store. When you add a new store, you will see that you have three options: Active Directory, LDAP, or SQL. For an LDAP or SQL source, you simply need to provide a connection string. For my application, I needed to access a SQL Server instance, so I just gave it a unique name and plugged in the SQL connection string.

AD FS Attribute Store

Claim Rules

Once the attribute stores have been setup, you need to setup claims rules either at the Relying Party or Identity Provider level to dictate which claims will be retrieved from which attribute store. Optionally, these claims can also be converted into another claim. Both of these tasks are accomplished using Microsoft’s new claim rule language. The syntax for defining claims transformations is sparsely documented at this point, and the only definitive source that I’ve found is on TechNet: http://technet.microsoft.com/en-us/library/dd807118%28WS.10%29.aspx.

To access the user data that’s stored in our SQL Server database, we need to write the query using a claim rule. Within the Relying Parties section, right click on the appropriate application and select “Edit Claim Rules…” Next, we will need to create an Advanced Rule since there currently isn’t a nice wizard to step us through this process. Within the rule definition window, type up your rule using syntax such as below:

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth"]
=> issue(store = "AdventureWorks Attribute Store", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth"), query = "SELECT BirthDate FROM [HumanResources].[Employee] WHERE LoginID = {0}", param = c.Value);

This isn’t an easy mechanism and hopefully Microsoft polishes this interface in future releases, but in the end, we do have claims being sourced from multiple locations, which will be very useful when developing a claims-enabled application.

When writing services that pass data between processes, it is oftentimes beneficial and wise to package the data in simple classes called DataTransferObjects (DTOs).  The database-matching Entity objects are not good choices for serialization since they may contain too much information, too little information, could be many layers deep, and expose the database structure to consuming clients.

The Assembler pattern is used to build up the DTO objects before sending results back from a method and is also responsible for reversing this process when clients pass DTOs to the service.  This build process involves mapping Entity classes to DTO classes, but there will not necessarily be a one-to-one correspondence between properties.  In either case, the process of mapping matching properties can be a laborious programming task.

Enter the AutoMapper

One option for overcoming this chore is to use generated code, which can be sufficient for exact matches but doesn’t address more complicated scenarios.  The other option is to use mapping code, and AutoMapper (http://www.codeplex.com/AutoMapper) is a CodePlex project meant to solve exactly this problem.  By default, the AutoMapper library copies property values from one class to another based on property names and also allows for more complicated mappings.

DtoAssembler

For my particular set of DTOs, the mappings were mostly one-to-one to the underlying database entities and did not require many changes.  To simplify things, I created a generic DtoAssembler class that takes two class types – TSource and TDestination – as the input and output types for the mappings.  Next, we simply create a map using the CreateMap static method and then call the Map to perform the conversion.

using AutoMapper;

public static class DtoAssembler<TSource, TDestination>
{
        public static void MapObject(TSource entity, TDestination destination)
        {
            Mapper.CreateMap<TSource, TDestination>();
            Mapper.Map<TSource, TDestination>(entity, destination);
        }

        public static TDestination MapObject(TSource entity)
        {
            Mapper.CreateMap<TSource, TDestination>();

            TDestination dto = Mapper.Map<TSource, TDestination>(entity);

            return dto;
        }

        public static List<TDestination> MapList(List<TSource> entities)
        {
            List<TDestination> dtoList = new List<TDestination>();

            foreach (TSource entity in entities)
            {
                dtoList.Add(MapObject(entity));
            }

            return dtoList;
        }
}

From within the service code, the call is as simple as this to create the DTO:

TeamDto teamDto = DtoAssembler<TeamEntity, TeamDto>.MapObject(team);

As you can see, creating a simple DTO mapping can be greatly simplified by using the AutoMapper. For more complicated mapping scenarios, take a look at the AutoMapper documentation for examples.

One aspect of using WCF services that took a little bit of time to figure out is the lifespan of the service connection.  Unlike standard web services in .NET, the connection to a WCF service is only closed when the Close method is explicitly called or the service proxy object is disposed.  In the latter case, the normal practice would be to wrap the object in a using statement as below:

using (EmailServiceClient svc = new EmailServiceClient())
{
   svc.SendEmail(fromAddress, fromName, toEmail, toName, message);
}

However, there are problems with the how the Dispose method was implemented that could cause an exception to be thrown and not properly caught as described in this MSDN article: http://msdn.microsoft.com/en-us/library/aa355056.aspx.  Therefore, the best practices dictates that Close is called explicitly and the operations are wrapped in a try/catch block:

EmailServiceClient svc = null;
try
{
   svc = new EmailServiceClient();
   svc.SendMail(fromAddress, fromName, toEmail, toName, message);
   svc.Close();
}
catch (CommunicationException e)
{
   svc.Abort();
}
catch (TimeoutException e)
{
   svc.Abort();
}
catch (Exception e)
{
   svc.Abort();
   throw;
}

Since this is fairly lengthy to write for every service call, I instead added a wrapper class (based on code found in this blog: http://bloggingabout.net/blogs/erwyn/archive/2006/12/09/WCF-Service-Proxy-Helper.aspx).

public class ServiceProxyHelper<TProxy, TChannel> : IDisposable
    where TProxy : ClientBase<TChannel>, new()
    where TChannel : class
{
    ///
    /// Private instance of the WCF service proxy.
    ///
    private TProxy _proxy;

    ///
    /// Gets the WCF service proxy wrapped by this instance.
    ///
    public TProxy Proxy
    {
        get
        {
            if (_proxy != null)
            {
                return _proxy;
            }
            else
            {
                throw new ObjectDisposedException("ServiceProxyHelper");
            }
        }
    }

    public TChannel Channel { get; private set; }

    ///
    /// Constructs an instance.
    ///
    public ServiceProxyHelper()
    {
        _proxy = new TProxy();
    }

    ///
    /// Disposes of this instance.
    ///
    public void Dispose()
    {
        try
        {
            if (_proxy != null)
            {
                if (_proxy.State != CommunicationState.Faulted)
                {
                    _proxy.Close();
                }
                else
                {
                    _proxy.Abort();
                }
            }
        }
        catch (CommunicationException)
        {
            _proxy.Abort();
        }
        catch (TimeoutException)
        {
            _proxy.Abort();
        }
        catch (Exception)
        {
            _proxy.Abort();
            throw;
        }
        finally
        {
            _proxy = null;
        }
    }

The new calls to our service now look like this:

using (ServiceProxyHelper<EmailServiceClient, EmailService> svc =
   new ServiceProxyHelper<EmailServiceClient, EmailService>())
{
   svc.Proxy.SendMail(fromAddress, fromName, toEmail, toName, message);
}

When using Visual Studio’s handy Add Service Reference wizard to add a new WCF service to your project, the dialog box allows you to define the namespace of the generated proxy code, which includes the method definitions and the data contracts.  While this is good for most cases, there are some instances where more flexibility in setting the namespace is desired.

I ran into a situation where there were several services using a common library of data classes.  However, the proxy classes generated for each service included separate instances of the same class (in this case, ParticipantDto) in different namespaces.  So instead of having the same class, the client application treated them as GoalService.ParticipantDto, UserService.ParticipantDto, etc.

Service Utility (SVCUTIL) to the Rescue

At the heart of the Add Service Reference Wizard is the SVCUTIL command line program, which has several options not exposed through Visual Studio.  To solve our divergent namespace issue, SVCUTIL includes a /namespace option that allows you to specify how to map a contract namespace to the generated .NET proxy namespace.

Therefore, the first key is setting the Namespace attribute in the DataContract attributes:

namespace Example.Business.DataTransferObjects
{
    [DataContract(Namespace= http://schemas.example.com/Services/2009/09")]
    public class ParticipantDto
    {
       …

Now that the namespace has been established, you can create a batch script as defined at http://stackoverflow.com/questions/889621/adding-service-references-to-multiple-wcf-services-that-shared-classes.  This script will execute SVCUTIL against the set of services that share a common set of classes.

@ECHO OFF
SET cmd=C:"Program Files""Microsoft SDKs"\Windows\v6.0a\bin\SvcUtil.exe
SET cmd=%cmd% /out:ProxyClass.cs /collectionType:System.Collections.Generic.List`1
SET cmd=%cmd% /config:Proxy.config
SET cmd=%cmd% /serializable
SET cmd=%cmd% /serializer:DataContractSerializer 

REM ######### Service namespace mappings (Service Contracts and Message Contracts)
SET cmd=%cmd% /namespace:"http://services.example.com/Services/2009/09"
SET cmd=%cmd%,"Example.Business.Services"

REM ######### Schema namespace mappings (Data Contracts)
SET cmd=%cmd% /namespace:"http://schemas.example.com/Services/2009/09"
SET cmd=%cmd%,"Example.Business.DataTransferObjects"

REM ######### Set all the URLs that have common types
SET cmd=%cmd% http://localhost/GoalsService/GoalService.svc
SET cmd=%cmd% http://localhost/UserService/UserService.svc
SET cmd=%cmd% http://localhost/EmailService/EmailService.svc

%cmd%

PAUSE

The newly generated proxy code will contain two namespaces – one for the data contracts (Example.Business.DataTransferObjects) and one for the services (Example.Business.Services).  Therefore not only does this solve our divergent namespace issue, but it also provides a cleaner separation between the service methods and the data classes.

While Data Transfer Objects (DTOs) are meant to be simple data containers with no functionality, there may be cases where you would like to add some simple business logic or data formatting within your classes that doesn’t require a call across the network using a service method.

For instance, let’s say we have a User DTO class that contains a property with the person’s height in inches.  If we would like to add some code to compute the person’s height in feet and inches (e.g., 5 feet, 11 inches), it would be nice to add this within the DTO class itself.

Since the generated proxy code uses partial classes, we have a fairly simple solution.  Within our client application, we can add on to the class using the “partial” keyword and then include any additional logic that we need to perform.  Be sure not to make this too complicated since any complex business logic should be done within the business layer, but this is an easy way to implement data formatting or simple computations.

namespace Example.Business.DataTransferObjects
{
    public partial class UserDto
    {
        public int HeightFeet
        {
            get
            {
                return this.CurrentHeight / 12;
            }
        }

        public int HeightInches
        {
            get
            {
                return this.CurrentHeight % 12;
            }
        }
    }
}