Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Support Forum
Download Visual Studio Add-In

Terms of Use
Privacy Policy
creduipromptforwindowscredentials (credui)
 
.
Summary
The CredUIPromptForWindowsCredentials function creates and displays a configurable dialog box that allows users to supply credential information by using any credential provider installed on the local computer.

C# Signature:

    [DllImport("credui.dll", CharSet = CharSet.Unicode)]
    private static extern uint CredUIPromptForWindowsCredentials(ref CREDUI_INFO notUsedHere,
      int authError,
      ref uint authPackage,
      IntPtr InAuthBuffer,
      uint InAuthBufferSize,
      out IntPtr refOutAuthBuffer,
      out uint refOutAuthBufferSize,
      ref bool fSave,
      PromptForWindowsCredentialsFlags flags);

VB Signature:

    ''' <summary>
    ''' The CredUIPromptForWindowsCredentials function creates and displays a configurable dialog box that allows users to supply credential information by using any credential provider installed on the local computer.
    ''' NOTE: Windows Vista or Server 2008 or later ONLY. For older Windows versions use CredUIPromptForCredentials().
    ''' See http://msdn.microsoft.com/en-us/library/aa375178(v=VS.85).aspx
    ''' </summary>
    ''' <param name="pUiInfo">The CREDUI_INFO structure with customises the appearance of the dialog.</param>
    ''' <param name="dwAuthError">If prompting after an error pass the Windows Error code so the appropriate error message is included in the dialog.</param>
    ''' <param name="pulAuthPackage">Determine the authentication package to use. Pass zero to use default. Returns with identifier for package used.</param>
    ''' <param name="pvInAuthBuffer">An authentication buffer with which to default prompted values (see <see cref="CredPackAuthenticationBuffer" />).</param>
    ''' <param name="ulInAuthBufferSize">Size of the input authentication buffer.</param>
    ''' <param name="ppvOutAuthBuffer">An authentication buffer which will be populated with entered credentials (see <see cref="CredUnPackAuthenticationBuffer" />).</param>
    ''' <param name="pulOutAuthBufferSize">Size of the output authentication buffer.</param>
    ''' <param name="pfSave">If set to <c>True</c> the check the "Save" checkbox on the dialog - only displayed if CREDUIWIN_CHECKBOX is passed in dwFlags.</param>
    ''' <param name="dwFlags">Flags to control the dialog functionality (see <see cref="CredUIWinFlags" />.</param>
    ''' <returns>A <see cref="CredUIReturnCodes" /> value.</returns>
    <System.Runtime.InteropServices.DllImport("credui.dll", EntryPoint:="CredUIPromptForWindowsCredentials", CharSet:=CharSet.Unicode)> <CLSCompliant(False)> _
    Public Shared Function CredUIPromptForWindowsCredentials(ByRef pUiInfo As CREDUI_INFO, _
                                ByVal dwAuthError As UInt32, _
                                ByRef pulAuthPackage As UInt32, _
                                ByVal pvInAuthBuffer As IntPtr, _
                                ByVal ulInAuthBufferSize As UInt32, _
                                ByRef ppvOutAuthBuffer As IntPtr, _
                                ByRef pulOutAuthBufferSize As UInt32, _
                                <MarshalAs(UnmanagedType.Bool)> ByRef pfSave As Boolean, _
                                ByVal dwFlags As CredUIWinFlags) As CredUIReturnCodes
    End Function

User-Defined Types:

C# Syntax:

    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
    private struct CREDUI_INFO
    {
      public int cbSize;
      public IntPtr hwndParent;
      public string pszMessageText;
      public string pszCaptionText;
      public IntPtr hbmBanner;
    }

    private enum PromptForWindowsCredentialsFlags
    {
      /// <summary>
      /// The caller is requesting that the credential provider return the user name and password in plain text.
      /// This value cannot be combined with SECURE_PROMPT.
      /// </summary>
      CREDUIWIN_GENERIC = 0x1,
      /// <summary>
      /// The Save check box is displayed in the dialog box.
      /// </summary>
      CREDUIWIN_CHECKBOX = 0x2,
      /// <summary>
      /// Only credential providers that support the authentication package specified by the authPackage parameter should be enumerated.
      /// This value cannot be combined with CREDUIWIN_IN_CRED_ONLY.
      /// </summary>
      CREDUIWIN_AUTHPACKAGE_ONLY = 0x10,
      /// <summary>
      /// Only the credentials specified by the InAuthBuffer parameter for the authentication package specified by the authPackage parameter should be enumerated.
      /// If this flag is set, and the InAuthBuffer parameter is NULL, the function fails.
      /// This value cannot be combined with CREDUIWIN_AUTHPACKAGE_ONLY.
      /// </summary>
      CREDUIWIN_IN_CRED_ONLY = 0x20,
      /// <summary>
      /// Credential providers should enumerate only administrators. This value is intended for User Account Control (UAC) purposes only. We recommend that external callers not set this flag.
      /// </summary>
      CREDUIWIN_ENUMERATE_ADMINS = 0x100,
      /// <summary>
      /// Only the incoming credentials for the authentication package specified by the authPackage parameter should be enumerated.
      /// </summary>
      CREDUIWIN_ENUMERATE_CURRENT_USER = 0x200,
      /// <summary>
      /// The credential dialog box should be displayed on the secure desktop. This value cannot be combined with CREDUIWIN_GENERIC.
      /// Windows Vista: This value is not supported until Windows Vista with SP1.
      /// </summary>
      CREDUIWIN_SECURE_PROMPT = 0x1000,
      /// <summary>
      /// The credential provider should align the credential BLOB pointed to by the refOutAuthBuffer parameter to a 32-bit boundary, even if the provider is running on a 64-bit system.
      /// </summary>
      CREDUIWIN_PACK_32_WOW = 0x10000000,
    }

VB Syntax:

    <Flags()> _
    Public Enum CredUIWinFlags As Integer
    CredUIWin_Generic = &H1
    CredUIWin_Checkbox = &H2
    CredUIWin_AuthPackage_Only = &H10
    CredUIWin_InCred_Only = &H20
    CredUIWin_Enumerate_Admins = &H100
    CredUIWin_Enumerate_CurrentUser = &H200
    CredUIWin_Secure_Prompt = &H1000
    CredUIWin_Pack_32_Wow = &H10000000
    End Enum

    Public Enum CredUIReturnCodes As Integer
    NO_ERROR = 0
    ERROR_CANCELLED = 1223
    ERROR_NO_SUCH_LOGON_SESSION = 1312
    ERROR_NOT_FOUND = 1168
    ERROR_INVALID_ACCOUNT_NAME = 1315
    ERROR_INSUFFICIENT_BUFFER = 122
    ERROR_INVALID_PARAMETER = 87
    ERROR_INVALID_FLAGS = 1004
    End Enum

Alternative Managed API:

Do you know one? Please contribute it!

Notes:

None.

Tips & Tricks:

Please add some!

Sample Code:

C# Sample:

    bool save = false;
    int errorcode = 0;
    uint dialogReturn;
    uint authPackage = 0;
    IntPtr outCredBuffer;
    uint outCredSize;

    CREDUI_INFO credui = new CREDUI_INFO();
    credui.cbSize = Marshal.SizeOf(credui);
    credui.pszCaptionText = "Connect to your application";
    credui.pszMessageText = "Enter your credentials!";
    credui.hwndParent = this.Handle;


    while (true) //Show the dialog again and again, until Cancel is clicked or the entered credentials are correct.
    {
      //Show the dialog
      dialogReturn = CredUIPromptForWindowsCredentials(ref credui,
      errorcode,
      ref authPackage,
      (IntPtr)0,  //You can force that a specific username is shown in the dialog. Create it with 'CredPackAuthenticationBuffer()'. Then, the buffer goes here...
      0,          //...and the size goes here. You also have to add CREDUIWIN_IN_CRED_ONLY to the flags (last argument).
      out outCredBuffer,
      out outCredSize,
      ref save,
      0); //Use the PromptForWindowsCredentialsFlags-Enum here. You can use multiple flags if you seperate them with | .

      if (dialogReturn != 0) break; //Break, if Cancel was clicked or an error occurred


      /*Unpack your credentials  (outCredBuffer, outCredSize) with 'CredUnPackAuthenticationBuffer()'
        For example, it returns a bool 'credentialsEnteredCorrect':*/
      bool credentialsEnteredCorrect = false;


      if (credentialsEnteredCorrect) break; //Break the while-loop, if the entered credentials are correct.
      else errorcode = 1326; //Else display an error message inside the dialog next time (The errorcodes are defined in 'winerror.h')
      //1326 = 'Logon failure: unknown user name or bad password.'
    }

Documentation

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Edit This Page
Find References
Show Printable Version
Revisions