ASP.NET VERSIONS: ALL
Authentication via the CredUIPromptForCredentials API
By Don Kiely
A post on the http://www.asp.net support forums recently asked a question about using Windows authentication in an ASP.NET project. Users get the familiar dialog box in IE that prompts for the user name and password. Some users would get a dialog that included a Remember my password checkbox, but others didn t. The author of the post wondered why it was inconsistent and how to enable the checkbox and feature to remember passwords for all users.
The variation in dialog boxes, as it turns out, can be based on the version of Windows the user is running. Windows XP and Windows Server 2003 include a CredUIPromptForCredentials API function. In later versions of Windows, IE uses this API for prompting the user for credentials. A nice benefit is that then Windows, not IE or your custom apps that use the API, takes care of securely saving the password. You shouldn t need to use CredUIPromptForCredentials directly in your ASP.NET apps because IE can handle it for you. Even if you did, such as to perhaps allow FireFox as the client browser for an app that uses Windows authentication, you d have to install and run client-side code to make the method call. Nevertheless, CredUIPromptForCredentials is an interesting method that can make clear some authentication issues for any Windows app. So let s take a look at how it works, using a WinForms app.
I recently used this in a project and so had to do all the research to make it work. This application happened to be written in VB.NET, but the ideas are similar for C#. If you re using C++, you ll need the Include and Lib directories from the Platform SDK (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/sdkintro/sdkintro/devdoc_platform_software_development_kit_start_page.asp). Here s the code I used to prompt the user for login credentials:
Dim bUseCredUI As Boolean = WindowsVersionForCredentials()
Dim frmLogin As Login
Dim sUser As String
Dim sPwd As String
Dim bSave As Boolean
Dim bAttemptAuth As Boolean
Do While True
If bUseCredUI Then
bAttemptAuth = CredUILogin(sUser, sPwd, bSave)
'Use a custom login form
If bAttemptAuth Then
'Do whatever is necessary to authenticate user
The code starts with a call to a custom WindowsVersionForCredentials function to determine whether the code is running on a version of Windows that supports CredUIPromptForCredentials, namely Windows XP or Windows Server 2003 (more about WindowsVersionForCredentials below). If CredUIPromptForCredentials is available, the code calls the custom CredUILogin function, which calls CredUIPromptForCredentials and returns a Boolean indicating whether the user entered any credentials. Here I m passing reference variables to get the user name, password, and whether the user checked the Remember my password box (see Figure 1).
Figure 1: The login box, which should look familiar to Windows users. Note that it includes a custom prompt.
The rest of the code above uses a custom login form if the code is running on Windows 2000. Then, if in either case the user entered credentials, the code does whatever is necessary to authenticate the user. This is commonly a database lookup.
Here is the crux code, the call to CredUIPromptForCredentials:
Private Function CredUILogin(ByRef sUserName As String,
ByRef sPassword As String, ByRef bSave As Boolean) As Boolean
Dim info As New CredentialManager.CREDUI_INFO
info.hwndParent = Me.Handle
info.pszCaptionText = Application.ProductName
info.pszMessageText = "Please enter " & Application.ProductName & " login information"
Dim result As CredUIReturnCodes
Dim flags As CREDUI_FLAGS
flags = CREDUI_FLAGS.GENERIC_CREDENTIALS Or _
CREDUI_FLAGS.SHOW_SAVE_CHECK_BOX Or _
CREDUI_FLAGS.ALWAYS_SHOW_UI Or _
Dim sUser As String
Dim sPwd As String
result = CredUI.PromptForCredentials(info, _
Application.ProductName, 0, _
sUser, sPwd, _
If result = CredUIReturnCodes.NO_ERROR Then
sUserName = sUser
sPassword = sPwd
CredUIPromptForCredentials has a boatload of parameters, but here I m using a bare minimum. The trickiest part is setting up the CREDUI_INFO structure with the parent form s window handle, the caption text for the title bar, and the text for the prompt. The code sets some flags; for instance, here to:
- use generic credentials rather than a Windows login;
- show the Save my password box;
- show the login even if the credentials are cached (used only with generic credentials); and,
- say whether the code will confirm the credentials after making use of them.
Check the documentation for the several other flags you can use.
Finally, the code calls the CredUIPromptForCredentials function actually the CredUI.PromptForCredentials method passing in the info structure; the application name used to store the credentials if the user opts to do that (any string will do, as long as it is unique for this set of credentials); 0 for a reserved parameter; reference variables for user name, password and the save flag; and the flags you set.
The CredUILogin function then returns True to indicate that the user entered credentials, or False if not.
Astute readers will no doubt notice that there is just not that much support for calling Win32 APIs as is implied in this code like, oh, say a p/invoke statement. Yes, of course! To do all the heavy lifting I used a CredentialsManager component, CredUI, written by Duncan Mackenzie and published on MSDN (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnnetsec/html/dpapiusercredentials.asp).
The last step in using the CredUIPromptForCredentials function is to optionally confirm the credentials. This uses another API function, CredUIConfirmCredentials, which must be called after you validate the credentials, if you passed the CREDUI_FLAGS.GENERIC_CREDENTIALS flag, and if the prompt function returned NO_ERROR. Duncan s CredentialsManager makes this easy. If the credentials are good:
'Credentials are good, so let Windows persist them
If they are bad:
'Credentials failed, so don't let Windows persist them
Here again I m passing the Application.ProductName as the unique string with which these credentials will be associated. Once this function is called with True for the second parameter, the credentials are saved for this user.
The WindowsVersionForCredentials function simply uses the OperatingSystem object to make sure that the code is running on Windows XP or Windows Server 2003. This might not be as robust as you need, because this particular application could only be installed on Windows 2000 or later, so I didn t need to worry about Windows 9x at all. But the docs explain things pretty thoroughly. This is way better than the old tricks we had to use with Win32 API programming to find out what the app was running on:
Public Function WindowsVersionForCredentials() As Boolean
'Determine if the app is running on a version of Windows that can use the CredUI API in Windows,
'available for WinXP and later. IOW, not Windows 2000.
Dim bOkay As Boolean = False
Dim OS As OperatingSystem = Environment.OSVersion
If OS.Platform = PlatformID.Win32NT Then
If OS.Version.Major >= 5 Then
If OS.Version.Minor > 0 Then
'Version 5.0 is Win2K, 5.1 is WinXP
bOkay = True
Valery Pryamikov, who writes an excellent security blog, talks about the problem of clearing the credential cache (http://www.harper.no/valery/PermaLink,guid,deba3b20-9d29-440f-b7bb-5a61c50bd99d.aspx), and includes a nifty utility to make it easier.
Don Kiely, MVP, MCSD, is a senior technology consultant, building custom applications as well as providing business and technology consulting services. His development work involves tools such as SQL Server, Visual Basic, C#, ASP.NET, and Microsoft Office. He writes regularly for several trade journals, and trains developers in database and .NET technologies. You can reach Don at mailto:[email protected] and read his blog at http://www.sqljunkies.com/weblog/donkiely/.