• How different user credentials are mapped to a set of claims that are attached to the security context for each request.
• How to access those claims through the AuthorizationContext to perform authorization, in lieu of role-based security checks.
• How to create a custom authorization policy to issue a set of normalized claims for any credential, and attach those claims to the AuthorizationContext for later authorization checks.

Part 1 introduces some of the benefits of a claims-based security model. Specifically, that it enables service developers to focus on application-specific claims to authorize calls to each operation, while decoupling the authentication step and removing dependencies on specific credential types. This model also allows applications to support more than one credential type by mapping authenticated callers to a set of normalized claims.

In this article I will discuss other design decisions related to the claims-based security model. I’ll walk through the process for creating a set of claims-based utilities to encapsulate claims authorization at the service tier; and explain how SAML tokens can be issued by a security token service for authentication, supplying normalized claims to the security context.

Claims-Based Permission Demands

When you work with a traditional role-based security model, as I discussed in Part 1 of this article, you often apply role-based permission demands at the service operation to authorize calls. For services that may authorize both Windows and custom username and password credentials, you can stack permission demands as shown here – for each of the supported roles at an operation:

[PrincipalPermission(SecurityAction.Demand,
Role="BUILTIN\\Administrators")]
[PrincipalPermission(SecurityAction.Demand,
Role="Administrators")]
public string AdminOperation()
{
  // protected code
}

Permission demands implemented with the PrincipalPermission or PrincipalPermissionAttribute rely on the security principal attached to the executing thread to authorize calls. The most common check is to require specific roles through the IsInRole() function exposed by the IPrincipal type. This model for authorizing access to operations is easy to work with, and familiar, but an equivalent set of claims-based principal and principal permission types do not exist. In this section, I will describe a set of claims-based utilities I created to implement this familiar model around claims. It includes the following custom types:

• ClaimsPrincipal
• ClaimsPrincipalPermission
• ClaimsPrincipalPermissionAttribute

ClaimsPrincipal

In Part 1 I showed you how to use a custom authorization policy to map a UserName credential to a set of application claims to be attached to the AuthorizationContext. Custom authorization policies are also responsible for providing a security principal for the request thread, in the form of an IPrincipal type. The custom authorization policy from Part 1 extracted the identity of the caller from the EvaluationContext, mapped that caller to a set of claims to be used for authorization, and created a simple GenericPrincipal with the identity and no roles. This work is done in the Evaluate() function of the custom authorization policy, as shown here:

public bool Evaluate(EvaluationContext evaluationContext, ref object state)
{
  if (evaluationContext.Properties.ContainsKey("Identities"))
  {
    List<IIdentity> identities =
evaluationContext.Properties["Identities"] as List<IIdentity>;
    IIdentity identity = identities[0];

    ClaimSet claims = MapClaims(identity);

    GenericPrincipal newPrincipal = new GenericPrincipal(identity, null);
    evaluationContext.Properties["Principal"] = newPrincipal;

    if (claims!=null)
      evaluationContext.AddClaimSet(this, claims);

    return true;
  }
  else
    return false;
}

Supplying a security principal is merely a formality in this case – since authorization is performed directly against the custom claim set added to the AuthorizationContext via AddClaimSet(). Assuming claims are assigned according to those discussed in Part 1, the following code looks for a claim set issued by http://www.thatindigogirl.com/samples/2006/06/issuer in the AuthorizationContext. In this example, the code checks that the claim set contains the “delete” claim for the “customers” resource:

public void DeleteCustomer(string customerId)
{
  AuthorizationContext authContext =
ServiceSecurityContext.Current.AuthorizationContext;

  ClaimSet issuerClaimSet = null;
  foreach (ClaimSet cs in authContext.ClaimSets)
  {
    Claim issuerClaim =
Claim.CreateNameClaim("http://www.thatindigogirl.com
/samples/2006/06/issuer");

    if (cs.Issuer.ContainsClaim(issuerClaim))
      issuerClaimSet=cs;
  }

  if (issuerClaimSet==null)
    throw new SecurityException("Access is denied. No claims were
provided from the expected issuer.");

  Claim c = new Claim("http://schemas.thatindigogirl.com
/samples/2006/06/identity/claims/delete",
"http://schemas.thatindigogirl.com/samples/2006/06/identity
/resources/customers", Rights.PossessProperty);

  if (!issuerClaimSet.ContainsClaim(c))
    throw new SecurityException("Access is denied. Required claims not
satisfied.");

  // delete customer
}

Implementing IClaimsPrincipal and ClaimsPrincipal

The first step in creating a first class claims-based model is to create a custom ClaimsPrincipal type for the request thread – to encapsulate the set of claims that authorization will be performed against. As you know, the security principal must implement IPrincipal which includes an Identity property and an IsInRole() method. To support the claims-based approach I created an IClaimsPrincipal interface which has the following definition:

public interface IClaimsPrincipal
{
  ClaimSet Claims {get;}
  ClaimSet Issuer {get;}

  bool HasRequiredClaims(ClaimSet requiredClaims);
}

As you would expect from a claims-based approach, a security principal implementing this interface provides access to the applicable claim set for authorization, the issuer of that claim set, and has a function to check that a set of required claims have been supplied. In my ClaimsPrincipal type I implement both IPrincipal and IClaimsPrincipal as shown in Listing 1.

Listing 1: Implementation of the ClaimsPrincipal type

using System;
using System.Collections.Generic;
using System.Text;
using System.Security.Principal;
using System.IdentityModel.Claims;

public class ClaimsPrincipal : IClaimsPrincipal, IPrincipal
{
  private ClaimSet m_claims;
  private IIdentity m_identity;

  public ClaimsPrincipal(IIdentity identity, ClaimSet claims)
  {
    this.m_identity = identity;
    this.m_claims = claims;
  }

  ClaimSet IClaimsPrincipal.Issuer
  {
    get { return this.m_claims.Issuer; }
  }

  bool IClaimsPrincipal.HasRequiredClaims(ClaimSet requiredClaims)
  {
    bool hasClaims = true;
    bool issuerMatch = false;

    // check issuer
    foreach (Claim c in requiredClaims.Issuer)
    {
      if (this.m_claims.Issuer.ContainsClaim(c))
      {
        issuerMatch=true;
        break;
      }
    }

    // check required claims
    if (issuerMatch)
    {
      foreach (Claim c in requiredClaims)
      {
        if (!this.m_claims.ContainsClaim(c))
        {
          hasClaims = false;
          break;
        }
      }
    }

    return issuerMatch && hasClaims;
  }

  ClaimSet IClaimsPrincipal.Claims
  {
    get { return this.m_claims; }
  }

  IIdentity IPrincipal.Identity
  {
    get
    {
      return this.m_identity;
    }
  }

  bool IPrincipal.IsInRole(string role)
  {
    throw new NotSupportedException("ClaimsPrincipal does not
implement role-based security checks.");
  }

}

The constructor takes an IIdentity type and a ClaimSet representative of the claims to authorize. In the implementation of IPrincipal, the Identity property returns this identity reference, but the IsInRole() function throws an exception since we’re not expecting any role-based checks when using claims-based security. The implementation of IClaimsPrincipal returns the associated ClaimSet from the Claims property, returns the issuer’s ClaimSet for the Issuer property, and performs a check for the correct issuer and claim set in the HasRequiredClaims() method.

Attaching the ClaimsPrincipal Instance

This ClaimsPrincipal type can be constructed in the custom authorization policy instead of the GenericPrincipal shown earlier. The same claim set that is being added to the EvaluationContext should also be passed to the ClaimsPrincipal when it is constructed, as shown here in this updated Evaluate() method:

public bool Evaluate(EvaluationContext evaluationContext,
ref object state)
{

  if (evaluationContext.Properties.ContainsKey("Identities"))
  {
    List<IIdentity> identities =
evaluationContext.Properties["Identities"] as List<IIdentity>;
    IIdentity identity = identities[0];

    ClaimSet claims = MapClaims(identity);

    ClaimsPrincipal newPrincipal =
new ClaimsPrincipal(identity, claims);
    evaluationContext.Properties["Principal"] = newPrincipal;

    evaluationContext.AddClaimSet(this, claims);

    return true;
  }
  else
    return false;
}

Validating ClaimsPrincipal Claims

This removes the need to traverse the AuthorizationContext for the correct issuer. Instead, you can retrieve the security principal attached to the thread, check that it implements IClaimsPrincipal, and validate that the required claims were provided:

IClaimsPrincipal claimsPrincipal = Thread.CurrentPrincipal
as IClaimsPrincipal;

if (claimsPrincipal == null)
  throw new SecurityException("Access is denied. Security principal
should be a IClaimsPrincipal type.");

Claim issuerName = Claim.CreateNameClaim(
ClaimsAuthorizationPolicy.IssuerName);
List<Claim> issuerClaims = new List<Claim>();
issuerClaims.Add(issuerName);

List<Claim> requiredClaims = new List<Claim>();
requiredClaims.Add(new Claim(�http://schemas.thatindigogirl.com
/samples/2006/06/identity/claims/delete�,
�http://schemas.thatindigogirl.com/samples/2006/06/identity
/resources/customers�, Rights.PossessProperty));

DefaultClaimSet claimSet = new DefaultClaimSet(
new DefaultClaimSet(issuerClaims), requiredClaims);

if (!claimsPrincipal.HasRequiredClaims(claimSet))
  throw new SecurityException("Access is denied. Security principal
does not satisfy required claims.");

HasRequiredClaims() expects you to pass a ClaimSet that includes the required claims with the correct issuer. Clearly, this still adds bloat to your code, but it can be simplified by using the ClaimsPrincipalPermission type that I’ll explain next.

ClaimsPrincipalPermission

You can perform permission demands in code to enforce role-based security using the following syntax:

PrincipalPermission p = new PrincipalPermission(null,
"Administrators", true);
p.Demand();

The PrincipalPermission type is passed a username, role and authentication status. When the permission demand is invoked the security principal attached to the request thread is checked against these values – in this case the user name is null, thus not checked, but the user must be in the “Administrators” role and be authenticated. I created a custom ClaimsPrincipalPermission to facilitate similar demands for claims.

Like with the PrincipalPermission type, the ClaimsPrincipalPermission implements IPermission, ISecurityEncodable and IUnrestrictedPermission. These interfaces are shown here:

public interface IPermission : ISecurityEncodable
{
  void Demand();

  IPermission Copy();
  IPermission Intersect(IPermission target);
  bool IsSubsetOf(IPermission target);
  IPermission Union(IPermission target);
}

public interface ISecurityEncodable
{
  void FromXml(SecurityElement e);
  SecurityElement ToXml();
}

public interface IUnrestrictedPermission
{
  bool IsUnrestricted();
}

In the following paragraphs I will discuss the implementation of the ClaimsPrincipalPermission type, including each of these methods that are common to all IPrincipal types.

Constructing ClaimPrincipalPermission

The implementation of Demand() is where all the work is done to check the security principal attached to the current thread and ensure that the requirements held by the ClaimPrincipalPermission are met. That implies that the ClaimsPrincipalPermission must supply overloaded constructors to provide information for the permission demand. ClaimsPrincipalPermission issues demands based on the following properties:

• IsAuthenticated: Since ClaimsPrincipal still carries information about the identity of the caller, you can validate that the caller has been authenticated by providing a value for this property.
• RequiredClaims: This is a ClaimSet which contains the list of required claims to be demanded, and information about the issuer of those claims.
• Issuer: This is a ClaimSet identifying the issuer of the required claims.

The ClaimsPrincipalPermission constructor takes a boolean and ClaimSet to populate these properties as follows:

// fields
private ClaimSet m_requiredClaims;
private bool m_isAuthenticated;

// properties
public bool IsAuthenticated
{
  get
  {
    return m_isAuthenticated;
  }
}

public ClaimSet Issuer
{
  get
  {
    return ((this.m_requiredClaims==null)?null :
this.m_requiredClaims.Issuer);
  }
}

public ClaimSet RequiredClaims
{
  get
  {
    return this.m_requiredClaims;
  }
}

// constructor
public ClaimsPrincipalPermission(bool isAuthenticated,
ClaimSet requiredClaims)
{
  this.m_isAuthenticated = isAuthenticated;
  this.m_requiredClaims=requiredClaims;
}

Once you have constructed the ClaimsPrincipalPermission type, you can use it to perform permission demands.

Another constructor is also supplied allowing the ClaimsPrincipalPermission to be initialized as restricted or unrestricted, according to the PermissionState enumeration.

private bool m_isUnrestricted;

public ClaimsPrincipalPermission(PermissionState state)
{
  this.m_isUnrestricted = (state == PermissionState.Unrestricted);
}

This value returned by the IsUnrestricted property of the IUnrestrictedPermission interface.

Demand()

Permission demands use the properties of the IPermission type to check the security principal attached to the thread for specified requirements. The implementation of Demand() for ClaimsPrincipalPermission executes the following checks:

• It checks to see that the security principal attached to the thread is an IClaimsPrincipal type, and throws a SecurityException if it is not.
• If the IsAuthenticated property is set to true, it checks to see that the current principal is authenticated.
• If the RequiredClaims property is null, it does not check any further, and the demand is complete, otherwise, the requirements for issuer and claims are verified as discussed next.
• The Issuer is checked next. When the RequiredClaims property is set, a ClaimSet is provided which includes a ClaimSet for the Issuer. The assumption here is that the developer has provided one or more identifying claims about the required Issuer. If one of these claims is matched by the Issuer of the security principal’s claims, then we have a match.
• Once an Issuer match is verified the list of required claims are checked. All required claims must be present in the RequiredClaims ClaimSet, or the demand fails.

The code to execute these checks begins with the Demand() implementation, which then calls to a shared CheckClaims() method, which then calls to the ClaimsPrincipal’s HasRequiredClaims() method (shown in Listing 1). The Demand() and CheckClaims() methods are shown in Listing 2.

Listing 2: Demand() and CheckClaims() functions from ClaimsPrincipalPermission

public void Demand()
{
  IClaimsPrincipal p = Thread.CurrentPrincipal as IClaimsPrincipal;

  if (p == null)
    throw new SecurityException("Access is denied. Security principal
should be a IClaimSetPrincipal type.");

  this.CheckClaims(p);
}

public void CheckClaims(IClaimsPrincipal principal)
{
  IPrincipal p = principal as IPrincipal;

  if (this.m_isAuthenticated && !p.Identity.IsAuthenticated)
  {
    throw new SecurityException("Access is denied. Security principal
is not authenticated.");
  }

  if (this.m_requiredClaims==null)
  {
    return;
  }

  if (!principal.HasRequiredClaims(this.m_requiredClaims))
    throw new SecurityException("Access is denied. Security principal
does not satisfy required claims.");

}

Now I will discuss other members of IPermission implemented by ClaimsPrincipalPermission – specifically Copy(), Intersect(), IsSubsetOf() and Union() – used to facilitate the generation of new permission objects or permission comparison.

Copy()

Copy() is the simplest IPermission function. It requires only that you clone the current permission object as shown here:

public IPermission Copy()
{
  if (this.IsUnrestricted())
    return new
ClaimsPrincipalPermission(PermissionState.Unrestricted);
  else
    return new ClaimsPrincipalPermission(this.m_isAuthenticated,
this.m_requiredClaims);
}

If the permission was constructed as unrestricted, values for IsAuthenticated and RequiredClaims take on their defaults.

Intersect()

Intersect() returns a new permission object that represents the intersection of two permissions. In the ClaimsPrincipalPermission, this is implemented in the following manner:

• If the permission to intersect with is null, null is returned.
• If the permission to intersect with is not a ClaimsPrincipalPermission type, null is returned.
• If either the permission to intersect or this permission is unrestricted, return a copy of the opposite permission.
• If IsAuthenticated does not match for both permissions, null is returned.
• If ALL of the Issuer claims are not matched, null is returned. The assumption here is that a developer is providing another permission to intersect with, and they should thus describe the Issuer with the same set of claims. This simplifies how developers can use these permissions, by reducing the complexity that would follow if you attempted to intersect the ClaimSet of an Issuer, and the Issuer’s Issuer, and that Issuer’s Issuer, and so on. In other words, the nature of the ClaimSet and the nested Issuer claim sets demands simplicity here.
• Once the Issuer ClaimSet is verified as a perfect match between permissions, the actual claim sets can be intersected. So long as they are issued by the same Issuer, the list of required claim sets in both permissions can be intersected to produce a new ClaimSet by the same Issuer.

The resulting code is shown in Listing 3.

Listing 3: Implementation of Intersect() and IsExactIssuerMatch()

public IPermission Intersect(IPermission target)
{
  if (target == null)
    return null;

  ClaimsPrincipalPermission perm = target as
ClaimsPrincipalPermission;
  if (perm == null)
    return null;

  if (this.IsUnrestricted())
    return target.Copy();

  if (perm.IsUnrestricted())
    return this.Copy();

  if (this.m_isAuthenticated != perm.IsAuthenticated)
    return null;

  if (!IsExactIssuerMatch(perm.Issuer)) return null;

  List claims = new List();
  foreach (Claim c in this.m_requiredClaims)
  {
    if (perm.RequiredClaims.ContainsClaim(c))
    {
      claims.Add(c);
    }
  }

  // it is assumed that the issuers are identical from the call
  // to IsExactIssuerMatch() above
  ClaimsPrincipalPermission newPerm = new
ClaimsPrincipalPermission(this.m_isAuthenticated, new
DefaultClaimSet(this.m_requiredClaims.Issuer, claims));
  return newPerm;

}

protected bool IsExactIssuerMatch(ClaimSet target)
{
  bool issuerMatch = true;
  foreach (Claim c in target)
  {
    if (!this.m_requiredClaims.Issuer.ContainsClaim(c))
    {
      issuerMatch = false;
      break;
    }
  }
  return issuerMatch;
}

IsSubsetOf()

IsSubsetOf() returns a boolean result after checking to see if the current permission is a subset of the permission passed to the method. This method does the following:

• Returns false if the permission passed is null.
• Returns false if the permission passed is not a ClaimsPrincipalPermission type.
• Returns true if the target permission is unrestricted. Returns false if this permission is unrestricted.
• Returns false if the IsAuthenticted properties do not match.
• Returns false if the Issuer of both permissions are not an exact match.
• Finally, it checks to see if the required claims in this permission instance are all found in the permission passed to the method. If they are not all present, returns false, otherwise true.

The resulting code is shown here:

public bool IsSubsetOf(IPermission target)
{

  if (target == null)
    return false;

  ClaimsPrincipalPermission perm = target as
ClaimsPrincipalPermission;
  if (perm == null)
    return false;

  if (perm.IsUnrestricted)
    return true;

  if (this.IsUnrestricted)
    return false;

  if (this.m_isAuthenticated != perm.IsAuthenticated)
    return false;

  if (!IsExactIssuerMatch(perm.Issuer)) return false;

  bool isSubsetOf = false;
  foreach (Claim c in this.m_requiredClaims)
  {
    if (!perm.RequiredClaims.ContainsClaim(c))
    {
      isSubsetOf=false;
      break;
    }

  }

  return isSubsetOf;
}

Union ()

Union() returns a new permission type that includes all of the required claims of two permissions, assuming that they both share the same setting for IsAuthenticated and Issuer values. Similar validation on the permission passed to the method, the IsAuthenticated property and the Issuer value are executed before creating a new permission type with the entire set of claims (without duplicates). The code looks as follows:

public IPermission Union(IPermission target)
{
  if (target == null)
    return null;

  ClaimsPrincipalPermission perm = target as
ClaimsPrincipalPermission;
  if (perm == null)
    return null;

  if (perm.IsUnrestricted|| this.IsUnrestricted)
    return new
ClaimsPrincipalPermission(PermissionState.Unrestricted);

  if (this.m_isAuthenticated != perm.IsAuthenticated)
    return null;

  if (!IsExactIssuerMatch(perm.Issuer)) return null;

  List<Claim> claims = new List<Claim>();
  foreach(Claim c in this.m_requiredClaims)
    claims.Add(c);

  foreach (Claim c in perm.RequiredClaims)
  {
    if (!this.m_requiredClaims.ContainsClaim(c))
    {
      claims.Add(c);
    }
  }

  // it is assumed that the issuers are identical from the call
  // to IsExactIssuerMatch() above
  ClaimsPrincipalPermission newPerm = new
ClaimsPrincipalPermission(this.m_isAuthenticated, new
DefaultClaimSet(this.m_requiredClaims.Issuer, claims));
  return newPerm;

}

FromXml() and ToXml()

IPermission inherits ISecurityEncodable as I mentioned earlier. The job of FromXml() and ToXml() are to support XML serialization and deserialization of the permission. This is not a necessary feature for this particular permission type, thus is not implemented.

Claims-Based Demands

With this ClaimsPrincipalPermission you can now place permission demands in code, for example in each service operation, as follows:

public void DeleteCustomer(string customerId)
{

  ClaimSet issuerClaimSet = new
DefaultClaimSet(Claim.CreateNameClaim(
"http://www.thatindigogirl.com/samples/2006/06/issuer"));

  Claim claim = new Claim(
"http://schemas.thatindigogirl.com/samples/2006/06/identity/
claims/delete", "http://schemas.thatindigogirl.com/samples/2006/06/
identity/resources/customers", Rights.PossessProperty);

  ClaimSet requiredClaimSet = new
DefaultClaimSet(issuerClaimSet, claim);

  ClaimsPrincipalPermission perm = new
ClaimsPrincipalPermission(true, requiredClaimSet);

  perm.Demand();

  // code to delete customer
}

But wait – isn’t this supposed to reduce the amount of code necessary to check claims? The problem is that it isn’t as simple as passing a string array of roles, when we do claims-based security. Generating a ClaimSet is the only reliable way to initialize the ClaimsPrincipalPermission with the issuer and required claims for the demand. But, since claims are tightly related to the authorization policy at your service, you can, and should, provide utility functions to generate claim sets for the issuer, and for common claims.

If you do, you can reduce the above code to these two lines:

ClaimsPrincipalPermission perm = new ClaimsPrincipalPermission(true,
ClaimsAuthorizationPolicy.CreateCustomersClaimSet(
ClaimsAuthorizationPolicy.ClaimTypes.Delete));
perm.Demand();

The CreateCustomersClaimSet() function is a static function exposed by the custom IAuthorizationPolicy type, ClaimsAuthorizationPolicy. Inside, it leverages string constants defining ClaimTypes and Resources as discussed in Part 1 of this article, to create a ClaimSet using the authorization policy issuer. It allows you to pass a parameter array of strings indicating the ClaimTypes to be included in the ClaimSet. Internal validation ensures that strings passed to the method are actually valid ClaimTypes. The core code is shown here:

public static ClaimSet CreateApplicationClaimSet(
params string[] claimTypes)
{
  List<Claim> claims = new List<Claim>();
  foreach(string s in claimTypes)
  {
    if (!IsValidClaimType(s))
      throw new SecurityException(string.Format("Invalid claim type
provided: {0}", s));

    claims.Add(new Claim(s,
ClaimsAuthorizationPolicy.Resources.Application,
Rights.PossessProperty));
  }

  return new DefaultClaimSet(
ClaimsAuthorizationPolicy.CreateIssuerClaimSet(), claims);
}

public static ClaimSet CreateIssuerClaimSet()
{
  return new DefaultClaimSet(Claim.CreateNameClaim(
ClaimsAuthorizationPolicy.IssuerName));
}

NOTE: You can look at the code sample for this article for a similar example with a complete listing of constants and helper methods for the authorization policy.

ClaimsPrincipalPermissionAttribute

As I mentioned earlier, you can also perform permission demands declaratively using the PrincipalPermissionAttribute as follows:

[PrincipalPermission(SecurityAction.Demand,
Role="BUILTIN\\Administrators")]
[PrincipalPermission(SecurityAction.Demand,
Role="Administrators")]
public string AdminOperation()
{
  // protected code
}

Like the PrincipalPermission, the PrincipalPermissionAttribute type can be initialized with a username, role and authentication status. You also indicate you are executing a demand with the first parameter, SecurityAction.Demand. To execute the demand, the runtime asks the attribute to create an instance of the associated permission, PrincipalPermission, and its Demand() function is executed to enforce this before the operation can be invoked.

To provide a similar experience for claims-based demands, I have created a ClaimsPrincipalPermissionAttribute which I’ll describe in the next sections.

Implementing CodeAccessSecurityAttribute

As with the PrincipalPermissionAttribute type, the ClaimsPrincipalPermissionAttribute inherits CodeAccessSecurityAttribute, which in turn inherits SecurityAttribute. The base type, SecurityAttribute, supplies these key members:

• Action: This property indicates the SecurityAction to execute, which in this context is SecurityAction.Demand.
• Unrestricted: If this property is true it indicates that the caller should be granted full access to the resource protected by the associated permission, if false, no access is granted.
• CreatePermission(): Invoked by the runtime to construct the permission type associated with the CodeAccessSecurityAttribute, in order to execute the permission demand.

The idea is to provide appropriate public properties on this custom attribute to so that the associated permission type can be constructed with values that can be used for permission demands. The base type for the attribute, CodeAccessSecurityAttribute, provides a constructor that takes the PermissionState enumeration setting the restricted state of the attribute, if applicable. The implementation of ClaimsPrincipalPermissionAttribute also exposes two other properties: Authenticated and RequiredClaimType.

The Authenticated property merely indicates if the security principal attached to the thread must be authenticated, just like the ClaimsPrincipalPermission. RequiredClaimType is a string property that indicates the claim type represented by the attribute. Ultimately this will be used to construct a ClaimSet to be passed to the ClaimsPrincipalPermission for permission demands. In this implementation I am assuming that the caller will pass a valid claim type from the ClaimsAuthorizationPolicy.ClaimTypes static class, discussed in Part 1. Resource is also a string property indicating the resource associated with the claim. This should be based on the ClaimsAuthorizationPolicy.Resources static class, also discussed in Part 1. Based on these supported resources and claim types I am inferring the issuer when the claim set is created during CreatePermission().

Listing 4 shows the full implementation.

Listing 4: Implementation of ClaimsPrincipalPermissionAttribute

using System;
using System.Security.Permissions;
using System.IdentityModel.Claims;

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = true, Inherited = false)]
public class ClaimsPrincipalPermissionAttribute :
CodeAccessSecurityAttribute
{

  private bool m_isAuthenticated;
  private string m_requiredClaimType;
  private string m_resource;

  public ClaimsPrincipalPermissionAttribute(SecurityAction action)
: base(action)
  {
    this.m_isAuthenticated = true;
  }

  public string RequiredClaimType
  {
    get
    {
      return this.m_requiredClaimType;

    }
    set
    {
      this.m_requiredClaimType = value;
    }
  }

  public string Resource
  {
    get
    {
      return this.m_resource;
    }
    set
    {
      this.m_resource = value;
    }
  }

  public bool Authenticated
  {
    get
    {
      return m_isAuthenticated;
    }
    set
    {
      m_isAuthenticated = value;
    }
  }

  public override System.Security.IPermission CreatePermission()
  {
    if (this.Unrestricted)
      return new
ClaimsPrincipalPermission(PermissionState.Unrestricted);

  ClaimSet cs = ClaimsAuthorizationPolicy.CreateClaimSet
(this.m_resource, this.m_requiredClaimType);
  return new ClaimsPrincipalPermission(this.m_isAuthenticated, cs);

  }
}

Attribute Usage

All attributes have an AttributeUsageAttribute applied to their type definition to indicate allowed use of the attribute. In the case of the ClaimsPrincipalPermissionAttribute, the following AttributeUsageAttribute is applied (also shown in Listing 4):

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = true, Inherited = false)]
public class ClaimsPrincipalPermissionAttribute : CodeAccessSecurityAttribute

In this case, the attribute is restricted to methods on a class, and cannot be inherited if there is a base type. So that you can stack many ClaimsPrincipalPermissionAttribute on a single method, AllowMultiple is set to true.

Declarative Claims-Based Demands

The purpose of providing the ClaimsPrincipalPermissionAttribute is to support declarative permission demands for each service operation instead of constructing the ClaimsPrincipalPermission directly. The following illustrates issuing a permission demand for the right to delete customers:

[ClaimsPrincipalPermissionAttribute(SecurityAction.Demand,
RequiredClaimType = ClaimsAuthorizationPolicy.ClaimTypes.Delete, Resource=ClaimsAuthorizationPolicy.Resources.Customers)]
public void DeleteCustomer(string customerId)
{
  // protected code
}

The verbosity of the attribute declaration results from the nature of claims-based security – it isn’t as simple as just passing a list of roles or user names to the attribute or permission. I have already simplified it by inferring the issuer, assuming it is associated with the type of claims and resources supported by the authorization policy. But, you can take it one level further by defining custom attributes that derive from this more general attribute. For example, I could create an attribute specifically for Create, Read, Update and Delete rights for Customers. Consider the following DeleteCustomersClaimAttribute:

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class,
AllowMultiple = true, Inherited = false)]
public class DeleteCustomersClaimAttribute:
ClaimsPrincipalPermissionAttribute
{

  public DeleteCustomersClaimAttribute(SecurityAction action)
: base(action)
  {
    this.Authenticated=true;
    this.RequiredClaimType =
ClaimsAuthorizationPolicy.ClaimTypes.Delete;
    this.Resource=ClaimsAuthorizationPolicy.Resources.Customers;
  }
}

When applied to a service operation, it greatly simplifies the declaration:

[DeleteCustomersClaim(SecurityAction.Demand)]
public void DeleteCustomer(string customerId)
{
  // protected code
}

So, when you design your claims-based permission model, you can come up with a collection of simplified attributes for developers to work with, while encapsulating the richness of the claims-based authorization within.

Pros and Cons of Claims-Based Security Permissions

The nice thing about using this claims-based security model is that developers can focus on demanding specific claims before operations can be executed, but they don’t need to know what form of authentication was used to grant those claims, so long as they trust the issuer. Since the model is familiar, the task is simplified. Furthermore, since the ClaimsPrincipalPermission also holds the ClaimSet granted by the trusted issuer, permission demands can also be placed in downstream assemblies used by the service, if applicable. This may be necessary when business rules require knowledge of the authenticated caller, or their granted rights.

One downside of this approach is that the authorization policy must supply a complete set of claims for the authorized caller, so that operations can demand the claims they require. If there is a long list of claims that apply to features, actions and other information supplied about the caller, the ClaimSet can become quite large. A refinement of this model would be to modify the functionality of the authorization policy to grant a claim set that merely identifies the caller, without assigning all possible claims. Then, modify the attribute to gather the claims for a specific service and/or operation, on demand. Of course this can add overhead to each operation call, but can reduce the size of the claim set stored by the security context that may also need to be serialized and forward to downstream services.

Security Token Services, SAML Tokens and Claims

So far I have focused on how you can build a custom authorization policy to map any type of credential to a normalized set of claims – enabling service developers to authorize calls based on those claims regardless of the way calls are authenticated. Assuming that a trusted set of claims has been added to the security context, the claims-based authorization model I have described can be applied to your service operations, programmatically or declaratively with ClaimsPrincipalPermission and ClaimsPrincipalPermissionAttribute, respectively. What these constructs rely on is that a ClaimsPrincipal has been attached to the thread carrying the claim set that should be used for authorization. Figure 1 illustrates how the custom authorization policy attaches a set of claims and a custom security principal to the security context for each call to a business service.

Figure 1: This custom authorization policy maps a UserName credential to a set of normalized claims.

Using a custom authorization policy to map credentials to normalized claims is a great way to start moving to a claims-based security model, without introducing the concepts of federation and SAML tokens. So long as your services authorize calls based on claims attached to the security context or ClaimsPrincipal you can introduce federation without modifications to service code. In this section I’ll explain how federated security and SAML tokens can be introduced while still utilizing the claims-based security model I’ve described.

Token Issuance

Figure 1 illustrates a scenario where the business service is responsible for configuring a custom authorization policy to normalize claims. Fortunately the authorization policy decouples authentication of the UserName token (or, other tokens if supported) from the authorization against normalized claims. The requirement is only that the AuthorizationContext contains an appropriate claim set from the desired issuer, and that a ClaimsPrincipal is attached to the thread also referencing that claim set.

You can use WSFederationHttpBinding to delegate authentication to a Security Token Service (STS) that will issue a SAML token containing the same normalized claims. Using this binding the client will authenticate to the STS, retrieve the SAML token with normalized claims, and then authenticate to the business service with that token. The resulting claim set is automatically attached to the security context for authorization purposes, as I will discuss shortly. Figure 2 illustrates the flow of token issuance.

Figure 2: With WSFederationHttpBinding clients authenticate first to the STS, and then present issued tokens (such as SAML) to services.

WSFederationHttpBinding

You can configure your services to require a SAML token issued by a particular STS using WSFederationHttpBinding. This binding requires you to provide the following information:

• IssuedTokenType: The type of token you require the STS to issue. In this case it is a SAML v1.1 token.
• ClaimTypeRequirements: A list of required or optional claim types that should be included in the issued token. In the case of the SAML token these will be supplied as SAML attributes. The service model will be able to automatically unpack those attributes into a claim set.
• Issuer Address: The Uri where the WS-Trust endpoint implemented by the STS can be located.
• Issuer Binding: The binding requirements of the issuer, so that the client can supply the correct binding with credentials to authenticate to the STS.
• Issuer Identity: In this case a certificate reference is used to identify the STS.

The resulting WSFederationHttpBinding section is shown in Listing 5.

Listing 5: WSFederationHttpBinding configuration.

<wsFederationHttpBinding>
  <binding name="wsFed" >
    <security mode="Message">
      <message issuedTokenType="http://docs.oasis-open.org/wss/oasis-
wss-saml-token-profile-1.1#SAMLV1.1"
negotiateServiceCredential="false">

         <claimTypeRequirements>
          <add
claimType="http://schemas.thatindigogirl.com/samples/2006/06/identity/
claims/create" isOptional="true"/>

          <add
claimType="http://schemas.thatindigogirl.com/samples/2006/06/identity/
claims/read" isOptional="false" />
          <add
claimType="http://schemas.thatindigogirl.com/samples/2006/06/identity/
claims/update" isOptional="true"/>
          <add
claimType="http://schemas.thatindigogirl.com/samples/2006/06/identity/
claims/delete" isOptional="true"/>
        </claimTypeRequirements>

        <issuer address="http://localhost:51213/TokenIssuer/Service.svc"
binding ="wsHttpBinding"  bindingConfiguration="stsBinding" >
          <identity>
	      <certificateReference findValue="IPKey"
x509FindType="FindBySubjectName" storeLocation="LocalMachine"
storeName="TrustedPeople" />
          </identity>
        </issuer>

      </message>
    </security>
  </binding>
</wsFederationHttpBinding>

Clients use a similar configuration to initialize a proxy to invoke the service, thus the proxy has enough information to automatically make calls to the STS passing the UserName credential to authenticate. The goal of this process is that the SAML token returned by the STS will contain the normalized claims that were previously issued by the ClaimsAuthorizationPolicy discussed earlier.

Normalizing Claims at the STS

When you delegate authentication to an STS, this implies that the STS knows how to generate the required claims to authorize access at your business services. An STS can be any service that implements the WS-Trust contract as described by OASIS (see resources). Normally, you will not consider implementing your own WS-Trust endpoint. Instead, you might use a pre-existing STS such as the next generation Active Directory Federation Services (ADFS) or Ping Trust. To illustrate a simple example of an STS, I have provided a custom STS in the code sample that will issue a SAML token with the normalized claims already discussed.

This custom STS consists of a WCF service that authenticates callers with UserName token, and maps those tokens to normalized claims. In fact the configuration of this custom STS service can use the same custom authorization policy to generate a claim set for the UserName. As Figure 3 illustrates, the authorization policy provides a claim set to the security context. This claim set is then used by the STS to generate a SAML token with the appropriate claims.

Figure 3: The custom STS provided in the sample code uses the same custom authorization policy to map UserName to normalized claims.

From a high level, the SAML token includes a private key signature indicating issuer, which in this case is a private key using the DNS “IPKey”. The token also includes a collection of SAML attributes which each evaluate to the assigned normalized claims. Listing 6 illustrates the main piece of code where the SAML token is actually generated, with the generation of the attribute list and token generation shown bold. The call to GetClaimSet() checks the authorization context for claims added by the custom authorization policy discussed earlier, returning that set of claims.

Listing 6: Generating a SAML token from normalized claims.

private SecurityToken CreateSAMLToken(DateTime validFrom,
DateTime validTo, SecurityKey signingKey,
SecurityKeyIdentifier signingKeyIdentifier,
SecurityKeyIdentifier proofKeyIdentifier,
IList<ClaimTypeRequirement> claimReqs )
{
  List<string> confirmations = new List<string>();
  confirmations.Add(SamlConstants.HolderOfKey);

  SamlSubject subject = new SamlSubject(null, null, m_issuer,
confirmations, null, proofKeyIdentifier);

  List<SamlAttribute> attributes = new List<SamlAttribute>();
  ClaimSet cs = GetClaimSet(claimReqs);

  foreach (Claim c in cs)
    attributes.Add(new SamlAttribute(c));

  List<SamlStatement> statements = new List<SamlStatement>();
  statements.Add(new SamlAttributeStatement(subject, attributes));

  SamlConditions conditions = new SamlConditions(validFrom, validTo);

  SamlAssertion assertion = new SamlAssertion("_" + Guid.NewGuid().ToString(), m_issuer, validFrom, conditions, null, statements);

  string signatureAlgorithm = GetSignatureAlgorithm(signingKey);
  assertion.SigningCredentials = new SigningCredentials(signingKey,
signatureAlgorithm, SecurityAlgorithms.Sha1Digest,
signingKeyIdentifier);

  SamlSecurityToken token = new SamlSecurityToken(assertion);
  return token;
}

Without getting caught up in the details of the SAML token, or the STS, the point here is that any STS can be configured to issue SAML tokens that include attributes representative of a set of normalized claims your services depend on. You don’t have to write your own STS to do it. With this arrangement you can delegate authentication of callers so that they can pass any supported credential to the STS, and allow a trusted STS to determine the claims to be granted. Figure 4 illustrates an STS that is capable of authenticating Windows, UserName, Certificate, SAML (from a different source), or a token from CardSpace (self-issued, perhaps).

Figure 4: An STS can authenticate any type of credential and map that to normalized claims encapsulated by a SAML token.

By signing the token with the STS’ private key the claims passed inside the SAML token are guaranteed to have come from a trusted source – assuming that the business service “trusts” that signature, which I’ll discuss next.

Generating Claims from SAML Tokens

When a service is configured to require a SAML token (in this case using WSFederationHttpBinding) the token is authenticated at the service before its attributes are extracted – a ClaimSet constructed from them. When a SAML token is supplied in the security headers for a message, the SamlSecurityTokenAuthenticator type validates the signature of the token. By default, it is expected that the token is signed by a trusted RSA issuer, and this information is supplied by a service behavior as shown in the <issuedTokenAuthentication> section of Listing 7.

Listing 7: Service behavior configuration to supply a custom authorization policy and indicate trusted RSA issuers.

<serviceBehaviors>
  <behavior name="serviceBehavior">
    <serviceAuthorization principalPermissionMode="Custom" >
      <authorizationPolicies>
        <add policyType=
"ClaimsBasedSecurityComponents.SAMLClaimsAuthorizationPolicy,
ClaimsBasedSecurityComponents"/>
      </authorizationPolicies>
    </serviceAuthorization>
    <serviceCredentials>
      <issuedTokenAuthentication allowUntrustedRsaIssuers="false">
	  <knownCertificates>
	      <add findValue="IPKey" storeLocation ="LocalMachine"
storeName="TrustedPeople" x509FindType ="FindBySubjectName"/>
        </knownCertificates>
      </issuedTokenAuthentication>
      <serviceCertificate findValue="RPKey"
storeLocation="LocalMachine" storeName="My"
x509FindType="FindBySubjectName"/>
    </serviceCredentials>
  </behavior>
</serviceBehaviors>

In this case, the STS signed the SAML token with its private key, IPKey. Since this key is trusted the SAML token attributes are extracted and placed in the AuthorizationContext in the form of a ClaimSet, as illustrated by Figure 5.

Figure 5: Trusted SAML tokens are converted to claim sets for the authorization context.

Since the ClaimsPrincipalPermission and ClaimsPrincipalPermissionAttribute discussed in this article depend on the security principal attached to the thread to be a ClaimsPrincipal, a custom authorization policy (also shown configured in Listing 6) is still necessary to create the custom principal and associate the correct claim set. To handle this I provided a SAMLClaimsAuthorizationPolicy, which inherits ClaimsAuthorizationPolicy and overrides Evaluate() as follows:

public override bool Evaluate(EvaluationContext evaluationContext, ref
object state)
{
  ClaimSet principalClaimSet = null;

  foreach (ClaimSet cs in evaluationContext.ClaimSets)
  {
    if (cs.Issuer.ContainsClaim(Claim.CreateDnsClaim("IPKey")))
    {
      principalClaimSet = cs;
    }
  }

  if (principalClaimSet != null)
  {
    ClaimsPrincipal newPrincipal = new ClaimsPrincipal(new
GenericIdentity("IPKey"), principalClaimSet);
    evaluationContext.Properties["Principal"] = newPrincipal;
    return true;
  }
  else
    return false;
}

When this authorization policy is invoked the SAML token has already been validated, its claims attached to the EvaluationContext. The issuer of the claim set we want is IPKey, in this case. Thus, the claims issued by IPKey, the STS, are attached to the ClaimsPrincipal instance. Figure 6 illustrates this addition.

Figure 6: A custom authorization policy that attaches claims received through a SAML token to a ClaimsPrincipal.

At this point, the SAML token has carried the normalized claims to the business service, and the business service has constructed a custom ClaimsPrincipal to associate the claim set to the security principal to support the claims-based authorization model I described earlier.

Adjustments to the Claims-Based Authorization Model

A few adjustments must be made to the model I have described thus far, to support the claim set extracted from the SAML token. If you recall, the original ClaimsAuthorizationPolicy constructs a normalized claim set using a name claim as the Issuer, where the name is “http://www.thatindigogirl.com/samples/2006/06/issuer”. When claims are extracted from a SAML token, the Issuer is described by an X509ClaimSet, in this case IPKey. That means there is a Name claim and DNS claim of “IPKey”, and the original issuer name is nowhere to be found.

To support claim sets issued by the ClaimsAuthorizationPolicy, or via SAML token, I added additional claims to the Issuer claim set that include the following information:

public const string IssuerUri =
"http://www.thatindigogirl.com/samples/2006/06/issuer";

public const string IssuerName = "IPKey";

The helper function used to generate the Issuer claim set now generates a Uri, Name and DNS claim as shown here:
public static ClaimSet CreateIssuerClaimSet()
{
  return new DefaultClaimSet(Claim.CreateUriClaim(new
Uri(ClaimsAuthorizationPolicy.IssuerUri)),
Claim.CreateDnsClaim(ClaimsAuthorizationPolicy.IssuerName),
Claim.CreateNameClaim(ClaimsAuthorizationPolicy.IssuerName));
}

By making this change, the ClaimsPrincipalPermission is able to validate the issuer since only one of the claims must match.

Summary

In both parts of this article I have explained my approach to building a custom claims-based security model for your WCF services. Obviously to achieve this model it is necessary to establish a set of well-defined claims associated with service operations and application features. The idea being that those claims would should be required to access operations. For example, claims can be representative of features and actions users may take in the application, or claims can carry information about the caller that is useful to determine their rights. You should define a set of claims relevant to the application, so that operations can require claims to access certain features, and as new features are added to the application, new claims can be introduced.

Resources

Code for this article: http://www.dasblonde.net/downloads/tssclaimsbasedpart2.zip

Michele Leroux Bustamante

WCF introduces a claims-based approach to security at service boundaries, improving on role-based and permission-based security models. Claims can represent many different types of information including identity, roles, permissions or rights and even general information about the caller that may be useful to the application. A set of claims is also vouched for by an issuer such as a security token service, adding credibility to the information described by each claim – something not present in role-based or permission-based models. An additional benefit of using a claims-based security model is that it supports federated and single sign-on scenarios.

This two-part article will explain how claims-based security is supported by WCF, and show you how to implement a claims-based security model for your services. In this first article I’ll start by providing a quick review of the traditional role-based model most .NET applications rely on, and then I’ll compare this model to the claims-based model supported by WCF. In the process, I’ll explain how different security tokens are converted into claims, how the security context for each request is initialized with those claims, and how you can interact with claims to authorize calls. I’ll also explain how to define custom claims for an application, how to normalize different credentials into that set of claims using a custom authorization policy, and how to handle authorization centrally or at each service operation. In the second article I’ll show you how to refine this claims-based authorization model working with custom security principals and claims-based permission demands. I’ll then explain how you can decouple authentication using security token services or CardSpace, and how to work with SAML tokens that carry normalized claims.

WCF and Role-Based Security

Any application can leverage built-in role-based security features of .NET including Windows client applications, ASP.NET web applications, ASP.NET web services built with ASMX and WCF services. In all cases, when users are authenticated a security principal is attached to the executing thread. This security principal holds the caller’s identity, which may be tied to a Windows account or a custom credential, and its roles. Security principals are the heart of role-based security – used to perform authorization checks in code. This section will review how this works and how WCF services work with this role-based security model.

Security Principals and Identities

To review, a security principal is a type that implements the IPrincipal interface which includes the following members:

public interface IPrincipal
{
      bool IsInRole(string role);
      IIdentity Identity { get; }
}

Implementations of this interface should return true from the IsInRole() method if the associated user belongs to the specified role. The user is identified by the Identity property which is a type that implements the IIdentity interface shown here:

public interface IIdentity
{
      string AuthenticationType { get; }
      bool IsAuthenticated { get; }
      string Name { get; }
}

Essentially the IIdentity implementation should hold the authenticated user’s name and the authentication type.

These interfaces enable standardized access to authenticated users and associated roles. When users are authenticated, an IIdentity type is created based on the type of credential provided. Built-in types for various .NET applications include WindowsIdentity, FormsIdentity, PassportIdentity, X509Identity and GenericIdentity. Based on the authorization policy for the application, the security principal can be a WindowsPrincipal, GenericPrincipal or RoleProviderPrincipal – the latter of which is new to WCF.

Security Principals and WCF

When a service operation is invoked, the request thread will have a security principal attached. The type of IIdentity associated with that principal is based on the credential type received at the service. The type of IPrincipal is based on the authorization mode for the service. Let’s walk through two common examples, for Windows and UserName credential types.

Consider this service configuration with a WSHttpBinding endpoint that requires a Windows credential passed via message security mode:

<system.serviceModel>
  <services>
    <service name="RoleBasedServices.SecureServiceInternal" >
      <endpoint contract="RoleBasedServices.ISecureService"
binding="wsHttpBinding" bindingConfiguration="wsHttpWindows" />
    </service>
  </services>
  <bindings>
    <wsHttpBinding>
      <binding name="wsHttpWindows">
        <security mode="Message">
          <message clientCredentialType="Windows" />
        </security>
      </binding>
    </wsHttpBinding>
  </bindings>
</system.serviceModel>

When the Windows credential is passed by the client, it is serialized to a security token in the message. By default that token is authenticated and authorized against the Windows domain using NTLM or Kerberos (depending on your set up). For Windows credentials, the only authentication option is the Windows domain. By default, authorization relies on the Windows domain as well, per the PrincipalPermissionMode setting. The following illustrates a service behavior configuration showing the default settings for Windows authentication and authorization:

<behavior name="internalServiceBehavior">
  <serviceAuthorization
principalPermissionMode="UseWindowsGroups" />
  <serviceCredentials>
    <windowsAuthentication includeWindowsGroups="true"
allowAnonymousLogons="false" />
  </serviceCredentials>
</behavior>

With this configuration, the resulting security principal attached to the thread is a WindowsPrincipal with a WindowsIdentity reference.

In the case of UserName credentials, if the client passes a username and password that should be authenticated against a custom credential store, and not the Windows domain, you must explicitly configure the authentication and authorization modes. By default, UserName credentials are authenticated against the Windows domain, unless you provide an alternate UserNamePasswordValidationMode. Likewise, the default authorization mode uses the Windows domain unless you provide an alternate PrincipalPermissionMode. The following configuration illustrates a service that requires UserName credentials, and authenticates and authorizes against the configured ASP.NET membership and roles provider:

<system.serviceModel>
  <services>
    <service name="RoleBasedServices.SecureServiceExternal"
behaviorConfiguration="externalServiceBehavior">
      <endpoint contract="RoleBasedServices.ISecureService"
binding="wsHttpBinding" bindingConfiguration="wsHttpUsername" />
    </service>
  </services>
  <bindings>
    <wsHttpBinding>
      <binding name="wsHttpUsername">
        <security mode="Message">
          <message clientCredentialType="UserName"
negotiateServiceCredential="false"
establishSecurityContext="false" />
        </security>
      </binding>
    </wsHttpBinding>
  </bindings>
  <behaviors>
    <serviceBehaviors>
      <behavior name="externalServiceBehavior">
        <serviceAuthorization principalPermissionMode="UseAspNetRoles" />
        <serviceCredentials>
          <userNameAuthentication
userNamePasswordValidationMode="MembershipProvider" />
          <serviceCertificate findValue="RPKey"
x509FindType="FindBySubjectName" storeLocation="LocalMachine"
storeName="My"/>
        </serviceCredentials>
      </behavior>
    </serviceBehaviors>
  </behaviors>
</system.serviceModel>

To authenticate using the ASP.NET membership provider, you set the authentication mode to MembershipProvider instead of Windows (the default). To authorize using the ASP.NET roles provider, you set the authorization mode to UseAspNetRoles instead of UseWindowsGroups (the default). Unless you configure an alternate ASP.NET membership and roles provider, this means the default ASP.NET membership and roles provider – but you can create a custom provider to go against your own credential store if desired.

In this case a RoleProviderPrincipal is attached to the thread instead of a WindowsPrincipal. It references a GenericIdentity type carrying the username.

For both Windows and UserName credentials, the security principal attached to the thread supports role-based security since they respectively have access to the Windows or custom roles for the user. I’ll review how permission demands interact with the security principal shortly.

ServiceSecurityContext

In the case of WCF services, you can access information about the user through two means: the security principal attached to the thread, and the service security context. Put another way, the service model populates both the CurrentPrincipal property of the thread and the ServiceSecurityContext when it processes security tokens. For traditional role-based security, the CurrentPrincipal property is used to gain access to the security principal and the user identity:

IPrincipal principal = Thread.CurrentPrincipal;
IIdentity identity = Thread.CurrentPrincipal.Identity;

You can also access the user identity through the ServiceSecurityContext. This type also provides run-time access to other relevant information about the security context for a service operation – specifically, it provides access to identities, claims, and authorization policies as follows:

• PrimaryIdentity: Contains a reference to the IIdentity type representing the authenticated caller.
• WindowsIdentity: Contains a reference to the same IIdentity as the PrimaryIdentity property if it is a WindowsIdentity type.
• AuthorizationContext: Contains information about the security token(s) passed in the message. This information is useful for performing claims-based authorization which I’ll discuss shortly.
• AuthorizationPolicies: Contains information about the authorization policies used to grant claims, also to be discussed.

You can access the ServiceSecurityContext through the current OperationContext as shown here:

ServiceSecurityContext context = OperationContext.Current.ServiceSecurityContext;

Or, you can reach it directly through the static Current property:

ServiceSecurityContext context = ServiceSecurityContext.Current;

So, what’s the significance of the security principal attached to the thread and the security context? The security principal is used for role-based security consistent with pre-WCF role-based security techniques, while the ServiceSecurityContext is a WCF-specific abstraction that is most useful when you move away from role-based security to claims-based security as I will discuss.

Role-Based Permission Demands

.NET role-based security relies on the IPrincipal object attached to the thread to perform authorization checks. To authorize access to WCF operations you can use a PrincipalPermission demand to find out if the user is authenticated, if they are in a particular role, or if a particular user is calling (not as useful). Using an imperative permission demand within the WCF operation means creating a PrincipalPermission instance, initializing the values to enforce, and issuing a Demand():

public string AdminsOnly()
{
  // unprotected code

  PrincipalPermission p = new PrincipalPermission(null, "Administrators");
  p.Demand();

  // protected code
}

In this example, an exception will be thrown if the user is not in the Administrators group. You can also do this declaratively with the PrincipalPermissionAttribute:

[PrincipalPermission(SecurityAction.Demand, Role="Administrators")]
public string AdminsOnly()
{
  // protected code
}

Ultimately, both of these scenarios use the PrincipalPermission type to validate the thread’s security principal. This is done by checking the IsAuthenticated property of the IIdentity type and invoking the IsInRole() method of the IPrincipal type to check membership.

Internally, each IPrincipal type has its own way to enforce role checks when IsInRole() is called. In the case of the RoleProviderPrincipal it uses the ServiceSecurityContext to access the user’s identity, and it relies on the configured membership provider to check roles.

WCF and Claims-Based Security

Clearly, applying role-based permission demands is an easy approach to authorizing callers at the service tier. But, as I mentioned earlier, roles are very coarse and are prone to customization and change. Permissions are more granular, but don’t carry guarantees and aren’t first class citizens in any .NET security model. Claims, on the other hand, are a first class citizen with WCF.

Claims

Credentials are passed in the security headers of a message as security tokens. Each security token in a message is mapped to a set of claims that are added to the security context for the request. A claim describes an individual right or action applicable to a particular resource. For example, an identity claim might describe a username, while a proof of possession claim might describe a role, a right to a particular resource, or some other useful information.

Claims are represented at runtime as a Claim type, from the System.IdentityModel.Claims namespace, with the following key properties:

• ClaimType: Can be any Uri value identifying the type of claim. A basic set of claims used by WCF can be found in the ClaimTypes static class, but this can be customized.
• Resource: Can be any type, but should contain the resource being referred to by the claim. For an e-mail possession claim, this would contain an e-mail address as a string.
• Right: Can be a Uri identifying an identity claim, or a possession claim. The Rights static class contains the correct Uri to use.

You can programmatically construct a Claim by providing a ClaimType, Resource and Right. The following code shows how to create a Claim that represents possession of an email address:

Claim c = new
Claim("http://schemas.xmlsoap.org/ws/2005/05/identity/
claims/emailaddress", "mlb@idesign.net", 

http://schemas.xmlsoap.org/ws/2005/05/identity/right/possessproperty);

You can also rely on the ClaimTypes and Rights static classes instead of looking up the correct Uri for each:

Claim c = new Claim(ClaimTypes.Email, "mlb@idesign.net",
Rights.PossessProperty);

The types of claims associated with the security context depend on the type of token, as I’ll discuss next.

Claim Sets

A claim set is a collection of claims granted by a particular issuer. For example, the claims extracted from an X.509 token are vouched for by the certificate authority. The certificate authority is therefore the issuer of the claim set. A claim set is represented at runtime by the ClaimSet type. Key properties for this type are:

• Issuer: Another ClaimSet describing the issuer.
• A collection of claims the issuer vouches for.

WindowsClaimSet, UserNameClaimSet and X509ClaimSet are examples of types that inherit the ClaimSet base type. These are the claim sets generated for Windows, UserName and X.509 tokens, respectively. To give you some context for what goes into a ClaimSet, let’s look at a few examples relevant to some common credentials used for authentication.

A WindowsClaimSet includes information about the identity of the user, plus other information about windows groups and other security identifiers. The following table shows a list of identity and possession claims for a Windows token:

You’ll notice a few things about these claims:

• There is a single identity claim that is an SID associated with a Windows token identifier.
• The remaining claims are possession of property claims that provide additional information about the user. Those include a name claim with the user name associated with the token; and other SID claims representative of other token information and groups associated with the user.

The issuer can also be described as a WindowsClaimSet, representative of the Windows account for the machine where the claims were issued.

A UserNameClaimSet produces a completely different set of claims as shown in this table:

This time you’ll notice that a single identity and possess property claim are provided – both indicating the user name – and that no roles are included in this claim set. The issuer of a UserNameClaimSet is usually a DefaultClaimSet indicating the system (or, application) issued the claims. This table lists the claims inside the issuer’s DefaultClaimSet:

For X.509 tokens, the X509ClaimSet describes information related to the certificate as shown here:

The issuer for the X509ClaimSet depends on the type of certificate it represents. For example, if the certificate is self-issued, so is the claim set, which means the Issuer references itself. If the certificate is the root certificate, then the issuer should be the Certificate Authority certificate, otherwise it could represent another certificate in the chain.

The point of this discussion is to help you visualize the fact that every security token can be mapped to a set of claims, and that the service model extracts relevant claims for tokens it knows about. So far, I have focused only on Windows, UserName and Certificate credentials. What you should take away is the following:

• For Windows credentials, clearly it is easier to work with role-based security rather than resolving SIDs to Windows groups using the claim set.
• For UserName credentials, role-based security is the obvious choice since no roles are included in the claim set.
• For Certificate credentials, since there is no role-based security (unless you map certificates to Windows accounts) you might find the claim set useful for doing custom authorization. For example you might have a database that associates certificates with custom roles or claims.

You can construct a custom claim set by either extending the DefaultClaimSet type or by constructing a DefaultClaimSet instance and providing a list of claims along with an issuer. The following example creates a claim set that describes an issuer using a name claim:

Claim c =Claim.CreateNameClaim(
"http://www.thatindigogirl.com/samples/2006/06/issuer");
Claim[] claims = new Claim[1];
claims[0] = c;
ClaimSet issuer = new DefaultClaimSet(claims);

Since an issuer is not provided to the DefaultClaimSet constructor, the resulting ClaimSet is considered to be self-issued, and the Issuer property will reference itself. You can use this issuer claim set to construct a custom claim set for an application, as you’ll see later on.

AuthorizationContext

As I’ve discussed, when clients send credentials they are serialized as security tokens. The service model processes each security token and generates claims that vary based on the type of token. The claims are stored in the security context, accessible through the AuthorizationContext shown here:

AuthorizationContext authContext =
ServiceSecurityContext.Current.AuthorizationContext;

The AuthorizationContext includes one or more claim sets based on the authenticated security tokens from the incoming request message, and associated authorization policies. You can programmatically access each claim set and drill down to extract specific claims for authorization. For example, inside a service operation you might look for an X509CertificateClaimSet and check the DNS claim for a particular subject key:

AuthorizationContext authContext =
ServiceSecurityContext.Current.AuthorizationContext;

X509CertificateClaimSet certClaims = null;
foreach (ClaimSet c in authContext.ClaimSets)
{
  certClaims = c as X509CertificateClaimSet;
  if (certClaims != null)
    break;
}

if (certClaims == null)
  throw new SecurityException("Access is denied. X509CertificateClaimSet is required.");

if (!certClaims.ContainsClaim(Claim.CreateDnsClaim("RPKey")))
  throw new SecurityException("Access is denied.");

This example illustrates how you can access claims through the AuthorizationContext, based on the types of claim sets discussed so far. In reality it is more likely that you’ll map the incoming certificate to a custom set of roles or claims in order to standardize how you authorize callers to each operation. The AuthorizationContext becomes very useful in accessing custom claims attached to the security context that have specific meaning to your application. This is what I’ll focus on for the remainder of this article.

Building a Claims-Based Authorization Model

Now that you have some background on how claims are associated with the AuthorizationContext, and how you can access those claims to authorize calls – I’ll explain how to build a claims-based security model at the service tier using a custom authorization policy. The idea behind this is that your applications and services may need to support many credential types to support internal and external clients. Figure 1 illustrates this.

Figure 1: Services can be configured to support different credential types through security policy.

NOTE: All endpoints for a service share behavior, so you are more likely to have a common base service type with service logic, while exposing several derived types with unique endpoints and authorization behavior.

If services focus on authorization based on a normalized set of claims, the security policy can change without affecting service authorization, or downstream business rules based on user rights. Service developers should be able to work with a specific set of claims required to access features and interact with business rules – and ideally these claims are not coupled to a particular credential or set of roles. One way to achieve this is with a custom authorization policy as shown in Figure 2.

Figure 2: A custom authorization policy can produce a normalized set of claims for all credentials so that services can focus on a single set of claims for authorization.

In this case, the authorization policy is responsible for normalizing claims based on credentials provided, and the service authorizes against this consistent set of claims.

Defining Custom Claims

Before you can implement a claims-based model, you must consider what types of claims make sense to your application. If you think of claims as permissions that are required to access features, one thing you can do is create a list of these permissions, and the resources or features they relate to if applicable, and then formulate a set of custom claim types and resources based on this information.

Consider CRUD (Create, Read, Update, and Delete) operations related to resources in an application. If the application has two key features related to Customers and Orders, you might want to specify CRUD rights for each resource that can later be allocated to users as they are authenticated. The following table summarizes the possible claims:

To work with custom claims and resources in code you can create a list of representative constants as follows:

public static class ClaimTypes
{
  public const string Create = "http://schemas.thatindigogirl.com/
samples/2006/06/identity/claim/create";
  public const string Read = "http://schemas.thatindigogirl.com/
samples/2006/06/identity/claim/read";
  public const string Update = "http://schemas.thatindigogirl.com/
samples/2006/06/identity/claim/update";
  public const string Delete = "http://schemas.thatindigogirl.com/
samples/2006/06/identity/claim/delete";
}

public static class Resources
{
  public const string Customers = "http://schemas.thatindigogirl.com/
samples/2006/06/identity/resources/customers";
  public const string Orders = "http://schemas.thatindigogirl.com/
samples/2006/06/identity/resources/orders";
}

Services would then be designed to perform authentication against these claims, as appropriate for the operation being invoked. For example, an operation that will delete a customer should check that one of the claims provided in the authorization context includes the ClaimTypes.Delete right for Resources.Customers. As new features are added to the application, new claims may also be introduced to the authorization model, but if designed properly existing operations wouldn’t need to change their authorization requirements.

It may also be important who issued the claim. For example, you may want to look for a claim set by a trusted issuer before checking for particular claims within the claim set. When you’re using a custom authorization policy, as I will discuss in the coming sections, the issuer might just be the application as it was for the UserNameClaimSet discussed earlier, or a named internal issuer. In the article to follow this one, I will talk about trusting external issuers.

Implementing IAuthorizationPolicy

Once you have established your requirements for claims-based authorization, you can implement a custom authorization policy to handle mapping different credentials and tokens to your normalized application claims. A custom authorization policy is a type that implements the IAuthorizationPolicy interface from the System.IdentityModel.Policy namespace. Authorization policies can inspect the claims that will be attached to the security context, before operations are called, and attach new claim sets to that context. In addition, a custom authorization policy is required to provide a security principal to be attached to the request thread – in lieu of it being done automatically through default authentication.

To implement a custom authorization policy, you create a type that implements IAuthorizationPolicy. This interface also inherits IAuthorizationComponent, which means you must also provide implementation for its members. Definitions for the two interfaces are shown here:

public interface IAuthorizationPolicy : IAuthorizationComponent
{
  ClaimSet Issuer { get; }

  bool Evaluate(EvaluationContext evaluationContext,
ref object state);
}

public interface IAuthorizationComponent
{
  string Id { get; }
}

The functionality for each member should be implemented as follows:

• Id returns a unique identifier for the authorization policy instance. This can be a unique GUID.
• Issuer returns a ClaimSet describing the issuer associated with the authorization policy. If claims are generated by this authorization policy, it must provide an issuer when generating the claim set for the authorization context.
• The Evaluate() method receives the claim sets evaluated so far by other authorization policies. For example, it may include a claim set for each token passed in the request message, thus contain a WindowsClaimSet or UserNameClaimSet and so on.

Evaluate() is the heart and soul of this implementation – responsible for inspecting claims based on the credentials provided, mapping those claims to normalized claims, and constructing a security principal for the request thread. The method should return false if this authorization policy was not able to complete its authorization. If false, the service model will invoke other authorization policies and then call this one once more, passing the updated claim sets. This gives the authorization policy another chance to authorize calls.

The EvaluationContext passed to Evaluate() provides access to the user identity through its Properties dictionary. If you are looking for a particular type of identity, such as a WindowsIdentity or GenericIdentity you can check for this before mapping the identity to custom claims. The following code expects a single identity of type GenericIdentity, for services that require UserName credentials:

  object objIdentities = evaluationContext.Properties["Identities"];
  IList<IIdentity> identities = objIdentities as IList<IIdentity>;
  if (identities != null && identities.Count > 0)
  {
    IIdentity identity = identities[0] as GenericIdentity;
    if (identity == null)
      // can�t authorize
    else
      // can authorize
  }

If you write an authorization policy that specifically handles normalizing claims for UserName credentials, this is acceptable. You can optionally change this to support different identity types.

Once you have the identity, you can decide how to map that identity to normalized claims, building a ClaimSet for the authorization context. One approach could be to map roles to claims, which means looking up the roles for the identity to achieve this. The following MapClaims() function accepts an identity, expecting to use the ASP.NET provider model to find its roles and map those roles to claims:

protected virtual ClaimSet MapClaims(IIdentity identity)
{
  List<Claim> listClaims = new List<Claim>();

  if (Roles.IsUserInRole(identity.Name, "Guests"))
  {
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Read,
ClaimsAuthorizationPolicy.Resources.Customers,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Read,
ClaimsAuthorizationPolicy.Resources.Orders,
Rights.PossessProperty));
  }
  else if (Roles.IsUserInRole(identity.Name, "Users"))
  {
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Read,
ClaimsAuthorizationPolicy.Resources.Customers,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Read,
ClaimsAuthorizationPolicy.Resources.Orders,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Create,
ClaimsAuthorizationPolicy.Resources.Customers,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Create,
ClaimsAuthorizationPolicy.Resources.Orders,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Update,
ClaimsAuthorizationPolicy.Resources.Customers,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Update,
ClaimsAuthorizationPolicy.Resources.Orders,
Rights.PossessProperty));

  }
  else if (Roles.IsUserInRole(identity.Name, "Administrators"))
  {
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Read,
ClaimsAuthorizationPolicy.Resources.Customers,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Read,
ClaimsAuthorizationPolicy.Resources.Orders,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Create,
ClaimsAuthorizationPolicy.Resources.Customers,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Create,
ClaimsAuthorizationPolicy.Resources.Orders,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Update,
ClaimsAuthorizationPolicy.Resources.Customers,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Update,
ClaimsAuthorizationPolicy.Resources.Orders,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes.Delete,
ClaimsAuthorizationPolicy.Resources.Customers,
Rights.PossessProperty));
    listClaims.Add(new Claim(ClaimsAuthorizationPolicy.ClaimTypes. Delete,
ClaimsAuthorizationPolicy.Resources.Orders,
Rights.PossessProperty));
  }

  return new DefaultClaimSet(ClaimSet.System, listClaims);
}

For each role associated with UserName credentials, the authorization policy has established a list of claims that are appropriate. At the end of the function a new ClaimSet is created, in this case a DefaultClaimSet. You must provide the list of claims and an issuer for the claim set. In this case, the issuer is the application, identified by ClaimSet.System. You can also construct a custom claim set to identify the issuer – to distinguish claims. For example, you can construct a name claim with a custom Uri as shown here:

public const string IssuerName = "http://www.thatindigogirl.com/samples/2006/06/issuer";

Claim c = Claim.CreateNameClaim(ClaimsAuthorizationPolicy.IssuerName);
Claim[] claims = new Claim[1];
claims[0] = c;
DefaultClaimSet issuerClaimSet = new DefaultClaimSet(claims);

This approach allows you to check for the application trusted claim set when authorizing requests.

Once the normalized claim set is generated, you must attach it to the EvaluationContext so that the service model can add it to the AuthorizationContext. In addition, you must add a security principal to the EvaluationContext so that the service model can attach it to the request thread, and to the security context as discussed earlier. The complete implementation of the Evaluate() function for this custom authorization policy, addressing these requirements, is shown here:

public bool Evaluate(EvaluationContext evaluationContext,
ref object state)
{
  if (evaluationContext.Properties.ContainsKey("Identities"))
  {
    List<IIdentity> identities =
evaluationContext.Properties["Identities"] as List<IIdentity>;
    IIdentity identity = identities[0];

    ClaimSet claims = MapClaims(identity);

    GenericPrincipal newPrincipal = new
GenericPrincipal(identity, null);
    evaluationContext.Properties["Principal"] = newPrincipal;

    if (claims != null)
      evaluationContext.AddClaimSet(this, claims);

    return true;
  }
  else
    return false;
}

MapClaims() returns the claim set to attach to the evaluation context and a new GenericPrincipal without any roles is constructed to provide a security principal for the request thread. In this case, role-based security will be useless since no roles are assigned – but the AuthorizationContext will support claims-based security.

NOTE: You do not have to look at roles to map claims. Instead, you could look at the claim sets attached to the evaluation context, and determine how to assign normalized claims from the generated claims.

Configuring Custom Authorization Policies

To configure a custom authorization policy you set the PrincipalPermissionMode to Custom for the service authorization behavior, and add the IAuthorizationPolicy type to the authorization policies section as follows:

<serviceAuthorization principalPermissionMode="Custom" >
  <authorizationPolicies>
    <add policyType=
"ClaimsBasedSecurityComponents.ClaimsAuthorizationPolicy, ClaimsBasedSecurityComponents"/>
  </authorizationPolicies>
</serviceAuthorization>

NOTE: this can also be done programmatically through the ServiceHost instance.

By stating you are performing custom authorization, you are expected to supply the security principal for the thread, as I have discussed. You can configure one or more authorization policy, in the order you want them executed. This can be useful if you support different types of credentials at the service, and want to provide different authorization policies to handle each credential type for better reuse.

Once configured, the authorization policy will be instantiated for each request to the service, and given a change to supply information for the security context.

Working with Normalized Claims

Earlier in the article I said that the goal was to allow developers to standardize on a set of claims to authorize calls to each operation. As discussed earlier, the traditional role-based security model meant applying authorization checks at the operation level using permission demands either in code or using the PrincipalPermissionAttribute. Once your custom authorization policy is in place, you can replace these permission demands with claims-based authorization checks against the AuthorizationContext.

Consider a DeleteCustomer() operation that requires callers are granted delete rights to the customers resource. Inside the operation you can check the AuthorizationContext for a claim issued by your custom application issuer that matches this requirement:

public string DeleteCustomer()
{
  AuthorizationContext authContext =
ServiceSecurityContext.Current.AuthorizationContext;

  ClaimSet issuerClaimSet = null;
  foreach (ClaimSet cs in authContext.ClaimSets)
  {
    Claim issuerClaim = Claim.CreateNameClaim(
"http://www.thatindigogirl.com/samples/2006/06/issuer");

    if (cs.Issuer.ContainsClaim(issuerClaim))
      issuerClaimSet=cs;
  }

  if (issuerClaimSet==null)
    throw new SecurityException("Access is denied. No claims were provided from the expected issuer.");

  Claim c = new Claim("http://schemas.thatindigogirl.com/
samples/2006/06/identity/claims/delete",
"http://schemas.thatindigogirl.com/samples/2006/06/identity/
resources/customers", Rights.PossessProperty);

  if (!issuerClaimSet.ContainsClaim(c))
    throw new SecurityException("Access is denied. Required claims not
satisfied.");

This code traverses the AuthorizationContext for a claim set that matches the issuer identified by the name claim mentioned earlier: "http://www.thatindigogirl.com/samples/2006/06/issuer". If a claim set from the expected issuer is present, the code proceeds to look for a particular claim. In this case, the delete claim for customers.

Of course, you probably wouldn’t want to litter service operation code with this cumbersome block of code to authorize callers. That’s where we get into other techniques for authorizing these normalized claims, to be discussed in the next part of this article.

Summary

In this article you learned how role-based security and claims-based security differ, and how to implement a claims-based security model. The goal of this first part was to educate you on claims and claim sets, help you understand how tokens map to claims, and educate you on the process of creating your own custom claims model. In addition, you learned how to create a custom authorization policy that can normalize claims for all tokens, and insert those new claims into the authorization context for evaluation in lieu of role-based security checks.

In the next part of this article, I’ll discuss several techniques for refining the authorization of custom claims. Instead of performing authorization directly in the operation I’ll show you how to extend the role-based security model of .NET for a claims-based model, I’ll also compare that approach to a custom validation policy or custom security token manager implementation. In addition, I’ll look at how the model works with SAML tokens issued by a custom security token service (STS).

Resources

Code for this article: http://www.dasblonde.net/downloads/tssclaimsbasedpart1.zip

Michele Leroux Bustamante