WCF ClearUsernameBinding: Send username without SSL or x.509 certificates

• Download source - 94.27 KB

Introduction

A username/password pair is a common authentication mechanism in web services. However, WCF limits the use of usernames to SSL or x.509 enabled scenarios only. ClearUsernameBinding mitigates this limitation.

Background

One of the most common authentication mechanisms in web services is a username/password in the message level. It looks like this:

<wsse:Username>yaron</wsse:Username>
<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-username-token-profile-1.0#PasswordText">1234</wsse:Password>

Since the password appears in cleartext, anyone who sees this message can later break into the system.
For this reason, transport level SSL or X.509 certificates at the message level should be used.
WCF actually forces us to use one of these mechanisms when we want to have a username.

Otherwise we would get any of the following exceptions (see full list):

The provided URI scheme 'http' is invalid; expected 'https'.
Parameter name: via

The provided URI scheme 'https' is invalid; expected 'http'.
Parameter name: via

BasicHttp binding requires that BasicHttpBinding.Security.Message.ClientCredentialType 
be equivalent to the BasicHttpMessageCredentialType.Certificate 
credential type for secure messages. 
Select Transport or TransportWithMessageCredential security for UserName credentials.

Could not find a base address that matches scheme https for the endpoint 
with binding BasicHttpBinding. 
Registered base address schemes are [http]. 

While being a good practice, this recommendation has a negative effect on interoperability as web services created by other frameworks may require a cleartext username. There are also legitimate scenarios when we want to do this, like in an internal secured network or when using load balancers SSL passthrough (e.g. F5's BIG-IP).

Running the Demo Project

ClearUsernmaeBinding code comes with a demo project. In order to run the demo:

1. Extract the code attached to this article to some folder, e.g. C:\program files\ClearUsernameBinding\
2. Run the server:

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

3. Run the client:

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

And you have a working demo of WCF with a clear username!

Using the Code

The code is a new WCF binding which you can use in your projects.
This blog post has additional information on how to use it.

Follow these steps:

1. Extract the code to some folder (e.g. "ClearUsernameBinding")
2. In your WCF project, add reference to ClearUsernameBinding\ClearUserPassBinding\bin\Release\ClearUsernameBinding.dll (the root folder is the one you extracted to)
3. In web.config or app.config, register and configure the binding in the system.ServiceModel section:

<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>

1. In the same configuration file, configure your endpoint to use ClearUsernameBinding:

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

More Information

• ClearUsernameBinding in Google code
• Support for ClearUsernameBinding
• More details on username in WCF
• Securing Web Services With Username/Password
• WCF Blog

The Binding Author

Yaron Naveh is a web services interoperability expert.
His blog contains information about interoperability of various frameworks (WCF, WSE, WSIT, Axis2...) and deals with web services security, performance and testing.

History

• 6^th September, 2009: Initial post