Click here to Skip to main content
15,880,132 members
Articles / Programming Languages / C#

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

Rate me:
Please Sign up or sign in to vote.
4.53/5 (9 votes)
18 Oct 2012CPOL2 min read 70.7K   1.5K   20   17
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)

Written By
Software Developer (Senior)
Israel Israel
Web services interoperability expert.

Comments and Discussions

QuestionHow do I add attribute : MaxReceivedMessageSize Pin
coderDeamon10-Aug-15 8:06
coderDeamon10-Aug-15 8:06 
QuestionRe: How do I add attribute : MaxReceivedMessageSize Pin
Edgar R. C.20-Jun-16 11:21
Edgar R. C.20-Jun-16 11:21 
QuestionClient configuration Pin
moh moh oo17-Feb-13 8:19
professionalmoh moh oo17-Feb-13 8:19 
AnswerRe: Client configuration Pin
Yaron Naveh19-Feb-13 8:24
Yaron Naveh19-Feb-13 8:24 
GeneralRe: Client configuration Pin
moh moh oo21-Feb-13 0:34
professionalmoh moh oo21-Feb-13 0:34 
Nuzz60417-Oct-12 14:19
Nuzz60417-Oct-12 14:19 
GeneralTCP support? Pin
Nuzz60417-Oct-12 14:28
Nuzz60417-Oct-12 14:28 
GeneralRe: TCP support? Pin
Yaron Naveh18-Oct-12 11:07
Yaron Naveh18-Oct-12 11:07 
GeneralRe: TCP support? Pin
Nuzz60418-Oct-12 11:18
Nuzz60418-Oct-12 11:18 
GeneralRe: TCP support? Pin
emperon19-Oct-12 0:46
emperon19-Oct-12 0:46 
GeneralRe: TCP support? Pin
Nuzz60419-Oct-12 7:32
Nuzz60419-Oct-12 7:32 
GeneralRe: BROKEN Pin
Yaron Naveh18-Oct-12 11:05
Yaron Naveh18-Oct-12 11:05 
GeneralThanks Pin
bkejser20-Dec-11 18:24
bkejser20-Dec-11 18:24 
GeneralWCF TransportCredentialOnly with HttpClientCredentialType.Certificate Pin
beat.kiener24-May-10 22:22
beat.kiener24-May-10 22:22 
GeneralRe: WCF TransportCredentialOnly with HttpClientCredentialType.Certificate Pin
Yaron Naveh25-May-10 8:37
Yaron Naveh25-May-10 8:37 
GeneralI sure hope all users of your "ClearUsernameBinding" will understand the implications..... Pin
Marc Scheuner7-Sep-09 11:15
professionalMarc Scheuner7-Sep-09 11:15 
GeneralRe: I sure hope all users of your "ClearUsernameBinding" will understand the implications..... Pin
Yaron Naveh7-Sep-09 11:49
Yaron Naveh7-Sep-09 11:49 

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

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