WIF introduced two new interfaces for representing client identities and principals: Microsoft.IdentityModel.Claims.IClaimsIdentity and Microsoft.IdentityModel.Claims.IClaimsPrincipal respectively (and the corresponding implementations ClaimsIdentity and ClaimsPrincipal).

IClaimsIdentity, in addition to giving you information about the client identity, provides a Claims property to gain access to claims associated to that identity. This could be the name, whether it is authenticated, or the way the client was authenticated.

public interface IClaimsIdentity : IIdentity
{
  ClaimCollection Claims { get; }
}

Because you have a new identity interface, there is also a principal interface IClaimsPrincipal with the corresponding implementation ClaimsPrincipal. This specific implementation wraps an instance of IClaimsIdentity instance and implements the IsInRole method by checking into the available claims:

public interface IClaimsPrincipal : IPrincipal
{
  ClaimsIdentityCollection Identities { get; }
}

Prior to WIF, building an active STS using WCF was a very complicated thing. All the documentation and examples available were unofficial and spread across different blogs. WIF fulfills an important missing piece in this area, providing all the necessary components and necessary classes to implement a STS and introduce claims-based security in your applications.

The core functionality to build a custom STS in WCF is provided by the abstract class Microsoft.IdentityModel.SecurityTokenService.SecurityTokenService.

A custom STS inherits this class and provides at least the following functionality:

The methods GetScope and GetOutputClaimsIdentity receive as argument a valid instance of an IClaimsPrincipal class that represents the authenticated caller's identity. This identity is typically used to determine the appropriate class to grant the caller. In the previous example, two claims are added to the security token, a claim for representing the caller name, and another hard-coded claim for representing the age.

After you have the service implementation ready, you need to expose it with one or more endpoints as you normally would with a traditional WCF service. In the case of a STS, you need to expose one of the contracts provided by WIF, which mainly depends on the features and WS-Trust version that you want to support in the STS.

WIF includes four contracts in the Microsoft.IdentityModel.Protocols.WSTrust namespace: IWSTrust13SyncContract for exposing a WS-Trust endpoint with the latest version of the specification (1.3), IWSTrustFeb2005SyncContract for exposing an older version of the specification (February 2005), or the asynchronous versions of the same contracts IWSTrust13AsyncContract and IWSTrustFeb2005AsyncContract.

The service class that implements the four contracts, WSTrustServiceContract, is also available in the same namespace. The following example illustrates one possible configuration for exposing a WS-Trust endpoint (the sync version of a WS-Trust 1.3 specification) using this service implementation:

<services>
  <service name="Microsoft.IdentityModel.Protocols.WSTrust.WSTrustServiceContract"
           behaviorConfiguration="stsBehavior">
    <endpoint address="WCFBookSTS"
              contract=
               "Microsoft.IdentityModel.Protocols.WSTrust.IWSTrust13SyncContract"
              binding="ws2007HttpBinding"
              bindingConfiguration="stsBinding"/>

  </service>
</services>

You basically need to define as many endpoints as authentication types and WS-Trust features you want to support. The binding definition for the previous endpoint "stsBinding" could be the following if you want to support username authentication for that endpoint:

<bindings>
  <ws2007HttpBinding>
    <binding name="stsBinding">
      <security mode="Message">
        <message clientCredentialType="UserName"
                 establishSecurityContext="false"
                 negotiateServiceCredential="true"/>
      </security>
    </binding>
  </ws2007HttpBinding>
</bindings>

As you can see, the same security characteristics that were previously discussed for other WCF services also apply for a STS implemented with WIF.

The last step in the basic implementation of a STS is to host the service so it becomes available to be consumed by different client applications. A new service host type, Microsoft.IdentityModel.Protocols.WSTrust.WSTrustServiceHost, is provided for that purpose.

One of the constructors for this new service host receives as arguments the configuration for the STS, and the base addresses where the service will listen for incoming requests:

static void Main( string[] args )
{
    X509Certificate2 stsCertificate = CertificateUtil.GetCertificate(
        StoreName.My,
        StoreLocation.LocalMachine,
        "CN=WCFSTS");

    // Create and setup the configuration for our STS
    SigningCredentials signingCreds = new X509SigningCredentials(stsCertificate);
    SecurityTokenServiceConfiguration config =
        new SecurityTokenServiceConfiguration("http://WCFBookSTS", signingCreds);

    config.SecurityTokenHandlers.AddOrReplace(new CustomUsernameTokenHandler());
    // Set the STS implementation class type
    config.SecurityTokenService = typeof( MySecurityTokenService );

    // Create the WS-Trust service host with our STS configuration
    using ( WSTrustServiceHost host = new WSTrustServiceHost( config, new Uri(
     "http://localhost:6000" ) ) )
    {
        host.Open();
        Console.WriteLine( "WCFBookSTS started, press ENTER to stop ..." );
        Console.ReadLine();
        host.Close();
    }
}

SecurityAuthenticationFederatedProgram.cs

The previous code initializes the STS configuration with the signing credentials that the STS will use to sign the issued SAML tokens, configure a custom security handler (discussed next), and finally create and open the service host using the configuration and the base address (http://localhost:6000).

A security token handler in WIF represents a new way to plug in custom token handling functionality. By writing a token handler, you can add functionality to serialize, deserialize, authenticate, and create a specific kind of token.

WIF has basically replaced the core functionality that WCF provides to parse security tokens, and validate them using credential validators such as the UserNamePasswordValidator or the X509CertificateValidator. This infrastructure is still layered on top of the WCF service layer, but most of the functionality that you would write to extends the WCF built-in security token. Authenticators will not work with this new architecture.

The base class for creating a new token handler is Microsoft.IdentityModel.Tokens.SecurityTokenHandler:

public abstract class SecurityTokenHandler
{

    public virtual bool CanReadToken(XmlReader reader);
    public virtual SecurityToken ReadToken(XmlReader reader);
    public virtual ClaimsIdentityCollection ValidateToken(SecurityToken token);

    public virtual void WriteToken(XmlWriter writer, SecurityToken token);
    public virtual bool CanValidateToken { get; }
    public virtual bool CanWriteToken { get; }

    public abstract Type TokenType { get; }
}

You can derive this class, implement the abstract methods, and override some of the available virtual methods to customize the handlings of an existing security token or support new ones.

WIF ships with a set of built-in token handlers for some of the well-known tokens. These include KerberosSecurityTokenHandler (for Kerberos tokens), UserNameSecurityTokenHandler (for username tokens), X509SecurityTokenHandler (for X509 certificate tokens), Saml11SecurityTokenHandler (for SAML 1.1 security tokens), or Saml2SecurityTokenHandler (for SAML 2.0 security tokens).

For example, if you want to customize the way username tokens are authenticated, you need to derive the class UsernameSecurityTokenHandler and provide the implementation of the ValidateToken method:

public class CustomUsernameTokenHandler : UserNameSecurityTokenHandler
{
    public override bool CanValidateToken
    {
        get
        {
            return true;
        }
    }

    public override Microsoft.IdentityModel.Claims.ClaimsIdentityCollection
     ValidateToken(System.IdentityModel.Tokens.SecurityToken token)
    {
        UserNameSecurityToken userNameToken = token as UserNameSecurityToken;
        if (userNameToken.UserName != "joe" ||
            userNameToken.Password != "bar")
        {
            throw new SecurityTokenValidationException(
               "The user can not be authenticated");
        }

        return new ClaimsIdentityCollection(new IClaimsIdentity[] {
            new ClaimsIdentity(
            new Claim(System.IdentityModel.Claims.ClaimTypes.Name,

userNameToken.UserName), "CustomUsernameTokenHandler")});

    }

    public override SecurityTokenHandler Clone()
    {
        return new CustomUsernameTokenHandler();
    }
}

In this example, the handler is validating that the username and password are equal to "Joe" and "bar" respectively. Also, that method needs to provide the list of claims available in the parsed token (the Name claim in this case).

The security token handlers can either be configured through configuration or code using the STS configuration class, as is shown here:

SecurityTokenServiceConfiguration config =
        new SecurityTokenServiceConfiguration("http://WCFBookSTS", signingCreds);

    config.SecurityTokenHandlers.AddOrReplace(new CustomUsernameTokenHandler());

The AddOrReplace method replaces the built-in UserNameSecurityTokenHandler, which by default is WindowsUserNameSecurityTokenHandler, and validates the tokens using Windows authentication.

WCF provides a federation binding to support scenarios in which the services expect a token issued by an STS, which is typically a SAML token (although it could be any other). WsFederationHttpBinding is the original binding shipped in the first WCF release to support the issue token negotiation with an STS, and Ws2007FederatedHttpBinding is a new version that supports the latest WS-* protocol versions.

In this section, you use the Ws2007FederationHttpBinding to configure a WCF service that requires a SAML 1.1 token issued by a custom STS built with WIF. See Listing 9-1.

public class EchoClaims : IEchoClaims
{
    public List<string> Echo()
    {

List<string> claims = new List<string>();

        IClaimsPrincipal principal = Thread.CurrentPrincipal as IClaimsPrincipal;

        foreach (IClaimsIdentity identity in principal.Identities)
        {
            foreach (Claim claim in identity.Claims)
            {
                claims.Add(string.Format("{0} - {1}",
                    claim.ClaimType, claim.Value));
            }
        }

        return claims;
    }

}

The main difference is that the WCF authorization context is no longer needed to get access to the authentication claims. Instead, the IClaimsPrincipal instance available in the Thread.CurrentPrincipal property can be used to enumerate different IClaimsIdentity instances and its associated claims (as far as you use the built-in support, only one identity will be available in the principal, the primary identity).

The WCF configuration for that service using the Ws2007FederationHttpBinding is shown in Listing 9-2.

<services>
      <service name="WCFBook.Samples.EchoClaims"
               behaviorConfiguration="echoClaimsBehavior">
        <endpoint address="EchoClaims"
                  contract="WCFBook.Samples.IEchoClaims"
                  binding="ws2007FederationHttpBinding"
                  bindingConfiguration="echoClaimsBinding"></endpoint>
        <endpoint address="mex"
               binding="mexHttpBinding"
               contract="IMetadataExchange" />
      </service>
    </services>
    <bindings>
      <ws2007FederationHttpBinding>
        <binding name="echoClaimsBinding" >
          <security mode="Message">
            <message negotiateServiceCredential="true">
              <claimTypeRequirements>
                <add claimType=
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
isOptional="false"/>
                <add claimType="http://WCFBookSamples/2008/05/AgeClaim"
isOptional="false"/>

</claimTypeRequirements>
            </message>
          </security>
        </binding>
      </ws2007FederationHttpBinding>
    </bindings>
    <behaviors>
      <serviceBehaviors>
        <behavior name="echoClaimsBehavior">
          <serviceMetadata httpGetEnabled="true"/>
          <serviceCredentials>
            <issuedTokenAuthentication
              certificateValidationMode="None"
              revocationMode="NoCheck">
              <knownCertificates>
                <add
                  findValue="CN=WCFSTS"
                  storeLocation="LocalMachine"
                  storeName="My"
                  x509FindType="FindBySubjectDistinguishedName"/>
              </knownCertificates>
            </issuedTokenAuthentication>
            <serviceCertificate
              findValue="CN=WCFServer"
              storeLocation="LocalMachine"
              storeName="My"
              x509FindType="FindBySubjectDistinguishedName"/>
          </serviceCredentials>

        </behavior>
      </serviceBehaviors>
    </behaviors>
  </system.serviceModel>

The service binding and behavior configuration has some settings worth pointing out. Inside the binding configuration, the <claimTypeRequirements> element indicates the custom claims expected by the service. These claims are exposed by WCF in the service WS-Policy, so the client knows what claims must be negotiated with the STS.

Inside the <serviceCredentials> behavior, the <issuedTokenAuthentication> element indicates which X509 signature should be used to validate the SAML token signature. This section only instructs WCF to validate the signature, and it is still the responsibility of the service to check whether the token has been issued by a trusted issuer (WIF provides an extensibility point for performing these checks).

The <serviceCertificate> element specifies the X509 certificate that needs to be used to decrypt the SAML token or the session key included within the token. (It is the same certificate provided in the GetScope method of the STS implementation example.)

As happens with most of the examples in this chapter, the X509 certificate validations have been disabled to use test certificates. These validations should be activated before rolling out the services to production.

The code for hosting the service and enabling claims-based security with WIF also requires some modifications with respect to the traditional way that you would normally use:

static void Main(string[] args)
{
    ServiceHost host = new ServiceHost(typeof(EchoClaims),
        new Uri("http://localhost:8000"));
    try
    {
        ServiceConfiguration configuration = new
ServiceConfiguration("WCFBook.Samples.EchoClaims");
        configuration.IssuerNameRegistry = new CustomIssuerNameRegistry();

        FederatedServiceCredentials.ConfigureServiceHost(host, configuration);

        host.Open();

        Console.WriteLine("Service running....");
        Console.WriteLine("Press a key to quit");
        Console.ReadKey();
    }
    finally
    {
        host.Close();
    }
}

The method call FederatedServiceCredentials.ConfigureServiceHost injects and initializes the WCF service host with all the extensions required by the WIF infrastructure — this also includes the built-in security token handlers.

The code is also setting a custom class in the configuration property IssuerNameRegistry. As discussed previously, this is the extensibility point for performing validations against the token issuer.

A simple implementation of the base class Microsoft.IdentityModel.Tokens.IssuerNameRegistry is shown in Listing 9-3.

public class CustomIssuerNameRegistry : IssuerNameRegistry
{
    public override string GetIssuerName(System.IdentityModel.Tokens.SecurityToken
    securityToken)
    {
        X509SecurityToken token = securityToken as X509SecurityToken;
        if (token == null)
        {
            throw new SecurityTokenException("Token is not a X509 Security Token");
        }

        if (token.Certificate.SubjectName.Name != "CN=WCFSTS")

{
            throw new SecurityTokenException("STS not supported");
        }


        return "WCFSTS";
    }
}

As you might notice, this implementation is quite simple. It validates that the token was signed by the X509 certificate with subject name "CN=WCFSTS" (only the trusted STS should have this certificate private key). You probably need to perform more complex validations for production-ready services, as only checking the subject name is not safe in most scenarios (anyone can generate a valid certificate with the same subject name).

Listing 9-4 shows the corresponding configuration for consuming this service on the client side.

<system.serviceModel>
      <client>
        <endpoint address="http://localhost:8000/EchoClaims"
                  binding="ws2007FederationHttpBinding"
                  bindingConfiguration="echoClaimsBinding"
                  contract="EchoClaimsReference.IEchoClaims"
                  name="WSHttpBinding_IEchoClaims"
                  behaviorConfiguration="echoClaimsBehavior">
          <identity>
            <dns value="WCFServer"/>
          </identity>
        </endpoint>
      </client>
      <bindings>
        <ws2007FederationHttpBinding>
          <binding name="echoClaimsBinding">
            <security mode="Message">
              <message>
                <claimTypeRequirements>
                  <add claimType=
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
isOptional="false"/>
                  <add claimType="http://WCFBookSamples/2008/05/AgeClaim"
isOptional="false"/>
                </claimTypeRequirements>
                <issuer address="http://localhost:6000/WCFBookSTS"
                        bindingConfiguration="stsBinding"
                        binding="ws2007HttpBinding">
                  <identity>
                    <dns value="WCFSTS"/>

</identity>
                </issuer>
                <issuerMetadata
address="http://localhost:6000/WCFBookSTS/Mex"></issuerMetadata>
              </message>
            </security>
          </binding>
        </ws2007FederationHttpBinding>

        <ws2007HttpBinding>
            <binding name="stsBinding">
              <security mode="Message">
                <message clientCredentialType="UserName"
                  establishSecurityContext="false"
                  negotiateServiceCredential="true"/>
              </security>
            </binding>
        </ws2007HttpBinding>
      </bindings>

      <behaviors>
        <endpointBehaviors>
          <behavior name="echoClaimsBehavior">
            <clientCredentials>
              <serviceCertificate>
                <defaultCertificate
                  findValue="CN=WCFSTS"
                  storeLocation="LocalMachine"
                  storeName="My"
                  x509FindType="FindBySubjectDistinguishedName"/>
                <authentication
                  revocationMode="NoCheck"
                  certificateValidationMode="None"/>
              </serviceCertificate>
            </clientCredentials>
          </behavior>
        </endpointBehaviors>
      </behaviors>
    </system.serviceModel>

The main difference with a traditional WCF endpoint is that two bindings are used, one for specifying the communication details with the final service, Ws2007FederatedBinding, and another for doing the same with the STS, Ws2007HttpBinding.

As you might notice, Ws2007FederatedBinding replicates the same configuration that you set on the service side with an extra element <issuer>. This specifies the issuer address a reference to the binding used for setting the communication details.