MICROSOFT_PRESS_EBOOK_PROGRAMMING_WINDOWS_8_APPS_WITH_HTML_CSS_AND_JAVASCRIPT_PDF

A credential object also contains an IPropertySet value named properties, through which the same
information can be managed.
In any case, when you collect credentials from a user and want to save them, create a
Password-Credential and pass it to PasswordVault.add:
var vault = new Windows.Security.Credentials.PasswordVault();
vault.add(cred);
Note that if you add a credential to the locker with a resource and userName that already exist, the
new credential will replace the old. And if at any point you want to delete a credential from the locker,
call the PasswordVault.remove method with that credential.
Furthermore, even though a PasswordCredential object sees the world in terms of usernames and
passwords, that password can be anything else you need to store securely, such as an access token. As
we’ll see in the next section, authentication through OAuth providers might return such a token, in
which case you might store something like “Facebook_Token” in the credential’s resource property,
your app name in userName, and the token in password. This is a perfectly legitimate and expected use.
Once a credential is in the locker, it will remain there for subsequent launches of the app until you
call the remove method or the user explicitly deletes it through Control Panel > User Accounts and
Family Safety >Credential Manager. On a trusted PC (which requires sign-in with a Microsoft account),
Windows will also automatically and securely roam the contents of the locker to the user’s other devices
(which can be turned off in PC Settings > Sync Your Settings > Passwords). This help to create a
seamless experience with your app as the user moves between devices. 74
So, when you launch an app—even when launching it for the first time—always check if the locker
contains saved credentials. There are several methods of the PasswordVault class for doing this:
• findAllByResource Returns an array (vector) of credential objects for a given resource
identifier. This is how you can obtain the username and password that’s been roamed from
another device, because the app would have stored those credentials in the locker on the other
machine under the same resource.
• findAllByUserName Returns an array (vector) of credential objects for a given username. This is
useful if you know the username and want to retrieve all the credentials for multiple resources
that the app connects to.
• retrieve Returns a single credential given a resource identifier and a username. Again, there
will only ever be a single credential in the locker for any given resource and username.
• retrieveAll Returns a vector of all credentials in the locker for this app. The vector contains a
snapshot of the locker and will not be updated with later changes to credentials in the locker.
74 Such roaming will not happen, however, if a credential is first stored in the locker on a domain joined machine. This
protects domain credentials from leaking to the cloud.
660