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:
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:
- Extract the code attached to this article to some folder, e.g. C:\program files\ClearUsernameBinding\
- Run the server:
- Run the client:
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:
- Extract the code to some folder (e.g. "ClearUsernameBinding")
- In your WCF project, add reference to ClearUsernameBinding\ClearUserPassBinding\bin\Release\ClearUsernameBinding.dll (the root folder is the one you extracted to)
- In web.config or app.config, register and configure the binding in the
<binding name="myClearUsernameBinding" messageVersion="Soap12">
- In the same configuration file, configure your endpoint to use
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