MICROSOFT_PRESS_EBOOK_PROGRAMMING_WINDOWS_8_APPS_WITH_HTML_CSS_AND_JAVASCRIPT_PDF

for domain-joined machines—see table below). The purpose here is to show the dialog when a
stored credential might be incorrect and the user is expected to provide a new one.
• errorCode The numerical value of a Win32 error code (default is ERROR_SUCCESS) that will be
formatted and displayed in the dialog box. You would use this when you obtain credentials from
the picker initially but find that those credentials don’t work and need to invoke the dialog
again. Instead of providing your own message, you just choose an error code and let the system
do the rest. The most common values for this are 1326 (login failure), 1330 (password expired),
2202 (bad username), 1907 or 1938 (password must change/password change required), 1351
(can’t access domain info), and 1355 (no such domain). There are, in fact, over 15,000 Win32
error codes, but that means you’ll have to search the reference linked here (or search within the
winerror.h file typically found in your Program Files (x86)\Windows Kits\8.0\Include\shared
folder). Happy hunting!
• callerSavesCredential A Boolean indicating that the app will save the credential and that the
picker should not. The default value is false. When set to true, credentials are saved to a secure
system location (not the credential locker) if the app has the Enterprise Authentication capability
(see below).
• credentialSaveOption A value from the CredentialSaveOption enumeration indica-ting the
initial state of the Remember My Credentials check box: unselected, selected, or hidden.
• authenticationProtocol A value from the AuthenticationProtocol enumeration: basic,
digest, ntlm, kerberos, negotiate (the default), credSsp, and custom (in which case you must
supply a string in the customAuthenticationProcotol property). Note that with basic and
digest, the CredentialPickerResults.credentialPassword will not be encrypted and is subject
to the same security needs as a plain text password you collect from your own UI.
Here’s an example of invoking the picker with an errorCode indicating a previous failed login:
var options = new Windows.Security.Credentials.UI.CredentialPickerOptions();
options.message = "Please enter your credentials";
options.caption = "Sample App";
options.targetName = "Target";
options.alwaysDisplayDialog = true;
options.errorCode = 1326; // Shows "The username or password is incorrect."
options.callerSavesCredential = true;
options.authenticationProtocol =
Windows.Security.Credentials.UI.AuthenticationProtocol.negotiate;
options.credentialSaveOption = Windows.Security.Credentials.UI.CredentialSaveOption.selected;
Windows.Security.Credentials.UI.CredentialPicker.pickAsync(options)
.done(function (results) {
}
658