Skip navigation

Checking Credentials

Authentication via the CredUIPromptForCredentials API

Secure ASP.NET

LANGUAGES: ALL

ASP.NET VERSIONS: ALL

 

Checking Credentials

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)

 Else

      'Use a custom login form

 End If

 If bAttemptAuth Then

      'Do whatever is necessary to authenticate user

 Else

      DoLogout()

      Exit Do

 End If

Loop

 

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.

 

CredUILogin Function

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 _

      CREDUI_FLAGS.EXPECT_CONFIRMATION

 Dim sUser As String

 Dim sPwd As String

 result = CredUI.PromptForCredentials(info, _

      Application.ProductName, 0, _

      sUser, sPwd, _

      bSave, flags)

 If result = CredUIReturnCodes.NO_ERROR Then

      sUserName = sUser

      sPassword = sPwd

      Return True

 Else

      Return False

 End If

End Function

 

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).

 

Confirming Credentials

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

CredUI.ConfirmCredentials(Application.ProductName, True)

 

If they are bad:

 

'Credentials failed, so don't let Windows persist them

CredUI.ConfirmCredentials(Application.ProductName, False)

 

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.

 

WindowsVersionForCredentials function

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

           End If

      End If

 End If

 Return bOkay

End Function

 

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.

 

Enjoy!

 

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/.

 

 

 

 

Hide comments

Comments

  • Allowed HTML tags: <em> <strong> <blockquote> <br> <p>

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.
Publish