Wednesday, July 10, 2013

Set WCF Service Authentication to Use a Custom Username & Password over HTTP

It’s a common requirement where you want to authenticate the requests which the clients will make to your WCF services. And let's say that’s using with some data which you have in your user table. In WCF, the default when a user name and password is used for authentication is let Windows to validate the user name and password using Windows Authentication. But if you want to authenticate users with custom validation, of course that’s possible with WCF, because of this custom validation scheme which is known as Validators. You will just have to create a class which will inherit from UserNamePasswordValidator class(which is provided with the .NET framework itself).

Now let’s see this in action. I have created a WCF application and I will just keep the default classes as it is. Now I am going to add a new class which is ServiceAuthenticator and going to inherit from UserNamePasswordValidator. For that I need to add reference to System.IdentityModel.

using System;
using System.IdentityModel.Selectors;
using System.IdentityModel.Tokens; 

namespace WcfService1
    public class ServiceAuthenticator : UserNamePasswordValidator
        public override void Validate(string userName, string password)
            if (null == userName || null == password)
                throw new ArgumentNullException();

            if (!(userName == "username" && password == "password"))
                throw new SecurityTokenException("Unknown Username or Password");

Now I need to configure a binding which supports message security over any transport or transport-level security over HTTP(S). Since I assume all my services are accessed via HTTP, the options I can use is wsHttpBinding or CustomBinding. So I am moving forward with wsHttpBinding and modifying the web.config file to configure custom wsHttpBinding as follows.
    <binding name="MyBinding">
      <security mode="Message">
        <message clientCredentialType="UserName"/>

When that's done I am configuring a behavior which specifies that a custom user name and password validator is used for authentication. And now comes another important thing to the picture which is a Certificate. In Message security, the message is encrypted by a service certificate which we are going to configure in web.config. So for that let’s create a certificate first. There is handy tool which you can download from my SkyDrive, which is known as Pluralsight self-cert Tool. This is provided by Pluralsight to create and install certificates.

So let’s see how we can use this great tool to create a new certificate and install it.

Pluralsight self-cert
Make sure to run this tool As Administrator and I have given a name which is “MyCertficate”. I am saving the certificate inside LocalMachine and the store name is “My”. Once you clicked the save button it will show the following message.

Certificate is created and stored.
Now let’s make sure the certificate is successfully created and installed. Go to Run and type mmc.

File Add/Remove Snap-in.

Add/Remove Snap-in
Click on Certificates and Add.

Add Certificate
Computer Account.

Computer Account
Local Computer and Finish.

Local Computer
Now in mmc, navigate to Certificates->Personal->Certificates. There you can see the certificate I have just created using self-cert.

View Certificate
Now let’s move back to web.config file and start creating a behavior configuration with the service certificate.
     <behavior name="MyBehavior">
       <serviceMetadata httpGetEnabled="true" />
       <serviceDebug includeExceptionDetailInFaults="true" />
         <userNameAuthentication userNamePasswordValidationMode="Custom"
          customUserNamePasswordValidatorType="WcfService1.ServiceAuthenticator, WcfService1" /> 

           storeName="My" />         



As you can see I have mentioned the userNamePasswordValidationMode as “Custom” and mentioned the ServiceCertificate.

Now let’s create the endpoints.
  <service behaviorConfiguration="MyBehavior" name="WcfService1.Service1">
    <endpoint address="Service1.svc" binding="wsHttpBinding"
              contract="WcfService1.IService1" />

    <endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange" />
        <add baseAddress="http://localhost:34435" />

Please note that I have mentioned the created custom configurations in the service behavior configuration and endpoint binding configuration.

Now that’s almost done. Please make sure you can view your service in the browser. If you are hosting your service application in IIS, you will be thrown out with this error which is “Keyset does not exist”.

Keyset does not exist.

Download winhttpcertcfg.exe from here. After installing the tool, run the following command on the command prompt as Administrator. Go to directory where you have installed this tool. Default is, ”C:\Program Files (x86)\Windows Resource Kits\Tools”. From sitting inside that directory run the following command.

If your service applications’ application pool is DefaultAppPool,
winhttpcertcfg -g -c LOCAL_MACHINE\My -s MyCertificate -a DefaultAppPool
If it’s another application pool you have created in which the identity is let's say “NetworkService”, then the command should be follows.
winhttpcertcfg -g -c LOCAL_MACHINE\My -s MyCertificate -a networkservice
Once you run the command, you will see a message like this.

Now make sure you can view your service in the browser.

Then let’s move to the final part which is the client app. I have created a console application and added a service reference. And following is my code.
using System;
using ConsoleApplication1.ServiceReference1;
using System.ServiceModel.Security; 

namespace ConsoleApplication1
    class Program
        static void Main(string[] args)
                Service1Client c = new Service1Client();
                c.ClientCredentials.UserName.UserName = "username";
                c.ClientCredentials.UserName.Password = "password";
                c.ClientCredentials.ServiceCertificate.Authentication.CertificateValidationMode = X509CertificateValidationMode.None;
            catch (MessageSecurityException ex)
As long I  can pass a valid username and a valid password to my ServiceAuthenticator class, I can consume the service. If not I will be thrown out with a error.

I am uploading a full sample to my SkyDrive.

Happy Coding.



  1. Really useful blog post, this way is very helpful when we are going to host our WCF service on cloud environment

  2. Hi,
    It is very informative and very helpful on my research regarding seo techniques. Thanks for sharing this post.
    Authentication Services