How to: Use a Custom User Name and Password Validator

Article
08/07/2009

By default, when a user name and password is used for authentication, Windows Communication Foundation (WCF) uses Windows to validate the user name and password. However, WCF allows for custom user name and password authentication schemes, also known as validators. To incorporate a custom user name and password validator, create a class that derives from UserNamePasswordValidator and then configure it.

For a sample application, see UserNamePassword Validator.

To create a custom user name and password validator

Create a class that derives from UserNamePasswordValidator.

Public Class CustomUserNameValidator
    Inherits UserNamePasswordValidator

public class CustomUserNameValidator : UserNamePasswordValidator
{

Implement the custom authentication scheme by overriding the Validate method.

Do not use the code in the following example that overrides the Validate method in a production environment. Replace the code with your custom user name and password validation scheme, which might involve retrieving user name and password pairs from a database.

To return authentication errors back to the client, throw a FaultException in the Validate method.

' This method validates users. It allows in two users, test1 and test2 
' with passwords 1tset and 2tset respectively.
' This code is for illustration purposes only and 
' must not be used in a production environment because it is not secure.    
Public Overrides Sub Validate(ByVal userName As String, ByVal password As String)
    If Nothing = userName OrElse Nothing = password Then
        Throw New ArgumentNullException()
    End If

    If Not (userName = "test1" AndAlso password = "1tset") AndAlso Not (userName = "test2" AndAlso password = "2tset") Then
        ' This throws an informative fault to the client.
        Throw New FaultException("Unknown Username or Incorrect Password")
        ' When you do not want to throw an infomative fault to the client,
        ' throw the following exception.
        ' Throw New SecurityTokenException("Unknown Username or Incorrect Password")
    End If

End Sub

// This method validates users. It allows in two users, test1 and test2 
// with passwords 1tset and 2tset respectively.
// This code is for illustration purposes only and 
// must not be used in a production environment because it is not secure.    
public override void Validate(string userName, string password)
{
    if (null == userName || null == password)
    {
        throw new ArgumentNullException();
    }

    if (!(userName == "test1" && password == "1tset") && !(userName == "test2" && password == "2tset"))
    {
        // This throws an informative fault to the client.
        throw new FaultException("Unknown Username or Incorrect Password");
        // When you do not want to throw an infomative fault to the client,
        // throw the following exception.
        // throw new SecurityTokenException("Unknown Username or Incorrect Password");
    }
}

To configure a service to use a custom user name and password validator

Configure a binding that uses message security over any transport or transport-level security over HTTP(S).

When using message security, add one of the system-provided bindings, such as wsHttpBinding Element, or a customBinding Element that supports message security and the UserName credential type.

When using transport-level security over HTTP(S), add either the wsHttpBinding Element or <basicHttpBinding>, or a customBinding Element that uses HTTP(S) and the Basic authentication scheme.

Note:
When .NET Framework version 3.5 or later is used, you can use a custom username and password validator with message and transport security. With .NET Framework 3.0, a custom username and password validator can only be used with message security.

In the configuration file, under the <system.ServiceModel> element, add a <bindings> element.
Add a wsHttpBinding Element or <basicHttpBinding> element to the bindings section. For more information about creating an WCF binding element, see How to: Specify a Service Binding in Configuration.
Set the mode attribute of the security element of wsHttpBinding or <security> of <basicHttpBinding> to Message, Transport, or TransportWithMessageCredential.

Set the clientCredentialType attribute of the message element of wsHttpBinding or <transport> of <wsHttpBinding>.

When using message security, set the clientCredentialType attribute of the message element of wsHttpBinding to UserName.

When using transport-level security over HTTP(S), set the clientCredentialType attribute of the <transport> of <wsHttpBinding> or <transport> of <basicHttpBinding> to Basic.

Note:
When a WCF service is hosted in Internet Information Services (IIS) using transport-level security and the UserNamePasswordValidationMode property is set to Custom, the custom authentication scheme uses a subset of Windows authentication. That is because in this scenario, IIS performs Windows authentication prior to WCF invoking the custom authenticator.

For more information about creating an WCF binding element, see How to: Specify a Service Binding in Configuration.

The following example shows the configuration code for the binding.

<system.serviceModel> 
  <bindings>
  <wsHttpBinding>
      <binding name="Binding1">
        <security mode="Message">
          <message clientCredentialType="UserName" />
        </security>
      </binding>        
    </wsHttpBinding>
  </bindings>
</system.serviceModel>

Configure a behavior that specifies that a custom user name and password validator is used to validate user name and password pairs for incoming UserNameSecurityToken security tokens.
1. As a child to the <system.serviceModel> element, add a <behaviors> element.
2. Add a serviceBehaviors section to the <behaviors> element.
3. Add a <behavior> element and set the name attribute to an appropriate value.
4. Add a <serviceCredentials> Element to the <behavior> element.
5. Add a userNameAuthentication element to the <serviceCredentials> Element.
6. Set the userNamePasswordValidationMode to Custom.
  
  Note:
  
  If the userNamePasswordValidationMode value is not set, WCF uses Windows authentication instead of the custom user name and password validator.
7. Set the customUserNamePasswordValidatorType to the type that represents your custom user name and password validator.
The following example shows the <serviceCredentials> fragment to this point.
```
<serviceCredentials>
  <userNameAuthentication userNamePasswordValidationMode="Custom" customUserNamePasswordValidatorType="Microsoft.ServiceModel.Samples.CalculatorService.CustomUserNameValidator, service" />
</serviceCredentials>
```

Note:
If the userNamePasswordValidationMode value is not set, WCF uses Windows authentication instead of the custom user name and password validator.

Example

The following code example demonstrates how to create a custom user name and password validator. Do not use the code that overrides the Validate method in a production environment. Replace the code with your custom user name and password validation scheme, which might involve retrieving user name and password pairs from a database.

Imports System

Imports System.IdentityModel.Selectors
Imports System.IdentityModel.Tokens

Imports System.Security.Principal

Imports System.ServiceModel

    

    
    ...
    
    

        Public Class CustomUserNameValidator
        Inherits UserNamePasswordValidator
        ' This method validates users. It allows in two users, test1 and test2 
        ' with passwords 1tset and 2tset respectively.
        ' This code is for illustration purposes only and 
        ' must not be used in a production environment because it is not secure.    
        Public Overrides Sub Validate(ByVal userName As String, ByVal password As String)
            If Nothing = userName OrElse Nothing = password Then
                Throw New ArgumentNullException()
            End If

            If Not (userName = "test1" AndAlso password = "1tset") AndAlso Not (userName = "test2" AndAlso password = "2tset") Then
                ' This throws an informative fault to the client.
                Throw New FaultException("Unknown Username or Incorrect Password")
                ' When you do not want to throw an infomative fault to the client,
                ' throw the following exception.
                ' Throw New SecurityTokenException("Unknown Username or Incorrect Password")
            End If

        End Sub
    End Class

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

using System.Security.Principal;

using System.ServiceModel;

    

    
    ...
    
    

    
        public class CustomUserNameValidator : UserNamePasswordValidator
        {
            // This method validates users. It allows in two users, test1 and test2 
            // with passwords 1tset and 2tset respectively.
            // This code is for illustration purposes only and 
            // must not be used in a production environment because it is not secure.   
            public override void Validate(string userName, string password)
            {
                if (null == userName || null == password)
                {
                    throw new ArgumentNullException();
                }

                if (!(userName == "test1" && password == "1tset") && !(userName == "test2" && password == "2tset"))
                {
                    // This throws an informative fault to the client.
                    throw new FaultException("Unknown Username or Incorrect Password");
                    // When you do not want to throw an infomative fault to the client,
                    // throw the following exception.
                    // throw new SecurityTokenException("Unknown Username or Incorrect Password");
                }
            }
        }

How to: Use a Custom User Name and Password Validator

To create a custom user name and password validator

To configure a service to use a custom user name and password validator

Example

See Also

Tasks

Reference

Other Resources

Additional resources