creduipromptforwindowscredentials (credui)
Last changed: -82.113.106.205

.
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;
    }

    [Flags]
    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