Click here to Skip to main content
Click here to Skip to main content

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

, 18 Oct 2012 CPOL
Rate this:
Please Sign up or sign in to vote.
How to use WCF to send cleartext username without SSL or X.509 certificate


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.


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

<wsse:Password Type="

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!

WCF ClearUsernameBinding

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:
              <endpoint address=http://localhost.:8087/SampleService/ 
                  name="ClearUsernameBinding_IEchoService" />

             <add name="clearUsernameBinding" 
		ClearUsernameBinding" />
             <binding name="myClearUsernameBinding" messageVersion="Soap12">

  1. In the same configuration file, configure your endpoint to use ClearUsernameBinding:
<endpoint binding="clearUsernameBinding" 
                    contract="WebServices20.SampleService.IEchoService" />

More Information

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.


  • 6th September, 2009: Initial post


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Yaron Naveh
Software Developer (Senior)
Israel Israel
Web services interoperability expert.
Follow on   Twitter

Comments and Discussions

QuestionClient configuration Pinmembermoh moh oo17-Feb-13 8:19 
AnswerRe: Client configuration PinmemberYaron Naveh19-Feb-13 8:24 
GeneralRe: Client configuration Pinmembermoh moh oo21-Feb-13 0:34 
BugBROKEN PinmemberNuzz60417-Oct-12 14:19 
GeneralTCP support? PinmemberNuzz60417-Oct-12 14:28 
GeneralRe: TCP support? PinmemberYaron Naveh18-Oct-12 11:07 
GeneralRe: TCP support? PinmemberNuzz60418-Oct-12 11:18 
GeneralRe: TCP support? Pinmemberemperon19-Oct-12 0:46 
GeneralRe: TCP support? PinmemberNuzz60419-Oct-12 7:32 
GeneralRe: BROKEN PinmemberYaron Naveh18-Oct-12 11:05 
GeneralThanks Pinmemberbkejser20-Dec-11 18:24 
GeneralWCF TransportCredentialOnly with HttpClientCredentialType.Certificate Pinmemberkiener24-May-10 22:22 
GeneralRe: WCF TransportCredentialOnly with HttpClientCredentialType.Certificate PinmemberYaron Naveh25-May-10 8:37 
GeneralI sure hope all users of your "ClearUsernameBinding" will understand the implications..... PinmemberMarc Scheuner7-Sep-09 11:15 
GeneralRe: I sure hope all users of your "ClearUsernameBinding" will understand the implications..... PinmemberYaron Naveh7-Sep-09 11:49 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web03 | 2.8.141022.2 | Last Updated 18 Oct 2012
Article Copyright 2009 by Yaron Naveh
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid