Introducing WCF ClearUsernameBinding

@YaronNaveh

Update: ClearUsernameBinding is now hosted on GitHub. This post contains the updated usage instructions.


Using cleartext username/password is usually not recommended. However it is sometimes required (like with F5's BIG-IP). WCF does not natively allow us to use such scenario. For this reason I have written ClearUsernameBinding - a WCF binding that enables to send cleartext username/password over HTTP.

Full source code is available in google code github.

So without any further preparations let's see how to use ClearUsernameBinding.

Step 1: Download latest release
Download it here or go to google code github.
Then extract the zip to some folder, let's say C:\program files\ (the ClearUsernameBinding subfolder will be created when extracting the zip).

Step 2 (optional) - Run the sample project
It can be useful to run the sample application.

Run the server:

C:\program files\ClearUsernameBinding\TestService\bin\Release\
TestService.exe

And now the client:

C:\program files\ClearUsernameBinding\TestClient\bin\Release\
TestClient.exe

And if everything went smoothly you have just seen ClearUsernameBinding in first action!

Step 3 (optional) - Investigate the sample project source code
The best way to learn a new (and very simple in this case) technology is by looking at existing projects. Just open with VS 2008 the solution file:

C:\program files\ClearUsernameBinding\ClearUsernameBinding.sln

And look at the source of the projects TestClient and TestService. These two projects are just normal WCF projects configured to use ClearUsernameBinding. In other words, making a WCF client/service use ClearUsernameBinding is just a matter of changing web.config and does not require coding. We will see in the next steps how to do it from scratch.

I'll probably have a separate post on the binding implementation itself. It is pretty straight forward and the handling of security is as I learned from Nicholas Allen's blog.

Step 4 - Creating your own service
For this step just create any normal WCF web site or a self hosted service.

Step 5 - Configure the service to use ClearUsernameBinding
Add your project a dll reference to

C:\Program Files\ClearUsernameBinding\ClearUserPassBinding\bin\
Release\ClearUsernameBinding.dll

Then open web.config and register the ClearUsernameBinding under the system.ServiceModel section:

<extensions>
  <bindingExtensions>
   <add name="clearUsernameBinding" type="WebServices20.BindingExtenions
.ClearUsernameCollectionElement, ClearUsernameBinding" />
  </bindingExtensions>
</extensions>

<bindings>
  <clearUsernameBinding>
   <binding name="myClearUsernameBinding"
messageVersion="Soap12">
   </binding>
  </clearUsernameBinding>
</bindings>

Finally configure your endpoint to use ClearUsernameBinging and its configuration:

<endpoint binding="clearUsernameBinding" bindingConfiguration="myClearUsernameBinding"
contract="WebServices20.SampleService.IEchoService" />

An example of the complete web.config is inside the full project binary&source in

C:\Program Files\ClearUsernameBinding\TestService\bin\Release\
TestService.exe.config

Step 6 (optional) - Configure the message version
If you need to use a specific message version configure it in the "messageVersion" attribute in the above configuration. Valid values are: Soap11WSAddressing10, Soap12WSAddressing10, Soap11WSAddressingAugust2004, Soap12WSAddressingAugust2004, Soap11, Soap12, None, Default.

Example:

<binding name="myClearUsernameBinding" messageVersion="Soap12">
</binding>

Step 7 - Configure the username authentication
This one needs to be done in any username/password authenticated service and not just one that uses ClearUsernameBinding. By default your server will authenticate the users against your active directory domain. If you want to do your own custom authentication you need to create a new class library project with a class that implements System.IdentityModel.Selectors.UserNamePasswordValidator

The class can look like this:

public class MyUserNameValidator : UserNamePasswordValidator
{
  public override void Validate(string userName, string password)
  {
   if (userName != "yaron")
    throw new SecurityTokenException("Unknown Username or Password");
  }
}

Don't forget to add dll reference to System.IdentityModel and System.IdentityModel.Selectors or the project will not compile. Then add this project as a project reference to your service project/website and configure the latter to use this custom authenticator:

<behaviors>
  <serviceBehaviors>
   <behavior name="SampleServiceBehaviour">
...
    <serviceCredentials>
    <userNameAuthentication     userNamePasswordValidationMode="Custom"
    customUserNamePasswordValidatorType=
"WebServices20.Validators.MyUserNameValidator, MyUserNameValidator" />
    </serviceCredentials>
   </behavior>
  </serviceBehaviors>
</behaviors>
...
<service behaviorConfiguration="SampleServiceBehaviour" name="WebServices20.SampleService.EchoService">
...

Again the full sample is available for download.


Step 8 - Run the service
Yes, the service is now ready to be activated, so run it when you are ready (run it directly from VS, just press F5).


Step 9 -Build a client
A service is worth nothing if there are no clients to consume it.
Create a new console application.
Right click the "References" node in the solution explorer and choose "Add service reference". Specify the WSDL of the server. If you are running the server from the given sample then the wsdl is in http://localhost:8087/SampleService/?WSDL. If you used your own server just run it and get the wsdl.

Now add some client code that uses the proxy to call the service. Don't forget to specify your username/password. For example:

ServiceReference1.EchoServiceClient client = new TestClient.ServiceReference1.EchoServiceClient();
client.ClientCredentials.UserName.UserName = "yaron";
client.ClientCredentials.UserName.Password = "1234";
client.EchoString("hello");

Step 10 - Configure the client
Configuring the client is as simple as configuring the service.
Here is the full client app.config:

<system.serviceModel>
  <client>
   <endpoint address="http://localhost.:8087/SampleService/" binding="clearUsernameBinding"
   bindingConfiguration="myClearUsernameBinding"   contract="ServiceReference1.IEchoService"
   name="ClearUsernameBinding_IEchoService" />
  </client>

  <extensions>
   <bindingExtensions>
    <add name="clearUsernameBinding"    type="WebServices20.BindingExtenions
.ClearUsernameCollectionElement   , ClearUsernameBinding" />
   </bindingExtensions>
  </extensions>

  <bindings>
   <clearUsernameBinding>
    <binding name="myClearUsernameBinding"
messageVersion="Soap12">

    </binding>
   </clearUsernameBinding>
  </bindings>

</system.serviceModel>

Step 11 - Done, Done, Done!
That's all. You can now run your client and see how WCF can be used to access a service with a cleartext username/password. Use a tool like fiddler to verify that indeed a clear username is sent (I've shorten some low-level stuff from bellow message):

<Envelope>
  <Header>
   <Security>
...
    <UsernameToken>
     <Username>yaron</Username>
     <Password>1234</Password>
    </UsernameToken>
   </Security>
  </Header>
  <Body>
   <EchoString xmlns="http://tempuri.org/">
    <s>hello</s>
   </EchoString>
  </Body>
</Envelope>

Conclusion
Sending username/password on the clear is not available out of the box with WCF (for reasons mentioned above). If such a scenario is required then ClearUsernameBinding needs to be used.

@YaronNaveh

What's next? get this blog rss updates or register for mail updates!