Selecting a Credential Type

Credentials are the data Windows Communication Foundation (WCF) uses to establish either a claimed identity or capabilities. For example, a passport is a credential a government issues to prove citizenship in a country or region. In WCF, credentials can take many forms, such as user name tokens and X.509 certificates. This topic discusses credentials, how they are used in WCF, and how to select the right credential for your application.

In many countries and regions, a driver’s license is an example of a credential. A license contains data that represents a person's identity and capabilities. It contains proof of possession in the form of the possessor's picture. The license is issued by a trusted authority, usually a governmental department of licensing. The license is sealed, and can contain a hologram, showing that it has not been tampered with or counterfeited.

Presenting a credential involves presenting both the data and proof of possession of the data. WCF supports a variety of credential types at both the transport and message security levels. For example, consider two types of credentials supported in WCF: user name and (X.509) certificate credentials.

For the user name credential, the user name represents the claimed identity and the password provides proof of possession. The trusted authority in this case is the system that validates the user name and password.

With an X.509 certificate credential, the subject name, subject alternative name or specific fields within the certificate can be used as claims of identity, while other fields, such as the Valid From and Valid To fields, specify the validity of the certificate.

Transport Credential Types

The following table shows the possible types of client credentials that can be used by a binding in transport security mode. When creating a service, set the ClientCredentialType property to one of these values to specify the type of credential that the client must supply to communicate with your service. You can set the types in either code or configuration files.

Setting	Description
None	Specifies that the client does not need to present any credential. This translates to an anonymous client.
Basic	Specifies basic authentication for the client. For additional information, see RFC2617—HTTP Authentication: Basic and Digest Authentication.
Digest	Specifies digest authentication for the client. For additional information, see RFC2617—HTTP Authentication: Basic and Digest Authentication.
Ntlm	Specifies NT LAN Manager (NTLM) authentication. This is used when you cannot use Kerberos authentication for some reason. You can also disable its use as a fallback by setting the AllowNtlm property to false, which causes WCF to make a best-effort to throw an exception if NTLM is used. Note that setting this property to false may not prevent NTLM credentials from being sent over the wire.
Windows	Specifies Windows authentication. To specify only the Kerberos protocol on a Windows domain, set the AllowNtlm property to false (the default is true).
Certificate	Performs client authentication using an X.509 certificate.
Password	User must supply a user name and password. Validate the user name/password pair using Windows authentication or another custom solution.

Message Client Credential Types

The following table shows the possible credential types that you can use when creating an application that uses message security. You can use these values in either code or configuration files.

Setting	Description
None	Specifies that the client does not need to present a credential. This translates to an anonymous client.
Windows	Allows SOAP message exchanges to occur under the security context established with a Windows credential.
Username	Allows the service to require that the client be authenticated with a user name credential. Note that WCF does not allow any cryptographic operations with user names, such as generating a signature or encrypting data. WCF ensures that the transport is secured when using user name credentials.
Certificate	Allows the service to require that the client be authenticated using an X.509 certificate.
Issued Token	A custom token type configured according to a security policy. The default token type is Security Assertions Markup Language (SAML). The token is issued by a secure token service. For more information, see Federation and Issued Tokens.

Negotiation Model of Service Credentials

Negotiation is the process of establishing trust between a client and a service by exchanging credentials. The process is performed iteratively between the client and the service, so as to disclose only the information necessary for the next step in the negotiation process. In practice, the end result is the delivery of a service's credential to the client to be used in subsequent operations.

With one exception, by default the system-provided bindings in WCF negotiate the service credential automatically when using message-level security. (The exception is the BasicHttpBinding, which does not enable security by default.) To disable this behavior, see the NegotiateServiceCredential and NegotiateServiceCredential properties.

Note:
When SSL security is used with .NET Framework 3.5 and later, a WCF client uses both the intermediate certificates in its certificate store and the intermediate certificates received during SSL negotiation to perform certificate chain validation on the service's certificate. .NET Framework 3.0 only uses the intermediate certificates installed in the local certificate store.

Out-of-Band Negotiation

If automatic negotiation is disabled, the service credential must be provisioned at the client prior to sending any messages to the service. This is also known as an out-of-band provisioning. For example, if the specified credential type is a certificate, and automatic negotiation is disabled, the client must contact the service owner to receive and install the certificate on the computer running the client application. This can be done, for example, when you want to strictly control which clients can access a service in a business-to-business scenario. This out-of-band-negotiation can be done in e-mail, and the X.509 certificate is stored in Windows certificate store, using a tool such as the Microsoft Management Console (MMC) Certificates snap-in.

Note:

The ClientCredentials property is used to provide the service with a certificate that was attained through out-of-band negotiation. This is necessary when using the BasicHttpBinding class because the binding does not allow automated negotiation. The property is also used in an uncorrelated duplex scenario. This is a scenario where a server sends a message to the client without requiring the client to send a request to the server first. Because the server does not have a request from the client, it must use the client's certificate to encrypt the message to the client.

Setting Credential Values

Once you select a security mode, you must specify the actual credentials. For example, if the credential type is set to "certificate," then you must associate a specific credential (such as a specific X.509 certificate) with the service or client.

Depending on whether you are programming a service or a client, the method for setting the credential value differs slightly.

Setting Service Credentials

If you are using transport mode, and you are using HTTP as the transport, you must use either Internet Information Services (IIS) or configure the port with a certificate. For more information, see Transport Security Overview and HTTP Transport Security.

To provision a service with credentials in code, create an instance of the ServiceHost class and specify the appropriate credential using the ServiceCredentials class, accessed through the Credentials property.

Setting a Certificate

To provision a service with an X.509 certificate to be used to authenticate the service to clients, use the SetCertificate method of the X509CertificateRecipientServiceCredential class.

To provision a service with a client certificate, use the SetCertificate method of the X509CertificateInitiatorServiceCredential class.

Setting Windows Credentials

If the client specifies a valid user name and password, that credential is used to authenticate the client. Otherwise, the current logged-on user's credentials are used.

Setting Client Credentials

In WCF, client applications use a WCF client to connect to services. Every client derives from the ClientBase class, and the ClientCredentials property on the client allows the specification of various values of client credentials.

Setting a Certificate

To provision a service with an X.509 certificate that is used to authenticate the client to a service, use the SetCertificate method of the X509CertificateInitiatorClientCredential class.

How Client Credentials Are Used to Authenticate a Client to the Service

Client credential information required to communicate with a service is provided using either the ClientCredentials property or the Credentials property. The security channel uses this information to authenticate the client to the service. Authentication is accomplished through one of two modes:

• The client credentials are used once before the first message is sent, using the WCF client instance to establish a security context. All application messages are then secured through the security context.

• The client credentials are used to authenticate every application message sent to the service. In this case, no context is established between the client and the service.

Established Identities Cannot Be Changed

When the first method is used, the established context is permanently associated with the client identity. That is, once the security context has been established, the identity associated with the client cannot be changed.

Note:

There is a situation to be aware of when the identity cannot be switched (that is, when establish security context is on, the default behavior). If you create a service that communicates with a second service, the identity used to open the WCF client to the second service cannot be changed. This becomes a problem if multiple clients are allowed to use the first service and the service impersonates the clients when accessing the second service. If the service reuses the same client for all callers, all calls to the second service are done under the identity of the first caller that was used to open the client to the second service. In other words, the service uses the identity of the first client for all its clients to communicate with the second service. This can lead to the elevation of privilege. If this is not the desired behavior of your service, you must track each caller and create a new client to the second service for every distinct caller, and ensure that the service uses only the right client for the right caller to communicate with the second service.

For more information about credentials and secure sessions, see Security Considerations for Secure Sessions.

See Also

Reference

System.ServiceModel.ClientBase
System.ServiceModel.ClientBase.ClientCredentials
System.ServiceModel.Description.ClientCredentials.ClientCertificate
System.ServiceModel.BasicHttpMessageSecurity.ClientCredentialType
System.ServiceModel.HttpTransportSecurity.ClientCredentialType
System.ServiceModel.MessageSecurityOverHttp.ClientCredentialType
System.ServiceModel.MessageSecurityOverMsmq.ClientCredentialType
System.ServiceModel.MessageSecurityOverTcp.ClientCredentialType
System.ServiceModel.TcpTransportSecurity.ClientCredentialType
System.ServiceModel.Security.X509CertificateInitiatorClientCredential.SetCertificate(System.Security.Cryptography.X509Certificates.StoreLocation,System.Security.Cryptography.X509Certificates.StoreName,System.Security.Cryptography.X509Certificates.X509FindType,System.Object)
System.ServiceModel.Security.X509CertificateInitiatorClientCredential.SetCertificate(System.String,System.Security.Cryptography.X509Certificates.StoreLocation,System.Security.Cryptography.X509Certificates.StoreName)
System.ServiceModel.Security.X509CertificateInitiatorServiceCredential.SetCertificate(System.String,System.Security.Cryptography.X509Certificates.StoreLocation,System.Security.Cryptography.X509Certificates.StoreName)

Concepts

Programming WCF Security
HTTP Transport Security

Other Resources

Security Concepts
Securing Services and Clients