Chapter 5: Authentication, Authorization, and Identities in WCF

Contents

• Client Authentication and Service Authentication
• Transfer Security Modes
• Authentication Options with Transport Security
• Authentication Options with Message Security
• Authorization Options in WCF
• Role-based Authorization Options in WCF
• Identity-based Authorization Options in WCF
• Resource-based Authorization Options in WCF
• The Trusted Subsystem Model
• The Impersonation / Delegation Model
• Identities in WCF
• Design Strategy for Authentication and Authorization
• Key Authentication and Authorization Scenarios

Objectives

• Understand the WCF authentication options for security: message, transport, mixed, and both.
• Understand the WCF authorization options based on role, identity, and resource.
• Understand the various WCF identities and the meaning of process identity, security principle, and ServiceSecurityContext.
• Understand common implementation models that employ specific authentication, authorization, and identity options.

Overview

Your choice of an appropriate authentication and authorization option for your WCF service should be based on your particular deployment scenario, including the credential store, location of clients on the Internet or intranet, and authorization constraints. Use authentication to positively identify the client consuming your service. Use authorization to restrict access to resources, or to make business decisions based on user roles.

Client Authentication and Service Authentication

When considering authentication, you may be used to thinking primarily of the client identity. However, in the context of WCF, authentication typically refers to mutual authentication. Mutual authentication not only allows positive identification of the clients, but also allows clients to positively identify the WCF services to which they are connected. Mutual authentication is especially important for Internet-facing WCF services, because an attacker may be able to spoof the WCF service and hijack the client’s calls in order to reveal sensitive data.

The service credentials to be used depend largely on the client authentication scheme you choose. Typically, if you are using non-Windows client authentication such as username or certificate authentication, a service certificate is used for both service authentication and message protection. If you are using Windows client authentication, the Windows credentials of the process identity can be used for both service authentication and message protection.

Transfer Security Modes

Your WCF authentication options depend on the transfer security mode being used. For this reason, your authentication choices are partly determined by your transfer security mode. WCF offers the following transfer security modes:

• Message security. When using message security, the user credentials and claims are encapsulated in every message by using the WS-Security specification to secure messages. This option gives the most flexibility from an authentication perspective. You can use any type of authentication credential you want, largely independent of transport, as long as both client and service agree.
• Transport security. When using transport security, the user credentials and claims are passed by using the transport layer. In other words, user credentials are transport-dependent, which allows fewer authentication options compared to message security.
• Mixed security. Mixed security gives you the best of both worlds: transport security ensures the integrity and confidentiality of the messages, while the user credentials and claims are encapsulated in every message as in message security. This allows you to use a variety of user credentials that are not possible with strict transport security mechanisms, and to leverage transport security’s performance.
• Both. When using this option, the user credentials and claims are transferred at both the transport layer and the message level. Similarly, message protection is provided at both the transport layer and the message level. Note that this is not a common scenario, and only bindings that support the Microsoft® Message Queuing (MSMQ) protocol support this security mode.

Your choice of binding will also affect your authentication options because not all of the transport or message user credentials are supported in every binding.

Authentication Options with Transport Security

The follow authentication options are available when using transport security:

• None. When using this option, the WCF service does not authenticate the callers. This is not the recommended option from a security perspective—avoid using this option wherever possible.
• Basic. This option is available with the HTTP protocol only. The client is authenticated by using the username and password against the Microsoft Active Directory® directory service. The client credentials are transported by using a Base64 encode string, which is very similar to a clear string and therefore not the most secure option. The service is authenticated by the Secure Sockets Layer (SSL) certificate used for secure communication.
• NTLM. This option is available with the HTTP protocol only. The client is authenticated by using a challenge-response scheme against Windows accounts. NTLM authentication is well suited for a workgroup environment and is more secure than Basic authentication. The service is authenticated by using an SSL certificate.
• Windows. When using this option, the WCF service uses Kerberos authentication when in a domain, or NTLM authentication when deployed in a workgroup environment. This option uses a Windows token presented by the caller to authenticate against the Active Directory. This is the most secure option compared to Basic or NTLM authentication. The service is authenticated by using the Windows credentials of the process identity, or an SSL certificate if you are using the HTTP protocol.
• Certificate. When using this option, the caller presents an X.509 client certificate that the WCF service validates by trusting the certificate (peer trust) or trusting the issuer of the certificate (chain trust). This option should be used when Windows authentication is not possible, as in the case of business-to-business (B2B) scenarios. The service is authenticated with the service certificate, or by using an SSL certificate if you are using the HTTP protocol.

Authentication Options with Message Security

The following authentication options are available when using message security:

• None. When using this option, the WCF service does not authenticate the callers. This is not the recommended option from a security perspective—avoid using this option wherever possible.
• Windows. When using this option, the WCF service uses Kerberos authentication when in a domain, or NTLM authentication when deployed in a workgroup environment. This option uses the Windows token presented by the caller to authenticate against the Active Directory. Service is authenticated by using the Windows credentials of the process identity.
• Username. When using this option, the caller provides a username and password to the service. The service can either authenticate against Windows credentials, use a membership provider such as the Microsoft SQL Server® membership provider, or use a custom validator to validate against the custom store. You should choose this option only when Windows authentication is not possible. The service is authenticated by using a service certificate.
• Certificate. When using this option, the caller presents an X.509 client certificate. The WCF service looks up the certificate information on the host side and validates it (peer trust), or trusts the issuer of the client certificate (chain trust). This option should be used when Windows authentication is not possible, or in the case of B2B scenarios. The service is authenticated by using a service certificate.
• Issue token. When using this option, the client and service depend on the Secure Token Service (STS) to issue tokens that the client and service trusts. Microsoft Windows CardSpace™ is a typical example of an STS.

Authorization Options in WCF

WCF supports three basic authorization approaches:

• Role-based. Access to WCF operations is secured based on the role membership of the caller. Roles are used to partition your application’s user base into sets of users that share the same security privileges within the application; for example, Senior Managers, Managers, and Employees. Users are mapped to roles, and if the user is authorized to perform the requested operation, the application executes the operation.
• Identity-based. WCF supports an Identity Model feature, which is an extension of role-based authorization. Identity Model enables you to manage claims and policies in order to authorize clients. With this approach, you can verify claims contained within the authenticated users’ credentials. These claims can be compared with the set of authorization policies for the WCF service. Depending on the claims provided by the client, the service can either grant or deny access to the operation or resources. Identity Model is useful for fine-grained authorization and is most beneficial when using issue token authentication.
• Resource-based. With this option, individual resources are secured by using Windows access control lists (ACLs). The WCF service impersonates the caller prior to accessing resources, which allows the operating system to perform standard access checks. All resource access is performed using the original caller’s security context. This authorization approach severely impacts application scalability, because it means that connection pooling cannot be used effectively within the application’s middle tier.

In enterprise-level applications where scalability is essential, a role-based or identity-based approach for authorization is the best choice. For small-scale intranet applications that serve per-user content from resources (such as files) that can be secured with Windows ACLs, a resource-based approach may be appropriate.

Role-based Authorization Options in WCF

WCF provides the following options for role-based authorization:

• Windows groups. For WCF services and clients that are deployed in the same Windows domain, you can use Windows groups for role authorization. Typically, this option is suitable when you have a small number of coarse role requirements.
• ASP.NET roles. Use ASPNET roles if you have fine-grained roles requirements, or if the users cannot be mapped to Windows domain accounts. This option uses the Role Manager feature and provides three different role providers, based on the role store:
  • SqlRoleProvider. If your role information is stored in a SQL Server database, consider using SqlRoleProvider for roles authorization.
  • WindowsTokenRoleProvider. If your roles are Windows groups, and you want to leverage the Role Manager feature as a consistent way of checking the role membership of your users, regardless of the underlying data store, consider using WindowsTokenRoleProvider for roles authorization.
  • AuthorizationStoreRoleProvider. If your role information is stored using an AzMan policy store in an XML file, in Active Directory, or in Active Directory Application Mode (ADAM), consider using AuthorizationStoreRoleProvider for role authorization.
• Custom roles. If your role information is stored in a custom store such as a SQL Server database, create a custom authorization policy to authorize your users.

Note

It is recommended that you implement a custom role provider, using the Role Manager feature, for your custom role store rather than using the custom roles option.

Imperative Authorization

Imperative authorization supports fine-grained authorization choices based on business logic. Imperative role-based authorization is written into your code and processed at run time. Imperative security is useful when the resource to be accessed or action to be performed is not known until run time, or when you require finer-grained access control beyond the level of a code method.

Imperative Check Example

The following is an example of an Imperative check using the ASP.NET role provider:

if (Roles.IsUserInRole(@"accounting"))
{
  //authorized
}
else
{
  //authorization failed
}

Declarative Authorization

Declarative authorization can be added to application code at design time by specifying required access for a particular method or class declared as an attribute on the operation. Declarative role-based authorization is best for authorizing access to WCF at the operation level. Because attribute metadata is discoverable using reflection, it is easier to track the security principals that are allowed to access each method. Declarative authorization checks will work if you are using the ASP.NET role provider or Windows groups.

PrincipalPermission Example

The following code example shows how to use the PrinciplePermission attribute to perform declarative authorization:

[PrincipalPermission(SecurityAction.Demand, Role = "accounting")]
public double Add(double a, double b)
{
 return a + b;
}

Identity-based Authorization Options in WCF

WCF uses the Identity Model feature to create claims from incoming messages. Identity Model classes can be extended to support new claim types for custom authorization schemes. Identity Model and claim-based authorization are outside the scope of this guide.

For more information, see Managing Claims and Authorization with the Identity Model.

Resource-based Authorization Options in WCF

A resource-based approach tends to work best for applications that provide access to resources that can be individually secured with Windows ACLs, such as files and other local resources. The approach starts to break down in cases where the requested resource consists of data that needs to be obtained and consolidated from a number of different sources; for example, multiple databases, database tables, external applications, or Web services. If the resources are remote, you have to use delegation.

The resource-based approach relies on the original caller’s security context flowing through the application to the back-end resource managers. This can require complex configuration and significantly reduces the ability of a multi-tiered application to scale to large numbers of users, because it prevents the efficient use of pooling (for example, database connection pooling) within the application’s middle tier.

The two most commonly used resource-based security models are:

• The trusted subsystem model
• The impersonation/delegation model

The Trusted Subsystem Model

With this model, the WCF service uses a fixed identity to access downstream services and resources.

Figure 1
Trusted Subsystem Model

A variation on this model may use a fixed identity per role in order to map multiple users to a set of permissions on a downstream resource.

Figure 2
Trusted Subsystem Model with Fixed Role Identity

The security context of the original caller will not flow through the service at the operating-system level. You can flow the identity of the caller at the application level by passing it to the downstream resource manually for auditing purposes. For example, you can pass it as a string in the header of the message or as a parameter in a stored procedure, etc.

It may need to do so in order to support back-end auditing requirements, or to support per-user data access and authorization.

The pattern for resource access in the trusted subsystem model is as follows:

1. Authenticate users.
2. Map users to roles.
3. Authorize based on role membership.
4. Access the downstream resource manager using a single or multiple fixed trusted identities.

The Impersonation / Delegation Model

With this model, the WCF service impersonates the client’s identity before it accesses the next downstream service.

Figure 3
Impersonation/Delegation Model

If the next service in line is on the same computer, impersonation is sufficient. Delegation is required if the downstream service is located on a remote computer.

The delegation mechanism is a powerful feature. Use the constrained delegation feature available in Microsoft Windows Server® 2003 when possible. By using this feature, you can limit access to a particular service on a specific machine.

As a result of the delegation, the security context used for the downstream resource access is that of the client. This model is typically used for one of the following two reasons:

• It allows the downstream service to perform per-caller authorization using the original caller’s identity.
• It allows the downstream service to use operating system–level auditing features.

For more information about the impersonation options, see “Chapter 6: Impersonation and Delegation in WCF.”

Identities in WCF

When designing your authentication and authorization strategies, you need to consider the following identity types:

• Process identity. This is the identity of the process hosting the WCF service. When the WCF service is hosted in Internet Information Services (IIS), it typically is NETWORK SERVICE by default.

  This means that the machine account credentials of the service host are presented to downstream resources. The process identity is important because it identifies what Windows resources and back end the service can access, when the WCF service is not impersonating the original caller. If a certificate is used to protect the transport, the process identity also needs access to the certificate’s private keys in order to provide for message security or transport security with netTcpBinding.

• Security principal. The executing thread includes a security principal that contains the user identity and associated roles. The roles can be Windows roles if the principal is a Windows Principal; an ASP.NET role if it is a role Principal; or a custom role if it is a generic Principal. To be able to authorize—either with the Roles.IsinRole call, with IPrincipals.IsInRole, or with declarative authorization checks—a security principal must be present in the thread executing the WCF business logic. If a custom authentication is used in WCF, the security principals must be set in a class that derives from IAuthorizationPolicy, and this custom authorization policy must be configured in WCF.

• ServiceSecurityContext. This identity type, available in the WCF run time, contains all of the security-related objects available in the WCF context. These objects are the user identity and authorization context and policies. The service security context is available on both the service and the client side. In the authorization context, you can extract the claim set associated with a security token, whether it is a certificate, issue token, username, or Windows token. To get the service security context on the client side, you need to use the operation context instead.

Design Strategy for Authentication and Authorization

The following steps help you to develop an authentication and authorization strategy for your application:

• Step 1: Identify resources
• Step 2: Choose an authorization approach
• Step 3: Choose the identities to be used for resource access
• Step 4: Choose an authentication approach

Step 1: Identify Resources

Identify resources that your application needs to expose to clients.

Typical resources include:

• Server resources such as contracts, service metadata, and static resources
• Database resources such as per-user data or application-wide data
• Network resources such as remote file system resources and data from directory stores such as Active Directory

You must also identify the system resources your application needs to access. This is in contrast to resources that are exposed to clients. Examples of system resources include the registry, event logs, and configuration files.

Step 2: Choose an Authorization Approach

When choosing an authorization strategy, first decide if you want to use resource-based or role-based authorization. Next, consider what user store your users belong to.

Resource-based authorization uses 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 to which the user belongs.

If scalability is essential to your application, consider a role-based approach. The following are the most common scenarios for role-based authorization:

• User store is in Windows Active Directory. Consider using role-based authorization with Windows groups for ease of maintenance as both roles and credentials reside in the Active Directory store.
  • If your roles are Windows groups and you want to leverage the Role Manager feature as a consistent way of checking your users’ role membership, consider using WindowsTokenRoleProvider for role authorization.
  • If your application requires finely granular roles, using Windows groups might not be the best option. Instead, consider using ASP.NET roles with role providers such as SqlRoleProvider or AuthorizationStoreRoleProvider.
• User store is in a SQL Server database. Consider using role-based authorization with ASP.NET roles.
  • If your role information is stored in a SQL Server database along with the user information, consider using ASP.NET roles with SqlRoleProvider.
  • If your role information is stored in a custom store, consider using custom role authorization.
• User information is stored in certificates. Consider doing authorization by using the claims provided by the certificate, such as subject name, thumbprint, etc.
  • If the user certificates can be mapped to a Windows account, consider using Windows groups for role authorization.
  • If your certificates can be mapped to a Windows account, and if your application requires finely granular roles, consider using ASP.NET roles with role providers such as SqlRoleProvider or AuthorizationStoreRoleProvider.
• User information is in a custom store. Consider using custom roles for authorization by creating a custom authorization policy.

Consider using a resource-based approach for smaller-scale intranet applications that serve per-user content from resources (such as files) that can be secured with Windows ACLs.

You must also consider whether you want to use impersonation and delegation:

• If your technical requirement is to use the original caller’s identity to access back-end resources on the same computer that is running the service, use impersonation.
• If your technical requirement is to use the original caller’s identity to access back-end resources on computers other than the computer running the service, use delegation.

Step 3: Choose the Identities to Be Used for Resource Access

Choose the identity or identities that should be used to access resources across the various tiers of your application. The identities can be:

• Original caller’s identity. This assumes an impersonation/delegation model in which the original caller’s identity can be obtained and then flowed through each layer of your system. The delegation factor is a key criterion used to determine your authentication mechanism.

• Process identity. This is the default case (without specific impersonation). Local resource access and downstream calls are made using the current process identity. The feasibility of this approach depends on the boundary being crossed, because the process identity must be recognized by the target system.

  This implies that calls are made in one of the following ways:

  • Within the same Windows security domain
  • Across Windows security domains (using trust and domain accounts, or duplicated user names and passwords where no trust relationship exists)

• Service account. This approach uses a (fixed) service account. For example, for database access, this might be a fixed SQL user name and password presented by the component connecting to the database.

Step 4: Choose an Authentication Approach

The choice of an authentication approach is influenced by the nature of your application’s user base, and impersonation/delegation and auditing requirements. The available authentication options depend on both the security mode and the binding.

An authentication strategy is based on available client credentials, networking strategy, system maintenance, and security-level requirements. You can decide on an appropriate authentication strategy by considering the following factors.

Transfer Security

Because WCF authentication options depend on the transfer security mode being used, you should first select the appropriate transfer security mode for your WCF application.

WCF offers two security modes: transport and message. If you are using transport security, you cannot use negotiate, username, or Kerberos direct authentication. If you are using message security, you cannot use Basic or Digest authentication.

Transport Security

Use the following criteria to determine whether you should 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.

Message Security

Use the following criteria to determine whether you should 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 clear text format.
• Binding limitations. Message security does not work with netNamedPipeBinding.
• Secure conversations. Secure conversations only work with message security.
• Authentication limitations. Message security does not work with Basic or Digest authentication.

Bindings

The choice of binding also plays an important role in your authentication options because not all transport or message security authentication options are supported across all bindings.

The following bindings typically work well over the Internet:

• If your service is interacting with WCF clients, use wsHttpBinding because it provides the best WS-* interoperability features, including WS-SecureConversation, WS-Addressing, and WS-AtomicTransaction. The combination of features offered by wsHttpBinding makes for 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 is interacting with WSE clients, you must use customBinding. The service must use a custom binding to be compatible with the August 2004 version of the WS-Addressing specification.

Most of the bindings also work in an intranet scenario, but netTcpBinding provides the best throughput performance. On an intranet, you generally do not need to worry as much about the connection going down as with an Internet connection, so some of the WS-* advantages that are supplied with wsHttpBinding may not be as necessary on an intranet.

Bindings Summary

The following table presents a list of bindings and details each binding’s support for transfer security modes.

Name	None	Transport	Message	Mixed	Both
basicHttpBinding	√ (Default)	√	√	√	X
netTCPBinding	√	√ (Default)	√	√	X
netPeerTCPBinding	√	√ (Default)	√	√	X
netNamedPipeBinding	√	√ (Default)	X	X	X
wsHttpBinding / ws2007HttpBinding	√	√	√ (Default)	√	X
wsFederationHttpBinding / ws2007federationHttpBinding	√	X	√ (Default)	X	X
wsDualHttpBinding	√	X	√ (Default)	X	X
netMsmqBinding	√	√ (Default)	√	X	√

User Store and Credential Management

Your authentication choice will depend greatly on whether you already have a user store in place:

• User store is in Windows Active Directory. Consider using Windows authentication for ease of maintenance as both roles and credentials reside in the Active Directory store. One of the key advantages of Windows authentication is that it enables you to let the operating system take care of credential management. By using Windows authentication with Active Directory, you benefit from a unified identity store, centralized account administration, enforceable account and password policies, and strong authentication that avoids sending passwords over the network.
• User store is in a SQL Server database. Consider using username authentication and configure your application to use the ASP.NET membership feature. You can use username authentication when you need client username/password authentication (versus client computer-level authentication) and the client and service are not in trusted domains; for example, clients are connecting over the Internet.
• User information is stored in certificates. Consider using certificate authentication, which works best when you need computer-level authentication vs. user-level authentication. Client certificates are used to authenticate the client computer connection, but not at a user level. Server certificates are used when you need to authenticate the server credentials to client connections.
• User information is in a custom store. Consider using custom roles for authorization by creating a custom authorization policy.

The following are some other factors to consider when choosing an authentication strategy:

• Determine which client credentials are available and map the credentials to the available WCF authentication methods.
• Determine if the client-service communication is within an intranet only or across the Internet. Integrated Windows authentication does not map well to Internet authentication scenarios.
• Consider total cost of ownership (TCO) when choosing an authentication scheme. Client certificates mapped to each user will be the most time-consuming to maintain. Windows accounts are easiest to maintain because they are built into the operating system, with maintenance tools and security supplied and tested by default.
• Consider whether you need user-level or machine-level authentication. Certificates work well for machine-level authentication.

Key Authentication and Authorization Scenarios

The following scenarios help illustrate best practices for authentication and authorization choices in common WCF deployment scenarios. Use these scenarios to help you choose your authentication and authorization strategy based on your user credential store location and the location of your clients on an intranet or the Internet.

Intranet Scenarios

The most common authentication scenario for intranet applications is where one or more client computers connect to a WCF service. Here the service acts as an intermediary to supply data back to the clients from resources to which it has access to resources on other computers.

A basic assumption for an intranet scenario is that your users have Windows accounts in the server’s domain or in a trusted domain accessible by the server.

Authentication

Use Windows authentication when both the client and service are in trusted domains, such as in an intranet scenario. Windows authentication works with resource-based authorization by default.

Authorization

In an intranet scenario, if you are using Windows Active Directory for authentication, use Windows groups for role authorization in WCF. You can choose this option when you have very coarse or fewer role requirements.

If you have fine-grained role requirements, consider using ASP.NET roles. If your roles are Windows groups, consider using the WindowsTokenRoleProvider for role authorization.

Internet Scenarios

The most common authentication scenario for Internet applications is where one or more client computers connect to a WCF service. Here the service acts as an intermediary to supply data back to the clients from resources to which it has access from resources on other computers within its network.

The basic assumptions for Internet scenarios are:

• Your users do not have Windows accounts in the server’s domain or in a trusted domain accessible by the server.
• Your users have Windows accounts, but cannot access directly over the Internet.
• If you want to access downstream services and resources on the Internet, use the Trusted Subsystem model.

Authentication

Keep in mind the following considerations related to authentication types:

• Username authentication. Use username authentication in the following scenarios:
  • If your users are in a custom store, use username authentication with a custom validator, or use username authentication with a membership provider by implementing a custom membership provider against the custom store.
  • If your users are in a SQL Server database, use username authentication with SqlMembershipProvider.
  • If your users are in Active Directory, use username authentication mapped to Windows.
• Certificate authentication. Use certificate authentication in the following scenarios.
  • If your service needs to be consumed by partner (B2B) applications. In this scenario, the client certificates can authenticate a machine account or multiple users to a WCF service.
  • If you have initial certificate investment.
  • If your users are in Active Directory, but you cannot use Windows authentication, use certificate authentication and map the certificates to a Windows account.

Authorization

You can implement role authorization either by using declarative or imperative authorization as follows:

• If you are using username authentication with SqlMembershipProvider, use SqlRoleProvider for role authorization.
• If you are using username authentication mapped to Windows, use WindowsTokeRoleProvider for role authorization using Windows groups.
• If you are using username authentication mapped to Windows, an AzMan policy store in an XML file, in Active Directory, or in Active Directory Application Mode (ADAM), consider using AuthorizationStoreRoleProvider for role authorization.
• If you are using certificate authentication with certificates mapped to Windows accounts, use WindowsTokeRoleProvider for role authorization using Windows groups.
• If you are using certificate authentication with certificates mapped to Windows accounts, an AzMan policy store in an XML file, in Active Directory, or in ADAM, consider using AuthorizationStoreRoleProvider for role authorization.

Additional Resources

• For more information on authorization, see Authorization.
• For more information on authentication, see Authentication.
• For more information, see the list of related How To articles in the How To Index.
• For more general information, see WCF Security Questions and Answers.