integrating your business

A while ago I had a little surprise with a demo project.
The project consists of a client application, a claims aware WCF service and AD FS as token issuer.

This demo was working fine until now...
Without changing anything, authentication always fails with this error message (see WIF tracing):

ID4175: The issuer of the security token was not recognized by the IssuerNameRegistry. To accept security tokens from this issuer, configure the IssuerNameRegistry to return a valid name for this issuer.

Offcourse my token issuer certificate was added to the 'trustedissuers' collection on the WCF service, so something must have changed in AD FS.

The signing certificate in AD FS shows this:

As you can see, there are two signing certificates (I had one before). The second signing certificate was created by AD FS automatically because my signing certificate was reaching it's expiration date. This feature - AD FS creating a new self-signed certificate when the old one nears expiration - is called Auto Certificate Rollover.

When using self-signed certificates, auto certificate rollover is on by default.
AF FS will use the signing certificate marked as 'Primary' to sign issued tokens.
The only thing I need to do is adding the new certificate to the trusted issuers collection as shown below:

Note: The reason why my sample failed is that I use the out-of-the box 'ConfigurationBasedIssuerNameRegistry' class to resolve the trusted issuer. This class uses the certificate thumbprint to match certificates. Obviously the certificate thumbprint changed when auto certificate rollover issued a new signing certificate. You can avoid this by implementing you own class and for example use the subject name to match issuers.

After adding the thumbprint of the new signing certificate to the trustedIssuers section, the sample should work again ... unless ...

My signing certificate is a self-signed certificate, but the newly created certificate is not trusted on the WCF machine. This results in this error:

ID4257: X.509 certificate 'CN=ADFS Signing - WIN-BEJU5AI4TP7.pbdev.CODit.eu' validation failed by the token handler.

The self-signed signing certificate should be added to the trusted root store of the WCF machine. The action you need to take to make sure the certificate passes validation depends on the certificateValidation mode you use. Mine was set on chaintrust, so adding it to trusted root will do. If you use peertrust, add the certificate to the trusted people store. If you use custom it depends on your implementation.

Peter Borremans

When developing applications that make use of Windows Identity Foundation - WIF (Microsoft's technology to deal with claims-based security in your services) you can encounter exceptions that are not very precise/clear.

In this blog post I will show the difference between WCF tracing and WIF tracing based upon a sample application that is made to fail. The sample application consists of a client calling a service by first obtaining a security token from AD FS 2.0 and then asking the service to enumerate the claims present in the security token. The client will show the claims enumeration as received from the service. 

When I run my application (both the host and the client) this is the result:

The window in the background is my ServiceHost, the window in the front is the client. When the client calls the service over transport security the presented claims are enumerated as expected, when doing the same over message security the communication fails.

We will try to find the root cause of the problem by looking into WCF and WIF tracing.

The first thing the seasoned .NET developer will think of is to go in the .config file of your service and enable WCF Tracing:

Let's have a look what helpful information we can find in the WCF tracelog and WCF message log after running the sample.

The trace log shows this exception:

The message log shows this SOAP fault:

Although we have some useful information, "Message security verification failed" and "Security token could not be authenticated" can have a lot of reasons. We are interested in more detailed information about what goes wrong in the communication between clients, AD FS 2.0 and the service.

To find more detailed information we can enable WIF Tracing. WIF tracing cannot be enabled by clicking 'enable' in the Service Configuration Editor tool like we did for WCF Trace. However the idea is similar.

We only need to add two things to our config file (can also be done via the Service Configuration Editor tool):
- A diagnostics source: Microsoft.IdentityModel
- A listener (shared or not)

 The Xml representation looks like this: 

<system.diagnostics>
    <sources>
...
      <source name="Microsoft.IdentityModel" switchValue="Verbose">
         <listeners>
           <add name="WIFListener" />
         </listeners>
      </source>
...
    </sources>
    <sharedListeners>
...
      <add initializeData="c:\...\wif.svclog" type ="System.Diagnostics.XmlWriterTraceListener, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" name="WIFListener" />
    </sharedListeners>
</system.diagnostics>

The Service Configuration Editor tool view looks like this:

That't all you need to do to enable WIF tracing.

Let's re-run the sample app with WIF tracing enabled and hit against the same exception...

After opening the WIF trace-file, I can see this information:

As you can see, WIF Tracing gives us a much clearer exception message:

"ID1038: The AudienceRestrictionCondition was not valid because the specified Audience is not present in AudienceUris.
Audience: 'http://localhost:8733/ClaimsEnumeratorService/'"

After checking the service config file, I can see that WIF is exaclty right :)

The audienceUri for my endpoint that uses message security is commented out.
Thanks to WIF tracing I can troubleshoot problems like this in a reasonable time, with only WCF tracing the exception details are just not enough to point you to the right direction.

Both WCF and WIF tracing are priceless for .NET developers...

Peter Borremans

Peter Borremans, CODit Integration architect, wrote a detailed document on how to use certificates to enable message security on a BizTalk WCF receive location.  This document was published by Microsoft.