The clientCredentialType Setting
Authentication in WCF is configured through the clientCredentialType attribute nested inside the <transport> or <message> element of a binding's <security> block, and the valid values differ depending on which one you're configuring. Transport-level clientCredentialType options typically include None, Basic, Digest, Ntlm, Windows, and Certificate, mirroring HTTP authentication schemes or TLS client certificate auth. Message-level clientCredentialType options include None, Windows, UserName, Certificate, and IssuedToken, the last of which delegates authentication to an external Security Token Service (STS) using WS-Trust — the foundation of federated identity scenarios. Picking the right combination requires knowing both your security mode (Transport, Message, or TransportWithMessageCredential) and which credential type is actually supported at that layer for your chosen binding.
Cricket analogy: clientCredentialType is like the specific method used to verify a player's identity before they walk out to bat — sometimes it's a simple team-sheet check (Basic), sometimes a full accreditation badge scan (Windows), and choosing the wrong method for the situation, like using a T20 rule in a Test match, breaks the process.
Windows and Certificate Authentication
Windows authentication (clientCredentialType="Windows") is the simplest choice on a domain-joined intranet: WCF uses the caller's existing Kerberos ticket or NTLM handshake, requiring no extra credential management code, and it pairs naturally with netTcpBinding Transport security for service-to-service calls between trusted machines. Certificate authentication instead requires each client to possess an X.509 certificate with a private key; the client presents this certificate during the security handshake, the service validates it against a trusted certificate authority (or an explicit peer/trust list), and the service can also extract claims like the certificate's subject name for authorization decisions. Certificate auth is strong because it doesn't depend on a shared secret being transmitted at all, but it introduces real operational overhead: certificate issuance, distribution, renewal before expiry, and revocation checking (CRL or OCSP) all become part of the deployment pipeline.
Cricket analogy: Windows auth is like a domestic player automatically recognized by their state cricket association ID without extra paperwork (already-trusted domain), while certificate auth is like an overseas player needing an ICC-issued accreditation certificate verified before every international series.
UserName and Federated (IssuedToken) Authentication
UserName credential type sends a plain username and password inside the SOAP message (never safe on its own, which is why it is almost always paired with TransportWithMessageCredential so the channel is already encrypted via HTTPS); on the service side, WCF requires you to implement a custom UserNamePasswordValidator by overriding UserNamePasswordValidator.Validate() and wiring it into the service's serviceCredentials behavior, since WCF has no built-in username/password store beyond a thin Windows-account passthrough. IssuedToken authentication is the most flexible and most complex: rather than authenticating directly against the service, the client first requests a security token from a separate Security Token Service using WS-Trust, and then presents that signed token to the WCF service, which validates it was issued by a trusted STS — this is the pattern behind claims-based and federated identity scenarios where a service trusts an external identity provider rather than managing credentials itself.
Cricket analogy: UserName auth is like a scorer manually checking a player's name against a handwritten team sheet (works, but fragile without a locked scoring room around it), while IssuedToken is like trusting the ICC's centrally issued player accreditation that was already verified by a separate authority before the match.
public class SimpleUserNameValidator : UserNamePasswordValidator
{
public override void Validate(string userName, string password)
{
if (string.IsNullOrEmpty(userName) || !userRepository.IsValid(userName, password))
{
throw new FaultException("Invalid username or password.");
}
}
}
// In ServiceHost setup:
host.Credentials.UserNameAuthentication.UserNamePasswordValidationMode =
UserNamePasswordValidationMode.Custom;
host.Credentials.UserNameAuthentication.CustomUserNamePasswordValidator =
new SimpleUserNameValidator();Never configure clientCredentialType="UserName" without pairing it with a security mode that already encrypts the channel (TransportWithMessageCredential or full Message security with encryption). Sent alone, the username and password travel as near-plaintext inside the SOAP body.
- clientCredentialType is configured separately under <transport> and <message>, with different valid values for each.
- Windows authentication reuses Kerberos/NTLM and needs no extra credential code on a domain-joined network.
- Certificate authentication uses X.509 certificates and avoids transmitting shared secrets, at the cost of issuance/renewal overhead.
- UserName authentication requires a custom UserNamePasswordValidator and must always run over an already-encrypted channel.
- IssuedToken delegates authentication to an external Security Token Service via WS-Trust, enabling federated identity.
- The chosen clientCredentialType must be compatible with the binding's security mode or the endpoint will fail to open.
- Weak credential types like plain UserName should never be used without transport-level or message-level encryption already active.
Practice what you learned
1. Which clientCredentialType value requires implementing a custom UserNamePasswordValidator on the service?
2. What authentication protocol underlies IssuedToken credential type?
3. Why is certificate authentication considered stronger than a shared-secret approach like plain UserName?
4. What must accompany clientCredentialType="UserName" to avoid sending credentials in near-plaintext?
Was this page helpful?
You May Also Like
WCF Security Modes
An overview of the five security modes WCF bindings expose — None, Transport, Message, TransportWithMessageCredential, and TransportCredentialOnly — and when to use each.
WCF Certificates
How X.509 certificates are configured, stored, and used in WCF for service authentication, client authentication, and message encryption.
Securing WCF Endpoints
Practical, end-to-end guidance for locking down a WCF service endpoint — binding choice, behaviors, authorization, and operational hardening.
Related Reading
Related Study Notes in Microsoft Technologies
Browse all study notesWindows 10 / UWP Development Study Notes
.NET · 30 topics
Microsoft TechnologiesWindows Batch Scripting Study Notes
Batch · 30 topics
Microsoft TechnologiesMFC (Microsoft Foundation Classes) Study Notes
C++ · 30 topics
Microsoft TechnologiesSilverlight Study Notes
.NET · 30 topics
Microsoft TechnologiesXAML Study Notes
.NET · 30 topics
Microsoft TechnologiesWPF (Windows Presentation Foundation) Study Notes
.NET · 30 topics