Fast Concurrent Binding Overview

One of the things I alluded to in my post that highlighted the differences in capabilities between the ADSI-based System.DirectoryServices (SDS) namespace and the raw LDAP-based System.DirectoryServices.Protocols (SDS.P) was the ability to access a feature called Fast Concurrent Binding (FCB).

FCB is a feature available in Active Directory 2003 (and later) and in ADAM.  To explain it, first let’s cover what happens with a “regular” bind operation in LDAP against AD or ADAM.  With a normal bind, the user’s credentials are presented to the LDAP server, either in plaintext format or via the Windows security model if using a secure binding protocol.  The server then attempts to authenticate these credentials.  If the credentials are accepted, then the server builds a Windows token for the user which will be used to for performing security checks on future operations and changes the state of the current LDAP connection to an authenticated state so that future requests will continue to use the newly established security context and this operation is not repeated.  This is the main reason why LDAP connections are stateful.

FCB eliminates two parts of this equation.  It authenticates the user’s credentials, but it does not build a Windows token for the user and the connection state stays anonymous.  As such, the bind operation will give you an “up/down” result based on whether the user’s name and password were valid, but it won’t let you do anything else with that connection such as perform searches, except as an anonymous user (which is pretty limited by default in AD 2003 and ADAM).

The big upside of FCB is that the bind operation is MUCH faster than a normal bind because the really expensive operation, expanding the user’s group membership to build the token, is eliminated.  Hence the name fast concurrent binding.^*

The concurrent part comes from the fact that multiple users can be authenticated on the same LDAP connection simultaneously without worrying about changing the authenticated state of the connection, so the expense of setting up and tearing down the associated socket can also be eliminated.  This makes it potentially even faster.

The big downside with FCB is that it only supports LDAP simple bind, not SASL, and simple bind does not have a built in mechanism for protecting the credentials on the wire like the various SASL mechanisms do.  As such, it is never safe to use FCB unless some form of transport security is used such as SSL or IPSEC!

When to Use Fast Concurrent Binding

Do use FCB when your application is doing pure authentication of credentials via LDAP.  An example of this might be in a web-based application that uses AD or ADAM as a user store and does LDAP authentication.  If you just need a “yes/no” vote as to whether a username/password combo is good, FCB will give you the best performance and may add a significant scalability increase to your application as a result. 

Do not use FCB if you need to authenticate and then perform operations against the directory on the user’s behalf (a delegation scenario from the architectural perspective, although not necessarily using Windows Kerberos delegation features to implement it).  Since the connection state does not change to “authenticated”, the user’s credentials will not be used to perform subsequent operations and you won’t get what you want.

An obvious place where you might want to use FCB would be in something like the ActiveDirectoryMembershipProvider in ASP.NET 2.0.  My understanding is that the development already thought about this and tried to add this support already.  Thus, you may already have this and not even know it!

Another obvious place for this to be used would be in ADFS for authenticating users in the ADAM store and potentially with users in the AD store as well when used with the Federation Service Proxy (which accepts credentials via a forms or basic auth interface in plaintext form).  As of this writing, I do not believe that ADFS is taking advantage of this feature (or and SDS.P capabilities for that matter).  Note to product team…

A Note on ADSI/SDS and Fast Concurrent Binding

Hey Joe, I see that ADSI and SDS have an AuthenticationTypes flag called FastBind.  Can’t I just use that to get FCB?  Why are you telling me this requires SDS.P?

The answer here is “no”, they are not the same thing, despite their unfortunately similar names!  FastBind in ADSI/SDS actually has nothing to do with the bind operation per say, but has to do with what ADSI does after the bind when you go to access an object.  With FastBind NOT set (the default), ADSI does a base-level search to the object you tried to access to read its objectClass attribute before it executes any other searches to load the property cache and such.  ADSI uses this information to determine which ADSI interfaces to make available.  By default, you get the core interfaces like IADs, but you don’t necessarily get one of the “persistent object” interfaces like IADsUser or IADsGroup unless ADSI knows that it is a user or group.  Without those interfaces, you loose access to members like SetPassword and Add (for group membership additions). 

The reason FastBind is called “Fast” is that this initial search is done in addition to any searches to load the property cache, which generally means that at least two base-level searches to the directory will be required to load any given ADSI object (as you normally use the property cache for something!).  All these extra searches add up to lots of network chatter and can slow certain types of operations to a crawl. 

Note that FastBind is an ADSI/SDS thing though and has no bearing on how things work at the lower level LDAP level, as this notion of the persistent object interfaces and property caches is an ADSI abstraction layer.

How to Implement Fast Concurrent Binding in SDS.P

There really isn’t too much too this.  All you really need to do is turn this option on BEFORE your LdapConnection actually connects to the directory for the first time and you are all set.  Briefly, the code looks something like:

_authConnect.SessionOptions.FastConcurrentBind();

In order to get a more thorough look, I’ll simply point you to the LdapAuth.cs class from our book’s website in ch 12 of the Full Samples to see this in real usage. 

Important Warning
There is a bug in the actual implementation printed in the book (first printing at least; assuming there will be more than one and we actually fix it ?).  A small last minute blunder caused the defect.  Please use the version in the full samples from the website.

There are some important caveats as well:

• Both the server and client must support FCB.  In the book sample, we actually check the server first via its supportedCapabilities RootDSE attribute to find the specific OID.  On the client requirements, be aware the SDS.P requires the client code to be run on Windows 2003 server or higher.  XP and below does not support this!  Our code tries to handle this gracefully, but you should plan ahead anyway.
• You are using simple bind, so you need plaintext usernames and passwords and must use a user name syntax supported by simple bind.  For AD, this is NT Account Name (domain\user), UPN or DN.  For ADAM, this is generally UPN or DN, but actually could be a lot of things like displayName as well.  Ch 3 of our book goes into more detail.
• This is simple bind.  You MUST encrypt the network traffic with SSL or something!

Conclusion

We already covered most of this information in our book, but I don’t think we hit all of these things in as much detail as I have covered here.  Additionally, not all of you will buy the book and this isn’t in the free chapter, and we want you to be successful with this somewhat mysterious feature, regardless.  Happy fast(er) binding!

* Of course, with all performance optimizations, always measure and never assume.  Premature optimization is one of the seven deadly sins of software engineering, yada-yada-yada.

Let's show some love for Andale Mono (my favorite coding font).

Edit 8/14/2006: Yikes!  It appears Andale Mono is not a freeware font as I was led to believe by the person who gave it to me.  These guys own it and would prefer that you bought it.  Oh well...

In a newsgroup thread today, William Stacey taught me some stuff about salted password hashes stored in a traditional relational database.  Apparently, this is not the way the cool kids do it anymore (although MS still has plenty of guidance suggesting to use this approach).  Apparently, the those in the know use an implementation like Secure Remote Password (SRP-6a).

William couldn't find a .NET implementation, so he built one!  You can find his implementation here.

So, let's say you are doing some ADFS programming and you see this big cookie being passed to your app called _WebSsoAuth.  Let's say your app is a token app, so the only trace of the claims from the federation is in the resulting Windows token with the user and group info (see here if you are not certain how to see this info).  Let's ignore for a second that it is possible to have a hybrid token/claims app that uses the IIS web service extension to build a Windows token for you, but also uses the HTTP Module to build a SingleSignOnIdentity so you can read the claims (this is possible!).  You are just really curious about what's in that cookie.  It looks like it contains a big blob of Base64 data.  Can we see the actual SAML token somehow?

Sadly, the answer is "no", not really.

Digging a Little Deeper

At this point, you may choose to stop reading or explore the futility in this a little further.

So, the data is clearly Base64-encoded, but a quick decode of it doesn't give us any angle brackets.  We wonder what gives, so we open up Reflector and start looking at the reverse engineered source code to find out what's up.

As we dig around, we soon discover that the WebSsoAuthenticationModule uses a class called LargeCookieWriter to read the data and decode it.  Interestingly, the Decode method actually calls into an unmanaged code function in another DLL installed by ADFS to do some sort of decompression/unmunging.  Interesting...I wonder what sort of magic goes on in there?  Must be cool if it had to be unmanaged C++!  But anyway, we are not deterred by this as a little reflection code allows us call LargeCookieWriter as well without any details of what's going on down deep.

So, we call the Decode method and we get a string back with readable characters.  Sort of.  Some of the data in there looks like our claims (I see a familar UPN and email address for example), but some of it is Base64 and none of it is XML.  Where's my SAML token???

At this point it gets a little wacky, as apparently there is some sort of XML in this data somehow as ADFS has implemented its own set of XmlReader classes to read this stuff.  This is all handled internally by the constructor on the SamlToken class.  The implementation is a little hard to follow though and we can't easily call the constructor on SamlToken ourselves because it also needs the TrustPolicy and I don't have one in memory right now and I'm getting a little tired of reflection code, so I give up.  Perhaps I'm just too easily deterred, but I really just wanted to see angle brackets and it does not look like there are any to be seen.  Sigh.

The moral of the story is that when the product team says that the _WebSsoAuth cookie is a proprietary format that is not intended to be read without their code, they mean it.  If you want the claims, you are supposed to go through the HTTP Module to get a SingleSignOnIdentity.  This gives them some flexibility to change how things work under the hood in future releases and other products.  Is this a violation of the WS-Fed spec?  Apparently not, as it doesn't specify the token format used in the cookie.

Should the Only Consumers of Claims Data Be .NET 2.0 Apps?

Would it be nice to have a way to get the claims as XML based on the cookie?  I think so.  The real use case in my book is allowing access to the claims for apps that aren't using .NET 2.0.  This could be a .NET 1.x app or could be another app platform altogether running on IIS.  It seems reasonable to me that I should be able to grab the cookie and call a web service method on the federation server to get a nice text-based XML SAML token to examine.  This just opens up the platform to allow a greater ecology of applications to participate.

Another option is to capture the redirected form post from the resource federation server when the user initially returns from logging in.  This does actually contain the XML-based SAML token.  The problem is that this event only happens once and triggers an immediate redirect, so there is an excellent chance you won't be able to grab it.

Still another option (which I think may be the best one) would be for the ADFS IIS web service extension (the part of ADFS that makes the token app work) to populate custom HTTP headers/server variables that contained the claims data.  Then any app platform running on IIS from ASP 3.0 to Rails to consume the claims.  The Windows token would be a secondary consideration, and in this case you could treat that token the same way you treat the anonymous user token in other forms authentication IIS apps (by ignoring it for purposes of authorization).

(ps: if anyone wants to see the reflection code required to actually call the Decode method and get the underlying string data, let me know and I'll post it.)

I haven't been blogging for very long, but I've been a pretty active community participant in general for many years now and am generally always happy to try to help people be more productive using the technologies that I know something about.

If you happen by here via a search or something and don't find what you are looking for but suspect I might know something to help you, feel free to ask.

There are two forums that I actively participate in, the web-based forums for our book (www.directoryprogramming.net) and the Microsoft newsgroups (primarily the ADSI.general group, but also the various .NET security groups).

Feel free to leave a comment here too or send an email via the link on the main page.  No promises, but I'll try...

Authentication Mechanisms in SDS

In ADSI and System.DirectoryServicess (SDS), we are really only given two choices for how authentication will be performed when we do a bind operation.  We can specify the "Secure" flag (AuthenticationTypes.Secure), and ADSI will attempt to the bind to the remote directory using Windows SSPI authentication with the Negotiate protocol.  As you may know, the Negotiate protocol is the primary authentication protocol in Windows since Windows 2000 and selects between using Kerberos (always preferred) and NTLM (there for backwards compatibility).  For the really nerdy of you out there, the Negotiate protocol is implemented by Microsoft's LDAP API using the GSS-SPNEGO SASL mechanism.

The other option in SDS is to NOT specify AuthenticationTypes.Secure and it will attempt to use an LDAP simple bind instead^*.  The only authentication mechanism defined by LDAP specification is the simple bind, so every directory implements it.  As such, it ends up being the cross-platform lowest common denominator approach.  The problem with the simple bind is that it is totally insecure by itself.  Simple bind passes the user's plaintext credentials on the network, so unless some sort of channel encryption is provided (like SSL, the defacto cross-platform standard here as well), anyone who can sniff the wire traffic can recover the user's password.  This sort of thing is generally frowned on my security enthusiasts.  :(

Digest Authentication in LDAP API/SDS.P

There is, however, a richer set of authentication mechanisms supported by Microsoft's LDAP API than what ADSI/SDS get to use, and these are available to System.DirectoryServices.Protocols (SDS.P).  One of the most interesting of these is the Digest authentication protocol.  Digest is a standard, secure authentication protocol that does not involve the exchange of plaintext credentials and is implemented by AD and ADAM, as well as some other LDAP directories.  In SDS.P, we can use it very easily.  Here is a short sample illustrating this (and no, there is no ADAM instance at adam.joekaplan.net; dream on...):

public static bool DoDigestAuth(NetworkCredential cred)
{
    const int LDAP_INVALID_CREDENTIALS = 49;
    LdapConnection conn =
        new LdapConnection("adam.joekaplan.net:389");
    conn.AuthType = AuthType.Digest;
    conn.Credential = cred;

    try
    {
        conn.Bind();
        return true;
    }
    catch (LdapException ex)
    {
        if (ex.ErrorCode == LDAP_INVALID_CREDENTIALS)
        {
            return false;
        }
        else
        {
            throw;
        }
    }
}

Here, we have a trivial little sample that shows how this might be done.  Note that we probably wouldn't create a new LdapConnection object each time this is called and we'd also try to find a way to clean that up with a proper Dispose, but the point here is to illustrate that all we really have to do is set the AuthType property to AuthType.Digest and it works.  The credentials are specified with a standard NetworkCredential object.  For Digest, just specify the username and password, not the domain parameter.

Why is This Important?

Digest authentication is really interesting particularly for ADAM, as it is supported by ADAM principals.  Before ADAM supported Digest auth (as of SP1), the only way to authenticate an ADAM principal was with a simple bind.  That wasn't secure (see above), so SSL was required to make it secure.  However, SSL certs are not always easy to procure and take extra effort to install, so many people were missing this and were insecure.  :(

The other cool thing with Digest is that since it is implemented through Microsoft's SSPI model, it can also be used as a mechanism for getting channel encryption and signing, just like negotiate auth supports today^**.  This means that not only can you get secure binding for free, but all of your network traffic after the bind can be encrypted and signed for free (no SSL required).  This is done through setting the Signing and Sealing properties to true on the LdapSessionOptions class.  This, in turn, allows a way to do LDAP password operations on ADAM principals without using SSL and without having to change the setting in ADAM to turn off the requirement for a secure channel on password ops (another big security frown sandwich there...). 

One great scenario for this feature would be to use it with ADFS for their ADAM Account Store support.  This would allow secure authentication without requiring SSL out of the box and would also provide free channel encryption.  Product team please take note!

_{* There is a feature in Windows Server 2003 SP1 ADSI will try Digest auth when the Secure flag is specified and ADSI detects that the server supports Digest but not negotiate auth.  However, this doesn't help us for AD or ADAM, since they both support negotiate auth.  The problem with negotiate auth for ADAM is that it is only used for authenticating Windows users, not ADAM principals.}

_{** There appears to be a bug in the implementation in ADAM SP1 where the channel encryption feature only works if the network traffic is NOT on the loopback (localhost) port.  This is different from the way negotiate channel encryption works.  This appears to be an oversight in the implementation and not an underlying issue in the design, so presumably this will get fixed someday.}

In a previous posting, I mentioned that even though System.DirectoryServices (SDS) and System.DirectoryServices.Protocols (SDS.P) share a lot of overlap in functionality, there are some important things that can only be done in SDS.P.  One that I mentioned is handling server and client certificates that are using when doing SSL/LDAP.

Both SDS and SDS.P support SSL/LDAP.  Basically, if your server is configured to support SSL (and both AD and ADAM can support this, although neither have the required certificates provisioned "out of the box"), you can just turn on SSL LDAP with the appropriate setting and it will just work.  However, SDS doesn't give you much control over the process.  It doesn't expose any information about the certificate the server supplied, nor does it let you choose which client certificate to use (if a choice is possible).  Additionally, if there is a problem with the server's certificate such a certificate trust issue or expiration, with SDS, that is automatically counted as an error.

In SDS.P, we get more control.  Not only can I inspect the certificate to find out information about it, but i can select my own client certificate and I have control over whether or not to trust the server's certificate if I want.  I can thus choose to ignore potential problems (at my peril, of course) and connect anyway.

SDS.P implements the client and server certificate verification stuff via callbacks implemented as delegates, specifically the QueryClientCertificateCallback and VerifyServerCertificateCallback delegates.  In order to use them, you create a method with the matching signature of the delegate and then set the LdapSessionOptions.QueryClientCertificate or LdapSessionOptions.VerifyServerCertificate properties for options set up on your LdapConnection.  Do this before you bind.  BTW, the LdapSessionOptions class is where a lot of the cool advanced features are in SDS.P that allow you access to features not exposed by SDS.  It is worth spending some time staring at it.  :)

Here is a brief code snippet example of doing this in C#:

LdapConnection con =
new LdapConnection(new LdapDirectoryIdentifier(dc + ":636", true, false));
con.SessionOptions.SecureSocketLayer = true;
con.SessionOptions.VerifyServerCertificate =
new VerifyServerCertificateCallback(ServerCallback);
con.SessionOptions.QueryClientCertificate =
new QueryClientCertificateCallback(ClientCallback);

Here, the method ServerCallback looks something like this:

public static bool ServerCallback(
LdapConnection connection,
X509Certificate certificate
)
{
//do some stuff here
}

The Sample App

Now, let's put this together into a useful example.  In my scenario here, I have an AD domain with third-party issued certificates that I'm responsible for maintaining by hand.  If these certificates expire, my apps that use SSL/LDAP may break and cause me embarassment and scorn amongst my colleagues (or worse).  As such, I'd like to have a list of the certificates on my DCs in order of expiration, so that I can plan my renewal/replacement work in advance.

The sample code shows how we can use the VerifyServerCertificateCallback to simply grab the server's current certificate and find its expiration date.  It shoves that into an in memory data structure and eventually dumps out the results to the console.  The sample shows the power of the new System.DirectoryServices.ActiveDirectory (SDS.AD) namespace to quickly and easily enumerate the DCs in my domain with no hassle.  This also shows how these two different LDAP stacks can be integrated to do the things that each is best at.

For good measure, I tried to make the sample fast.  We might have a lot of DCs, so instead of querying them one at a time and waiting for all that network stuff to happen, why not use the .NET thread pool and let it hit them "simultaneously" (more or less)?  Try that with that goofy script stuff.  :)

I wrote this sample using Jeff Key's fantastic Snippet Compiler 2, which is a nice tool for rattling off quicky .NET stuff.  It doesn't make you bust out VS.NET and create a whole project for throwaway stuff.  It also doesn't make you buy VS.NET, although Microsoft has made that easier with the express editions.  Sure, you can always use the free SDK, but this is quite a bit easier to use than notepad and a hand-written MSBuild file.  You'll need assembly references to mscorlib,system,system.directoryservices and system.directoryservices.protocols.  You'll obviously need the .NET 2.0 runtime installed to use the binary.

Enjoy!  All feedback is appreciated.

When I was at TechEd this year, I ran into a few people asking how to integrate SecurID authentication into ADFS.  As it currently stands, Microsoft has no direct support for this, or any other authentication mechanism besides AD/ADAM password authentication and client certificate auth.  Hopefully in the future, Microsoft will make the account store and authentication mechanisms a first class extensibility point, but for now, we must hack.  :)

As you can probably tell by the article title, I have gotten this working in my organization's environment, even though it is not supported by MS.  So, how do we make this work?  First, I'll explain the overall principles of how we glue these things together and then I'll share how I actually did it.  In part 2 of the posting, I'll talk about some other ways that we might get this working.

Basic Principles

In Windows Server 2003 and Active Directory 2003, Microsoft implemented an important and useful extension to the Kerberos authentication protocol called "Service for User" (S4U), aka Protocol Transition.  S4U adds the ability for a service to authenticate a client with a non-Kerberos protocol and then transition to a Kerberos-based identity for accessing Windows resources on local or remote services (hence "protocol transition").  Protocol transition is something that can be done automatically by services like IIS when a user authenticates with Basic, Digest or NTLM, but it can also be called programmatically and used by non-Windows authentication systems such as SecurID.

To use S4U, your code must execute on a Windows Server 2003 machine (or higher) AND your Active Directory must be 2003 forest functional level.  If you are doing ADFS, you already have the former.  However, since ADFS supports both Windows 2000 Server and Windows Server 2003 AD, you might not have the latter.  If you don't, you are basically SOL for now.  Upgrade!

When using S4U programmatically, you are basically calling the Windows API LsaLogonUser with the S4U option specified.  When usings the S4U option, LsaLogonUser only requires you to know the user's UPN, not their password, in order to get a Windows logon token for them.  There are some restrictions on how this token can be used, but that really isn't too important for this discussion.  Keith covers this stuff in detail in his book and several articles anyway.  One other nice thing is that .NET (as of 1.1 and higher) has a very easy way to call LsaLogonUser for S4U with the WindowsIdentity constructor that just takes the UPN.  It is that simple.

So, now we know we need to use S4U to get a Windows token for the user and we'll need their UPN to call this.  How does the Windows token then help us with ADFS?  Well, the ADFS logon service (LS) has a method that allows a user to authenticate given their Windows token.  In fact, the /ls/auth/integrated directory on the federation server does just this.  It is set to use Windows Integrated authentication (IWA) in IIS.  IIS logs the user on with IWA, passes the corresponding Windows token to ASP.NET.  Then, the ADFS HTTP Module grabs that and calls the correct method to log you into ADFS and now you have a federation token. 

An interesting side note is that ADFS itself uses protocol transition in the web agent for token-based applications to achieve similar things (assuming again that you have 2003 AD; otherwise it uses its custom authentication package). 

So, our basic approach with SecurID authentication is to:

1. Authenticate the user with SecurID using one of RSA's supported methods for web authentication
2.  Get the user's UPN somehow (perhaps an LDAP query?)
3. Use S4U to get a Windows token for the user
4. Use the appropriate method on the LS to authenticate with ADFS using the token

This is cake!  :)

How I Did This

Ok, I cheated a little bit.  In addition to using RSA's SecurID/ACE Server product in our company, we also use their ClearTrust web SSO product (now apparently called Access Manager, but I didn't get that memo).  ClearTrust already basically let's me do steps 1-3 above using their standard product when the protocol transition/S4U feature is enabled.  Since it runs as an ISAPI Filter/ISAPI Extension (via a wildcard map in IIS), it runs before any .NET code executes.  All I had to do was configure ClearTrust on my /ls/auth/integrated directory, and ADFS doesn't know the difference between IIS having used IWA or some other thing.  The LS just grabs the Windows token from where it expects to find it in ASP.NET and proceeds with logon.  It really is cake and actually worked the first time I tried it.

The hardest part was instructing ClearTrust to NOT execute on any resources other than the /ls/auth/integrated directory, which essentially came down to a lengthy URL exclusion list in the ClearTrust configuration.  Anyone who has used ClearTrust probably already knows how to do that.  I will probably experiment with alternate directory structures to simplify this a bit more in the future.

Since ClearTrust is a web SSO product, it also contains a signout function that is implemented by navigating to a page.  We integrated this into the ADFS signout by using the same technique it does: we referred to the ClearTrust signout page in a hidden image tag on the normal signout page.  That results in our ClearTrust cookie being cleared.

One thing I should make clear is that we did this customization on the FS, not the FS-P (Federation Service Proxy).  I don't see a reason why you couldn't do this there too, but you'd need to mess with it a bit more as the FS-P is configured out of the box to do its own forms auth instead of redirecting to the /ls/auth/integrated directory.

One important caveat with SecurID auth is that it basically requires forms authentication, especially to support PIN operations.  This basically implies that you can't use the "basic" authentication support built in to ADFS here.  As such, you should probably turn off that option in your ADFS configuration.  That may also mean that you some SharePoint/Office integration stuff breaks though.  I'm not sure how to reconcile that problem.  Forms auth and Office don't like each other.

Summary

So anyway, that's the basic concept.  If anyone needs additional details, let me know and I'll try to expand on this.

In Part 2 of this post, I'll try to expand on how one might accomplish if one were not so blessed with a working ClearTrust infrastructure in place to do the hard part.  Note that I've never actually done this part, so some of it might just be wild supposition and it might take some help from someone else out there who really wants this to make it happen.  We'll see.  In the meantime, I hope the blueprint was helpful.