Design Considerations

  • Article

patterns & practices Developer Center

  • How do I decide on an authentication strategy?
  • How do I decide on an authorization strategy?
  • When should I use message security versus transport security?
  • How do I use my existing Active Directory infrastructure?
  • What bindings should I use over the Internet?
  • What bindings should I use over an intranet?
  • When should I use resource-based authorization versus roles-based authorization?
  • When should I impersonate the original caller?
  • When should I flow the original caller's identity?
  • How do I migrate to WCF from an ASMX Web service?
  • How do I migrate to WCF from a COM application?
  • How do I migrate to WCF from a DCOM application?
  • How do I migrate to WCF from a WSE application?

How do I decide on an authentication strategy?

Decide your authentication strategy based on your user credential store location and the location 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 user's 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 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 to protect your credentials. Consider that local machine accounts configure authentication with 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 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

How do I decide on an authorization strategy?

Know your authorization options and choose the most appropriate one for your scenario. First decide if you want to use resource-based or role-based authorization. Resource-based authorization uses access control lists (ACLs) on the resource to authorize the original caller. Role-based authorization allows you to authorize access to service operations or resources based on the group a user is in.

  • If you choose to use role-based authorization, you can store your roles in Windows groups or in ASP.NET roles.
  • If you are using Active Directory, consider using Windows groups based on ease of maintenance and the fact that you maintain both roles and credentials in the Active Directory store. If you are not using Active Directory, consider using ASP.NET roles and the ASP.NET role provider.

Your authorization strategy may also be influenced by your choice of authentication type:

Resource-based Authorization

  • If you are using certificate authentication, you will need to map certificates to Windows groups.

  • If you are using username authentication, you will need to perform protocol transition.

  • Windows authentication will work with resource-based authorization by default.

  • Basic authentication will work with resource-based authorization by default.

    Note

    You need to impersonate for resource-based authorization.

Role-based Authorization

  • If you are using certificate authentication, you will need to map certificates to Windows groups.
  • If you are using username authentication with Windows groups, you will need to perform protocol transition.
  • Username authentication will work with ASP.NET roles by default.
  • Windows authentication will work with Windows groups by default.
  • Basic authentication will work with Windows groups by default.

Additional Resources

When should I use message security vs. transport security?

Message security encrypts each individual message to protect sensitive data. Transport security secures the end-to-end network connection to protect the network traffic.

Use the following criteria to decide whether to use transport security:

  • Point-to-point. Transport security supports point-to-point communication and does not support intermediary scenarios or protocol transition.
  • Streaming. Transport security can support streaming data scenarios.
  • Binding limitations. Transport security does not work with wsDualHttpBinding.
  • Authentication limitations. Transport security does not work with negotiation, username, or Kerberos direct authentication.
  • Performance. Transport security may provide better performance than message security.

Use the following criteria to decide whether to use message security:

  • Intermediaries. Message security supports scenarios with intermediaries or protocol transition.
  • Encryption flexibility. Message security allows you to encrypt part of a message while leaving other parts in cleartext format.
  • Binding limitations. Message security does not work with netNamedPipeBinding.
  • Secure conversations. Secure conversations only works with message security.
  • Authentication limitations. Message security does not work with Basic or Digest authentication.

Additional Resources

How do I use my existing Active Directory infrastructure?

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 has the benefits 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 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 to protect credentials. Username authentication can cross firewall boundaries.

What bindings should I use over the Internet?

The following bindings work well over the Internet, depending on your scenario:

  • If your service is interacting with WCF clients, use wsHttpBinding because this binding provides the best WS-* interoperability features, including (depending on your scenario) WS-Addressing and WS-AtomicTransaction. The combination of features offered by wsHttpBinding provides the most reliable connection offered by WCF over the Internet.
  • If your service is interacting with ASP.NET Web Services (ASMX) clients, you must use basicHttpBinding because it is the only WCF binding that supports ASMX clients.
  • Clients and services that require full-duplex communication should use wsDualHttpBinding because it is the only binding that supports full-duplex.
  • If your service interacts with Web Services Enhancements (WSE) clients, you must use customBinding. The service must use a custom binding to be compatible with the August 2004 version of WS-Addressing.

What bindings should I use over an intranet?

Although you can use any binding over an intranet, netTcpBinding will provide the best throughput performance. On an intranet, you generally do not need to be as concerned about the connection going down as with an Internet connection, so some of the WS-* advantages that are supplied with wsHttpBinding may not be necessary.

When should I use resource-based authorization vs. roles-based authorization?

Use resource-based authorization when you want to allow access to ACL-secured resources based on the original caller. Use roles-based authorization when you want to manage multiple users in groups to authorize on or within operations based on business logic.

When should I impersonate the original caller?

Impersonation allows your service to run in a least-privileged security context and only elevate privileges when necessary. Use impersonation when the service needs to use the original caller's credentials to access resources. Without impersonation, the service will authorize resource access based on the least-privileged account under which it is running.

The most common impersonation scenarios in WCF are:

  • Resource-based authorization on any resource using an ACL.
  • Role-based authorization in which the user's security context will be authorized downstream in another component.
  • Database authorization based on the original caller.

Additional Resources

When should I flow the original caller's identity?

Flow the original caller's identity when some action needs to be performed on the client's behalf. There are two methods for accomplishing this. The first is impersonation, which allows the service to act as the client while performing a business operation, such as accessing a resource or back-end system. Another way of flowing the caller's identity is via delegation. In this case, the service flows impersonation capabilities to a back-end service. The back-end service is passed the caller identity, which acts on behalf of the original caller. Therefore delegation includes another hop to another service with machine boundary, which will impersonate the original caller. Impersonation and delegation are features of Kerberos-based authentication. Both require a Windows identity.

Additional Resources

How do I migrate to WCF from an ASMX Web service?

In order to migrate to WCF from an ASMX Web service, you must update the service contract definition, elements, attributes, and configuration definitions. You can keep the exposed methods, properties, and business logic contained within the ASMX service.

Note the following considerations:

  • WCF requires Microsoft .NET Framework version 3.0 or above.
  • You can leave your ASMX clients as coded after you upgrade the service by using basicHttpBinding for the service. basicHttpBinding binding is compatible with ASMX clients.
  • The client proxy is nearly identical between ASMX and WCF, but should be regenerated by using SvcUtil.exe to ensure that it is up to date.
  • Because WCF configuration is different from ASMX configuration, it needs to be changed (e.g., for the app.config or web.config file).
  • WCF implements a [ServiceContract] attribute to define the service interface, and an [OperationContract] attribute for each method or property that is exposed. Web services implement a [WebService()] attribute to define the service and a [WebMethod()] attribute for each method or property that is exposed.

For example:

ASMX Web Service

[WebService()]
public class ThisService : WebService
{
  [WebMethod()]
  public String Hello(String inputName)
  {
    return "Hello, " + inputName;
  }

WCF Service

    [ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")]
    public interface IThisService
    {
        [OperationContract]
        string Hello(String inputName);
    }

public class ThisService : IThisService
{
  public String Hello(String inputName)
  {
    return "Hello, " + inputName;
  }

How do I migrate to WCF from a COM application?

WCF offers the advantage of a more distributable Service-Oriented Architecture (SOA). Your application can call the service objects on the same computer, or across different computers on an intranet or across the Internet. The service will be available to other applications as well.

To migrate a COM object to WCF

  1. Install .NET Framework 3.0 or above.
  2. Create a WCF service project. Move your code from the legacy COM application to the managed-code WCF service project.
  3. Add WCF [ServiceContract] and [OperationContract] attributes to define the service contract and operation contract elements. See “How do I migrate to WCF from an ASMX Web service?” above for more information on how to specify the [ServiceContract] and [OperationContract] attributes.
  4. Fill in the WCF service configuration file. If hosting in Internet Information Services (IIS), configure in the web.config file. If self-hosting, configure in the app.config file. If your application is calling the WCF service on the same computer, the NamedPipes binding will offer the best performance.

How do I migrate to WCF from a DCOM application?

WCF eliminates the difficulties of DCOM reliability and configuration. WCF offers the advantages of a more distributable Service-Oriented Architecture (SOA). Your application can call the service objects on the same computer, or across different computers on an intranet or across the Internet. The service will be available to other applications as well.

To migrate a DCOM object to WCF

  1. Install Microsoft .NET Framework 3.0 or above.
  2. Create a WCF service project. Move your code from the legacy DCOM application to the managed-code WCF service project.
  3. Add WCF [ServiceContract] and [OperationContract] attributes to define the service contract and operation contract elements. See “How do I migrate to WCF from an ASMX Web service?” above for more information on how to specify the [ServiceContract] and [OperationContract] attributes.
  4. Fill in the WCF service configuration file. If hosting in IIS, configure in the web.config file. If self-hosting, configure in the app.config file. If your application is calling the WCF service on the same computer, the NamedPipes binding will offer the best performance.

How do I migrate to WCF from a WSE application?

You can keep the exposed methods, properties, and business logic contained within the Web Services Enhancements (WSE) service. Update the service contract definition, elements, attributes, and configuration definitions to update the service from WSE to WCF. Note the following considerations:

  • WCF requires Microsoft .NET Framework 3.0 or above.
  • The client proxy is nearly identical between WSE and WCF, but should be regenerated using SvcUtil.exe to ensure that it is up to date.
  • WCF requires a different configuration than WSE (e.g., for the app.config or web.config file).
  • WCF implements a [ServiceContract] attribute to define the service interface, and an [OperationContract] attribute for each method or property exposed. Web services implement a [WebService()] attribute to define the service and a [WebMethod()] attribute for each method or property exposed.

For example:

ASMX Web Service

[WebService()]
public class ThisService : WebService
{
  [WebMethod()]
  public String Hello(String inputName)
  {
    return "Hello, " + inputName;
  }

WCF Service

    [ServiceContract(Namespace="http://Microsoft.ServiceModel.Samples")]
    public interface IThisService
    {
        [OperationContract]
        string Hello(String inputName);
    }

public class ThisService : IThisService
{
  public String Hello(String inputName)
  {
    return "Hello, " + inputName;
  }

WCF services are wire-level compatible with WSE clients when configured to use the August 2004 version of WS-Addressing. WCF services that interact with WSE clients require a custom binding configuration to facilitate WS-Addressing compatibility.

Additional Resources