Chapter 5 – Authentication, Authorization and Identities in WCF
- J.D. Meier, Carlos Farre, Jason Taylor, Prashant Bansode, Steve Gregersen, Madhu Sundararajan, Rob Boucher
- Understand the WCF Authentication options of “Message”, “Transport”, “Mixed” and “both” Security
- Understand the WCF Authorization options based on “role”, “identity” and “Resource”
- Understand the WCF Identities and the meaning of “process identity”, “security principle”, and “ServiceSecurityContext”
- Understand common implementation models using specific Authentication, Authorization and Identity choices
Use this chapter to create a strategy for authentication and authorization in your WCF service. Based on your deployment scenario, including credential store, location of clients on the Internet or intranet, and authorization constraints, you will choose an appropriate authentication and authorization option for your service. Use authentication to positively identify the client consuming your service. Use authorization to restrict access to resources or make business decisions based upon user roles.
Client Authentication and Service Authentication
When considering authentication you may be used to thinking primarily of the client identity, however, in WCF when we refer to authentication it’s typically 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 used depend largely upon the client authentication scheme chosen. Typically, if you are using non Windows client authentication like username and certificates, then a service certificate is used for both service authentication and message protection. If you are using Windows client authentication, then Windows credentials of the process identity can be used for both service authentication and message protection.
Transfer Security Modes
Your WCF authentication options depend upon 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 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 credentials 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 using the transport layer. In other words user credentials are transport dependent which allows fewer authentications options compared to Message security.
- Mixed Security. When using mixed security, you get the best of both worlds; transport security provides integrity and confidentiality of the messages, while the user credentials and claims are encapsulated in every message as in case of message security. This provides you options to use a variety of user credentials that are not possible with strict transport security mechanisms and leverage the transport security’s performance.
- Both Security. When using this option the user credentials and claims are transferred using both transport layer and at message level. Also the message protection is provided by both transport layer and at message level. This is not a common scenario and only bindings supporting MSMQ protocol supports this security mode.
Your choice of binding will also play an important role in the authentication options, as not all 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 mode:
- None. When using this option WCF service does not authenticate the callers, this is not the recommended option from security perspective. You should avoid using this option wherever possible.
- Basic. This option is available with http protocol only and the client is authenticated using username and password against Active Directory. The client credentials are transported using Base64 encode string, which is literally like clear string, therefore it is not the most secure option. The service is authenticated by the SSL certificate used for secure communication.
- NTLM. This option is available with http protocol only. The client is authenticated using a challenge-response scheme against Windows accounts. The NTLM option is well suited for a workgroup environment. NTLM authentication is more secure than Basic authentication. The service is authenticated using an SSL certificate.
- Windows. The Windows option tells the WCF service to use Kerberos when in a domain or NTLM when deployed in a workgroup environment. This option uses a Windows token presented by the caller to authenticate against Active Directory. This is the most secure option compared to Basic or NTLM. The Service is authenticated 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 which 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 such as in the case of B2B scenarios. The service is authenticated with the service certificate or 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 mode:
- None. When using this option WCF service does not authenticate the callers, this is not the recommended option from security perspective. You should avoid using this option wherever possible.
- Windows. When using this option WCF service uses Kerberos when in a domain else NTLM when deployed in workgroup environment. This option uses windows token presented by the caller to authenticate against the Active Directory. Service is authenticated using the windows credentials of the process identity.
- UserName. When using this option, the caller provides username and password to the service and the service can authenticate against windows, or use membership providers like SqlMembershipProvider or use custom validator to validate against the custom store. You should choose this option only when windows authentication is not possible. The service is authenticated with a service certificate.
- Certificate. When using this option, the caller presents a X.509 client certificate, WCF service looks up the certificate information on the host side and validates it (peer trust) or trusts the issuer (Chain Trust) of the client certificate. This option should be used when Windows Authentication is not possible for some reason or in case of B2B scenarios. Service is authenticated with Service Certificate.
- Issue Token. When using this option the client and the service depends on the Secure Token Service to issue tokens that the client and service trusts. CardSpace is a typical example of STS.
Authorization Options in WCF
WCF supports three basic authorization approaches as discussed below:
- 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 to role-based authorization. Identity Model enables you to manage claims and policies 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 upon the claims provided by the client the service can 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. Individual resources are secured using Windows 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 represents 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.
Roles Based Authorization Options in WCF
In WCF you have the following options for role based authorization:
- Windows Groups. For WCF services and clients deployed in the same windows domain you can use Windows groups for roles authorization. Typically this option is suitable when you have a small number of coarse role requirements.
- ASPNET Roles. Use ASPNET roles if you have fine grained roles requirement, 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 the SqlRoleProvider for roles authorization.
- WindowsTokenRoleProvider. If your roles are Window groups, and you want to leverage the role manager feature of consistent way for you to check the role membership of your users, regardless of the underlying data store, consider using the WindowsTokenRoleProvider for roles authorization. .
- AuthorizationStoreRoleProvider. If your roles information is stored using AzMan policy store in an XML file, in Active Directory, or in Active Directory Application Mode (ADAM), consider using the AuthorizationStoreRoleProvider for roles authorization.
- Custom Roles. If your roles information is stored in a custom store such as a SQL Server database, create a custom authorization policy to authorize your users.
: It’s recommended to implement a custom role provider, using role manager feature, for your custom role store rather than using the custom roles option.
Imperative authorization supports fine-grained authorization choices based upon business logic. Imperative role-based authorization is written into your code and processed at runtime. Imperative security is useful when the resource to be accessed or action to be performed is not known until run time or when finer-grained access control beyond the level of a code method is required.
Imperative Check Example
The following is an example of an Imperative check using the ASP.NET role provider:
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. 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. Since 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 ASPNET role provider or windows groups.
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 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 out of scope of this guide.
For more information see, “Managing Claims and Authorization with the Identity Model” at http://msdn.microsoft.com/en-us/library/ms729851.aspx
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. The approach starts to break down 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.
The resource based approach relies upon 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 mode
The Trusted Subsystem Model
With this model, the WCF service uses a fixed identity to access downstream services and resources.
A variation on this model may use a fixed identity per-role in order to map multiple users into a set of permissions on a downstream resource.
The security context of the original caller does not flow through the service at the operating system level, although the application may choose to flow the original caller's identity at the application level. It may need to do so 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 the following:
- Authenticate users
- Map users to roles
- Authorize based on role membership
- Access 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.
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.
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 a couple of 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 you’re designing your authentication and authorization strategies, you need to consider the following identities:
- Process identity. Identity of the process hosting WCF service. When the WCF service is hosted in IIS, then typically it is NETWORK SERVICE by default. The process identity is important because it says what Windows resources and backend service can access, when the WCF service is not impersonating the original caller. The process identity also needs access to certificates private keys to provide for message security or transport security with netTcpBinding if certificate is used to protect the transport.
- Security principal. In the executing thread, there is a security principal that contains the user identity and roles associated with it. 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 Roles.IsinRole call or with IPrincipals.IsInRole or with declarative authorization checks a security principals must be present in the thread executing 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 is a type available in WCF runtime which contains all the objects related with context of security in WCF. The objects are the user identity, authorization context / polices. The service security context is available both on service and client side. In authorization context you can extract the claim set associated with a security token, be a certificate, issue token, user name or windows token. If you want 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 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 that 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 deciding an authorization strategy, first decide if you want to use resource based or role based authorization; secondly 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 upon the group a user is in.
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 Windows Active Directory. Consider using role-based authorization with Windows groups, its easy to maintain as both roles and credentials in the Active Directory store.
- If your roles are Window groups, and you want to leverage the role manager feature of consistent way for you to check the role membership of your users, consider using the WindowsTokenRoleProvider for roles authorization.
- If your application has granular roles requirement, using windows groups might not be the best option, consider using ASPNET roles with role providers like SqlRoleProvider or AuthorizationStoreRoleProvider.
- User Store is SQL server database. Consider using roles-based authorization with ASPNET roles.
- If your roles information is stored in SQL server database along with the user information, consider using ASPNET roles with SqlRoleProvider.
- If your roles information is stored in custom store, consider using custom roles authorization.
- User information is stored in certificates. Consider doing authorization using the claims provided by the certificate, like subject name, thumbprint etc.
- If the user certificates can be mapped to windows account, you can consider using windows groups for roles authorization.
- If your certificates can be mapped to windows account, and if your application has granular roles requirement, consider using ASPNET roles with role providers like SqlRoleProvider or AuthorizationStoreRoleProvider.
- User information is in 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 business requirement is to use the original caller’s identity to access back-end resources on the same computer that is running the service, then use Impersonation.
- If your business requirement is to use the original caller’s identity to access back-end resources on the computers other than the computer running the service, then use Delegation.
Step 3 – Choose the Identities 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 identity can be obtained and then flowed through each layer of your system. The delegation factor is a key criteria 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 authentication approach is influenced by the nature of your application's user base, and your application's impersonation/delegation and auditing requirements. The available authentication options depend upon both security mode and the binding.
An authentication strategy is based upon available client credentials, networking strategy, system maintenance, and security level requirements. You can decide on an authentication strategy by considering the following factors.
In WCF the authentication options depends upon the transfer security mode being used. So first select the appropriate transfer security mode for your WCF application.
WCF offers two security modes: Transport
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.
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 the wsDualHttpBinding.
- Authentication limitations. Transport security does not work with negotiation, username or Kerberos direct authentication.
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 message while leaving other parts in clear-text.
- Binding limitations. Message security does not work with the netNamedPipeBinding.
- Secure conversations. Secure conversation only works with message security.
- Authentication limitations. Message security does not work with basic or digest authentication.
The choice of binding also plays an important role in your authentication options, as not all the transport or message security authentication options are supported across all the bindings.
The following bindings typically work well over the Internet:
- If your service is interacting with WCF clients, use the wsHttpBinding. 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 ASMX clients, you must use the basicHttpBinding. It is the only WCF binding that supports ASMX clients.
- Clients and services that require full-duplex communication should use the wsDualHttpBinding. It is the only binding that supports full-duplex.
- If your service is interacting with WSE clients, you must use the customBinding. The service must use a custom binding to be compatible with the August 2004 version of the WS-Addressing.
Most of the bindings work in the Intranet, but the netTcpBinding
will provide 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 the wsHttpBinding
may not be as necessary on an Intranet.
The following table shows the list of bindings and its support for transfer security modes.
|Name ||None ||Transport ||Message ||Mixed ||Both|
|basicHttpBinding ||v (Default) ||v ||v ||v ||X|
|netTCPBinding ||v ||v (Default) ||v ||v ||X|
|netPeerTCPBinding ||v ||v (Default) ||v ||v ||X|
|netNamedPipeBinding ||v ||v (Default) ||X ||X ||X|
|wsHttpBinding / ws2007HttpBinding ||v ||v ||v (Default) ||v ||X|
|wsFederationHttpBinding /wsFederation2007HttpBinding ||v ||X ||v (Default) ||X ||X|
|wsDualHttpBinding ||v ||X ||v (Default) ||X ||X|
|netMsmqBinding ||v ||v (Default) ||v ||X ||v|
User Store and Credential Management
Your authentication choice will depend heavily on whether you already have a user store in place:
- User store is Windows Active Directory. Consider using Windows authentication as it is easy to maintain as both roles and credentials 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 avoid sending passwords over the network.
- User Store is 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 (vs. 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 custom store. Consider using custom roles for authorization by creating a custom authorization policy.
The following are some of the 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 Intranet-only or across the Internet. Integrated Windows authentication does not map well to Internet authentication scenarios.
- Consider TCO when deciding upon an authentication scheme. Client certificates mapped to each user will be most time consuming to maintain. Windows accounts are easiest to maintain because they are built in to 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-practice for authentication and authorization choices in common WCF deployment scenarios. Use these scenarios to help you choose your authentication and authorization strategy based upon your user credential store location and the location of your clients on the Intranet or Internet.
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.
The basic assumptions for Intranet scenarios are:
- Your users have Windows accounts in the server's domain or in a trusted domain accessible by the server
Use Windows authentication when both the client and service are in trusted domains, such as in an Intranet scenario. Windows authentication will work with resource-based authorization by default
In an Intranet, if you are using Windows Active directory for authentication then use Windows Groups for role authorization in WCF. You can choose this option when you have very coarse or fewer roles requirement.
If you have fine grained roles requirement, consider using ASPNET roles. If your roles are Window groups consider using the WindowsTokenRoleProvider
for roles authorization.
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 for 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 in internet, use Trusted Subsystem model.
. Use username authentication in the following scenarios.
- If your users are in custom store, use username authentication with custom validator or username authentication with membership provider, by implementing custom membership provide against the custom store.
- If your users are in SQL server database, use username authentication with SqlMembershipProvider.
- If your users are in Active Directory, use username authentication mapped to windows.
. 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, you can use certificate authentication.
- If your users are in Active Directory, but you cannot use Windows authentication, use certificate authentication and map the certificates to Windows account.
You can implement roles authorization either by using declarative or imperative authorization.
- If you are using Username authentication with SqlMembershipProvider, use SqlRoleProvider for roles authorization.
- If you are using Username authentication mapped to Windows, use WindowsTokeRoleProvider for roles authorization using Windows groups.
- If you are using Username authentication mapped to Windows, use AzMan policy store in an XML file, in Active Directory, or in Active Directory Application Mode (ADAM), consider using the AuthorizationStoreRoleProvider for roles authorization.
- If you are using Certificate Authentication with certificates mapped to Windows accounts, use WindowsTokeRoleProvider for roles authorization using Windows groups.
- If you are using Certificate Authentication with certificates mapped to Windows accounts, use AzMan policy store in an XML file, in Active Directory, or in Active Directory Application Mode (ADAM), consider using the AuthorizationStoreRoleProvider for roles authorization.