Authentication

• How do I decide on an authentication strategy in WCF?
• When should I use the SQL Server membership provider?
• How do I authenticate against Active Directory?
• How do I authenticate against a SQL store?
• How do I authenticate against a custom store?
• How do I protect passwords in my user store?
• How do I use certificate authentication with X.509 certificates?
• What is the most common authentication scenario for intranet applications?
• What is the most common authentication scenario for Internet applications?
• How do I support authentication for multiple client types?
• What is federated security?
• How do I send credentials in the message when I am using transport security?
• How do I avoid cleartext passwords?

How do I decide on an authentication strategy in WCF?

Decide your authentication strategy based on the location of your user credential store location and of your clients on the Internet or an intranet.

Internet

• Username authentication with the SQL Server membership provider. If your users are not in Active Directory, consider using the SQL Server membership provider. This will give you a store that can be easily deployed and created. Configure message or mixed-mode security to protect your users' credentials.
• Basic authentication with Windows. If your users are already in Active Directory, or in local machine accounts, consider using Basic authentication. Use transport security to secure the communication channel and protect your credentials.
• Username authentication with a custom store. If your users are in a custom store, consider using username authentication with a custom validator in order to validate user credentials against your custom store. Unlike the other scenarios, you will have to write custom code to validate your users' credentials. Use message or mixed-mode security to protect your users' credentials.
• Certificate authentication with certificates. If your clients are partners or mobile clients connecting over a virtual private network (VPN) in a peer-to-peer authentication scenario, consider using certificate authentication. If your users have Windows accounts in your domain, you can map the certificates to Windows accounts and enable authorization checks based on Windows roles. Certificate authentication requires that you manage certificates; however, it allows seamless authentication for clients who are outside your firewall. Use transport security to secure the communication channel and protect your credentials.

Intranet

• Username authentication with the SQL Server membership provider. If your users are not in Active Directory, consider using the SQL Server membership provider. This will give you a store that can be easily deployed and created. Use transport security to secure the communication channel and protect your credentials.
• Windows authentication with Windows. If your users are already in Active Directory or in local machine accounts, consider using Windows authentication to leverage this infrastructure. Windows authentication will also give you the benefits of using Windows roles for authorization checks. Use transport security to secure the communication channel and protect your credentials. Consider that local machine accounts configure authentication using the NTLM protocol, which is prone to brute-force attacks. For more secure peer-to-peer authentication, consider using certificate authentication.
• Username authentication with a custom store. If your users are in a custom store, consider using username authentication with a custom validator in order to validate user credentials against your custom store. Unlike the other scenarios, you will have to write custom code to validate your users' credentials. Use message or mixed-mode security to protect your users' credentials.
• Certificate authentication with certificates. If your clients are partners or mobile clients connecting over a virtual private network (VPN) in a peer-to-peer authentication scenario, consider using certificate authentication. If your users have Windows accounts in your domain, you can map the certificates to Windows accounts and enable authorization checks based on Windows roles. Certificate authentication requires that you manage certificates; however, it allows seamless authentication for clients who are outside your firewall. Use transport security to secure the communication channel and protect your credentials.

Additional Resources

• For more information on authentication, see Authentication.

When should I use the SQL Server Membership provider?

You should use SQL Server membership provider when users are not in Active Directory and you need a user store that can be easily created and deployed. As additional benefits, you can use authentication schemes in WCF that can cross firewall boundaries. You will need to use transport security to secure the communication channel to protect user credentials.

Additional Resources

• For more information on authentication, see Authentication.

How do I authenticate against Active Directory?

If your users are in Active Directory, consider using Windows, username, or Basic authentication. All of these authentication schemes can be mapped to users in Active Directory.

• Windows authentication. This authentication scheme will default to users in Active Directory. It offers the benefit of providing support for message security without requiring installation of certificates. It also provides support for transport security with netTcpBinding without requiring installation of certificates. Windows authentication cannot cross firewall boundaries

• Basic authentication. Basic authentication maps to users in Active Directory. Transport security will be required in order to protect user credentials. Basic authentication can cross firewall boundaries.

• Username authentication. Client username/password information is automatically mapped to Windows user accounts. Message security will be required in order to protect credentials. Username authentication can cross firewall boundaries. The following example configures the binding for username authentication and message security:

  <bindings>
  <wsHttpBinding>
  <binding name="MessageUserName">
            <security mode="Message">            
  <message clientCredentialType="UserName" />
  </security>
  </binding>
  </wsHttpBinding>
  </bindings>
  

Additional Resources

• For more information on authentication, see Authentication.

How do I authenticate against a SQL store?

To use username authentication with a SQL Server database, you can configure your application to use the ASP.NET membership feature. To configure the membership provider

1. Configure your SQL Server database for membership. From a Microsoft Visual Studio® 2008 command prompt, run the following command:

   aspnet_regsql -S .\SQLExpress -E -A m -d <<YourDatabaseName>>
   

   In this command:

   • -S specifies the server, which is (.\SQLExpress) in this example.
   • -E specifies to use Windows authentication to connect to SQL Server.
   • -A m specifies to add only the membership feature. For simple authentication against a SQL Server user store, only the membership feature is required.
   • -d specifies the SQL Server database name. If this option is not used, a default aspnetdb database will be created.

2. Modify your Web.config file in your WCF service application by adding the following sections:

   <connectionStrings>
     <add name="MyLocalSQLServer"
          connectionString="Initial Catalog=<<YourDatabaseName>>;
         data source=.\sqlexpress;Integrated Security=SSPI;" />
   </connectionStrings>
   
   …
   <system.web>
     ...
     <membership defaultProvider="MySqlMembershipProvider" >
       <providers>
         <clear/>
         <add name="MySqlMembershipProvider"
              connectionStringName="MyLocalSQLServer"
              applicationName="MyAppName"
              type="System.Web.Security.SqlMembershipProvider" />
       </providers>
     </membership>
   </system.web>
   …
   

3. Configure the service to use username authentication.

   …
   <bindings>
     <wsHttpBinding>
       <binding name="wsHttpEndpointBinding">
         <security>
           <message clientCredentialType="UserName" />
         </security>
       </binding>
     </wsHttpBinding>
   </bindings>
   

4. Configure the service to use the membership provider.

   <behaviors>
     <serviceBehaviors>
       <behavior name="ServiceBehavior">
   
         <serviceCredentials>
           <userNameAuthentication userNamePasswordValidationMode="MembershipProvider"
             membershipProviderName="MySqlMembershipProvider" />
         </serviceCredentials>
   
       </behavior>
     </serviceBehaviors>
   </behaviors>
   …
   

Additional Resources

• For more information, see How to: Use Username Authentication with the SQL Server Membership Provider and Message Security in WCF from Windows Forms.

How do I authenticate against a custom store?

To use a custom user/identity store with username authentication, configure your application to use username authentication with a custom username and password validator. The custom validator will be configured in a service behavior and implemented in a class library. The username and password validator will be used by your service to authenticate your users based on your custom user store.

The following configuration snippet shows how to configure a custom validator for your WCF service:

<serviceCredentials>
<userNameAuthentication userNamePasswordValidationMode="Custom" customUserNamePasswordValidatorType="MyUserNamePasswordValidator,Host"/>
<serviceCertificate findValue="CN=FabrikamEnterprises"/>
</serviceCredentials>

The following code snippet shows how to implement a custom username and password validator:

using System;
using System.Collections.Generic;
using System.IdentityModel.Selectors;
using System.IdentityModel.Tokens;
using System.Text;

namespace Validator
{
    public class MyUserNamePasswordValidator : UserNamePasswordValidator
    {
        public override void Validate(string userName, string password)
        {
            Console.Write("\nValidating username, {0}, and password, {1} ... ", userName, password);
            if ((string.Compare(userName, "don", true) != 0) || (string.Compare(password, "hall", false) != 0))
            {
                throw new SecurityTokenException("Unknown user.");
            }
            Console.Write("Done: Credentials accepted. \n");
        }
    }
}

How do I protect passwords in my user store?

Protect passwords in your user store by storing one-way password hashes with a salt. Generate the hash from a combination of the password and a random salt value. Use an algorithm such as SHA256. If your credential store is compromised, the salt value helps to slow an attacker who is attempting to perform a dictionary attack.

How do I use certificate authentication with X.509 certificates?

Configure your service to use wsHttpBinding with message security and clientCredentialType set to Certificate, as follows:

      <wsHttpBinding>
        <binding name="WSHttpBinding_ICalculator">
          <security mode="Message">
            <message clientCredentialType="Certificate" />
          </security>
        </binding>
      </wsHttpBinding>

You can map an X509 certificate to a Windows account by setting the mapClientCertificateToWindowsAccount property to true. By default, when using the certificate client credential type on bindings, the certificate is not mapped to Windows accounts. You can override this behavior by using the mapClientCertificateToWindowsAccount property as follows:

<serviceBehaviors>
  <behavior name="MyServiceBehaviorForWebHttp">

     <serviceCredentials>
      <clientCertificate>
       <authentication mapClientCertificateToWindowsAccount="true" />
      </clientCertificate>
     </serviceCredentials>

  </behavior>
</serviceBehaviors>

Additional Resources

• For more information on using WCF with certificates, see Working with Certificates.
• For more information on mapping certificates to Windows accounts, see Map certificates to user accounts.
• For more information on mapping certificates to Active Directory, see Mapping Client Certificates with Directory Service Mapping.
• For more information on certificate-mapping strategies, see Mapping Strategies.

What is the most common authentication scenario for intranet applications?

In the most common scenario, one or more clients connect to a WCF service using Windows authentication with users in Active Directory. The service uses transport security over netTcpBinding and is hosted in a Windows service. This combination gives the benefits of leveraging existing Windows users and groups for authentication and authorization while choosing the security mode and binding that are likely to yield the best performance.

What is the most common authentication scenario for Internet applications?

In the most common scenario, one or more clients connect to a WCF service using username authentication with users accessed via SqlMembershipProvider. The service uses message security over wsHttpBinding and is hosted in Internet Information Services (IIS). This combination works well over the Internet since it can cross firewalls and does not assume that your users are in Active Directory.

How do I support authentication for multiple client types?

You can supply multiple endpoints from within one service to support multiple client types. For example, you can have one endpoint with basicHttpBinding for legacy Web service client connections, and another endpoint with wsHttpBinding for WCF clients located on the Internet.

What is federated security?

Federated security provides a layer of abstraction between your service and the authentication/authorization mechanism you choose. This enables collaboration across multiple systems, networks, and organizations in different trust realms. WCF provides support for building and deploying distributed systems that employ federated security.

Using federated security gives you the flexibility of providing one set of credentials to a user and converting it to another set of credentials; for instance, converting the certificate given by the client to a Security Assertions Markup Language (SAML) token. Federated security also gives you the flexibility to alter your internal security mechanisms; for example, the client can provide a username/password pair to replace the certificate.

Additional Resources

• For more information, see Federation and Issued Tokens.

How do I send credentials in the message when I am using transport security?

In intermediary scenarios, you might want to send credentials in messages that are protected by transport security, allowing your user to be authenticated by a downstream system.

To send credentials in the message, set the security mode to TransportWithMessageCredentials and clientCredentialType to the type of credentials you want to include.

   <wsHttpBinding>
      <binding name="WindowsClientOverwsHttp">
        <security mode="TransportWithMessageCredentials">
          <transport clientCredentialType="Windows" />
        </security>
      </binding>
      </wsHttpBinding>

How do I avoid cleartext passwords?

Perform the following steps to avoid sending cleartext passwords over the network:

• If possible, remove the need for a password at all by specifying ClientCredentialType=”Windows”, ClientCredentialType=”Certificate”, or a custom token that does not require a password.
• If the user must enter a password, protect the password by specifying either <Security mode=”Transport”> to secure the channel or <Security mode=”Message”> to secure the messages. Do not specify <Security mode=”None”> in the configuration as this will provide no communication security.