Starting to build your own Credential Provider

If you’re starting to work on a Credential Provider (CredProv or CP, for short) for Windows Vista, Windows Server 2008, Windows Server 2008 R2 or Windows 7, there are a few steps I would strongly recommend you take, because it will make life easier for you.

0. Read Dan Griffin’s article in MSDN Magazine.

The article, "Create Custom Login Experiences With Credential Providers For Windows Vista" by Dan Griffin in January 2007’s MSDN Magazine on Credential Providers is a truly excellent source of information, gleaned largely by the same exhaustive trial and error effort that you will be engaging in with your own CP.

0.1 Read it again.

0.2 And again, and again and again.

As you work on your CP, you will keep running into questions and new insights as to what it is that Dan was telling you in that article.

Keep a printed copy next to you when developing your CP, so that you can keep looking back to it.

If you have met Dan and asked his permission, keep him on speed-dial.

1. Test your Credential Provider in a Virtual PC environment.

You will screw something up, and when you do, the logon screen will most likely cycle over and over and over (what, Microsoft couldn’t provide a “this Credential Provider has failed eighteen times in a row and will be temporarily disabled” feature?), preventing you from logging back on to change out your broken CP. At this point, you really want to revert back to a previous working session.

To my mind, the easiest way to do this is to create one Virtual PC environment with a base Windows 7 system, patched up to current levels, and with a few test users installed. You can burn an MSDN licence up on this test installation, if you like, but quite frankly, I’m likely to want to refresh it from scratch every so often anyway, so the activation timeout is no big deal.

Once you have created this base image, create another virtual machine, based off the virtual hard disk (VHD) of the base image, and be sure to enable undo disks. This way, when things go wrong, you can shut down this second virtual machine, telling Virtual PC to discard the Undo Disk data, and you will be able to restart the machine immediately and continue to work on it.

2. Enable the kernel debugger against your VM.

This is a little tricky.

2.1 First, edit the settings on your VM.

Enable COM1 to point to a Named Pipe, such as “\\.\pipe\credprov”:

2.2 Now, enable kernel debugging on the VM itself

Log on to the VM, and use the bcdedit tool, from an Administrator Command Prompt to change the debugging option in the boot database. You can go the long way around, reading Microsoft’s instructions on how to do this, or you can simply use the following two commands:

bcdedit /dbgsettings serial debugport:1

bcdedit /debug {current} on

Notice that Microsoft suggests creating a separate environment for debugging on and off, but I don’t see that as being terribly useful. I will always be debugging this test environment, and it really doesn’t slow me down that much. You can always use “bcdedit /debug {current} off” to turn debugging off later.

This setting will take effect at the next reboot of the VM, but don’t reboot yet.

2.3 Enable the Debug Output Filter so OutputDebugString works.

Windows Vista and later don’t output debug messages to the kernel debugger by default. Those messages are filtered. You can spend a lot of time trying to figure out why you are staring at a blank screen when you have filled your code with OutputDebugString and/or TRACE calls. Or you can change the registry entry that controls the Output Debug Filter:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Debug Print Filter\DEFAULT

Create the “Debug Print Filter” value, if it isn’t there, and then create the DEFAULT value as a DWORD, and set it to the value 8.

2.4 Save these settings

Since you’ll want these settings to come back after a restart, you’ll want to commit them to the VHD. Easily done, but takes some time. Shut down the VM, and when you are prompted what you want to do, select that you wish to commit changes to the virtual hard disk.

Expect this to take several long minutes. While you do that, go read Dan’s article again.

2.5 Create a shortcut to the debugger

I use WinDBG (is that pronounced “Windbag”?), and the shortcut I use points to:

"C:\Program Files\Debugging Tools for Windows (x64)\windbg.exe" -k com:port=\\.\pipe\credprov,baud=115200,pipe,reconnect,resets=10

Remember to start the VM before starting the WinDBG shortcut, so that the VM has a pipe for WinDbg to connect to.

3. Start from the CredProv samples

Play around with the credential provider sample, or samples, that are closest to your eventual design goal, and add features to move them towards your desired end-state, rather than building your own from scratch.

Don’t just play with the one sample – looking at, or testing, the other samples may give you a little more insight that you didn’t get from the sample you’re working with.

3.1 Build often, and test frequently

Random errors and occasional misunderstandings (“gee, I didn’t realise you can’t call SetFieldString from GetStringValue”) will cause you to crash often. A crash in your CP means an infinite loop, and some inventive use of Anglo-Saxon.

Building often, testing frequently, and backing out disastrous changes (use version control if you have it!) will lead to a better process.

3.2 Later, build your own CP

Once you have a good understanding of the Credential Provider and its mysterious ways, you may decide to throw out Microsoft’s code and build your own from scratch. Keep comparing against your modified sample to see why it isn’t working.

3.3 Before deployment, change the GUID!

The GUIDs used by the sample code are well-known, and will tie in some systems to other, more shoddy, developers’ versions of those samples. If you forget to change the GUID on your code, you will have a CP-fight.

4. Go back to Dan’s article every time you reach a bottleneck

Occasionally a twist of phrase, or a reinterpretation of a paragraph is all it takes to wring some more useful knowledge out of this article. Don’t forget to use the online help Microsoft provides, as well as searching the MSDN, but remember that this is not a very frequently-trod path. It may be that you are doing something the credential provider architects didn’t consider. In fact, it’s highly likely.

5. Stop mailing credprov@microsoft.com

Nobody monitors that email address any more, and there seems to be something of a black hole associated with questions related to Credential Providers in general. It’s as if nobody really truly understands them. A few of the MVPs (particularly Dan Griffin, Dana Epp, and perhaps myself) have a good understanding, so read their blogs, and perhaps post to the Microsoft Forums, if you can manage to do so.

6. Enumerate, and test, the scenarios your customers might run into

• domain-joined and non-domain
• administrator, non-administrator, guest
• with and without user names being supplied (Secpol.msc –> Local Policies –> Security Options –> Interactive Logon: Do not display last user name)
• default domain, other domain, local accounts
• logon, switch user, unlock workstation, access from Remote Desktop Connection / MSTSC (as we old-timers call it)
• change password
• If you’re of a mind, test the credential user interface mode, too.