Credential Locker: Your solution for handling usernames and passwords in your Windows Store app

If you haven’t yet heard about the Credential Locker that's available for Windows Store apps, it’s time you did. Why? Because it not only simplifies the task of storing and retrieving user credentials, it stores them securely, and credentials roam with users “for free” along with their Microsoft account.

Say you have an app that connects to a service to access protected resources such as media files, social networking, etc. Your service requires login information for each user. So, you’ve built UI into your app that gets the username and password for the user, which is then used to log the user into the service. Everything works like a champ.

Now you want to go that extra mile for your users and store their login information securely so they don’t have to log in every time they use your app. Enter Credential Locker. With a few simple calls to the Credential Locker API, you can store the username and password for your user and easily retrieve them and log the user in the next time they open your app.

Secure storage

The great advantage that Credential Locker brings to your app is that it stores the user credentials in a secure location, and the credential information is encrypted when it’s stored on disk. Sure, you could store your user credentials in a file in the local storage for your app, but storing user credentials in plain text presents a considerable security hole. If a user’s system is compromised in some way, the user’s username and password are easy to access and manipulate. If the username and password are stored using Credential Locker, the best that a malicious source could get a hold of is an encrypted file.

The Credential Locker is unique to each Windows PC user and access to a credential is limited to the app that stored it. That is, you can only retrieve a credential that you stored for your app. Likewise, no other apps can get to the credentials that your app has stored in the locker.

Roaming credentials

As an added benefit to your users, when you store their username and password using Credential Locker, the stored credentials roam with their Microsoft account to any other trusted machine they use with that Microsoft account. This makes your secure app even more convenient for your users because your app can log them in automatically—without re-prompting the user for credentials--from any trusted machine they have installed your app on and associated with their Microsoft account.

Things work a little differently for domain accounts. If there are credentials stored with your Microsoft account, and you associate that account with a domain account (such as the account that you use at work), your credentials will roam to that domain account. However, any new credentials added when signed on with the domain account won’t roam. This ensures that private credentials for the domain aren’t exposed outside of the domain.

Storing user credentials

Storing user credentials in the Credential Locker is a quick, two-step process. First, you obtain a reference to the Credential Locker using the PasswordVault object from the Windows.Security.Credentials namespace. Then, you create a PasswordCredential object that contains an identifier for your app, the username and the password, and pass that to the PasswordVault.Add() method to add the credential to the locker.

C#

var vault = new Windows.Security.Credentials.PasswordVault();
vault.Add(new Windows.Security.Credentials.PasswordCredential(
"My App", username, password));

JavaScript

var vault = new Windows.Security.Credentials.PasswordVault();
vault.add(new Windows.Security.Credentials.PasswordCredential(
"My App", username, password));

Retrieving user credentials

You have several options for retrieving user credentials from the Credential Locker after you have a reference to the PasswordVault object.

• You can retrieve all the credentials the user has supplied for your app in the locker with the PasswordVault.RetrieveAll() method.
• If you know the username for the stored credentials, you can retrieve all the credentials for that username with the PasswordVault.FindAllByUserName() method.
• If you know the resource name for the stored credentials, you can retrieve all the credentials for that resource name with the PasswordVault.FindAllByResource() method.
• Finally, if you know both the username and the resource name for a credential, you can retrieve just that credential with the PasswordVault.Retrieve() method.

Let’s look at an example where we have stored the resource name globally in an app and we log the user on automatically if we find a credential for them. In the case where we find multiple credentials for the user, we ask the user to select a default credential to use when logging on.

C#

privatestring resourceName = "My App";
privatestring defaultUserName;

privatevoid Login()
{
    var loginCredential = GetCredentialFromLocker();

if (loginCredential != null)
    {
// There is a credential stored in the locker.
// Populate the Password property of the credential
// for automatic login.
        loginCredential.RetrievePassword();
    }
else
    {
// There is no credential stored in the locker.
// Display UI to get user credentials.
        loginCredential = GetLoginCredentialUI();
    }

// Log the user in.
    ServerLogin(loginCredential.UserName, loginCredential.Password);
}


private Windows.Security.Credentials.PasswordCredential GetCredentialFromLocker()
{
    Windows.Security.Credentials.PasswordCredential credential = null;

    var vault = new Windows.Security.Credentials.PasswordVault();
    var credentialList = vault.FindAllByResource(resourceName);
if (credentialList.Count > 0)
    {
if (credentialList.Count == 1)
        {
            credential = credentialList[0];
        }
else
        {
// When there are multiple usernames,
// retrieve the default username. If one doesn’t
// exist, then display UI to have the user select
// a default username.

            defaultUserName = GetDefaultUserNameUI();

            credential = vault.Retrieve(resourceName, defaultUserName);
        }
    }

return credential;
}

var resourceName = "My App";
var defaultUserName;

function login() {
var loginCredential = getCredentialFromLocker();

if (loginCredential != null) {
// There is a credential stored in the locker.
// Populate the Password property of the credential
// for automatic login.
        loginCredential.retrievePassword();
    } else {
// There is no credential stored in the locker.
// Display UI to get user credentials.
        loginCredential = getLoginCredentialUI();
    }

// Log the user in.
    serverLogin(loginCredential.userName, loginCredential.password);
}


function GetCredentialFromLocker() {
var credential = null;

var vault = new Windows.Security.Credentials.PasswordVault();
var credentialList = vault.findAllByResource(resourceName);
if (credentialList.length > 0) {
if (credentialList.length == 1) {
            credential = credentialList[0];
        } else {
// When there are multiple usernames,
// retrieve the default username. If one doesn’t
// exist, display UI to have the user select
// a default username.

            defaultUserName = getDefaultUserNameUI();
            credential = vault.retrieve(resourceName, defaultUserName);
        }
    }

return credential;
}

Deleting user credentials

Deleting user credentials in the Credential Locker is also a quick, two-step process. Again, you obtain a reference to the Credential Locker using the PasswordVault object from the Windows.Security.Credentials namespace. Then, you pass the credential you want to delete to the PasswordVault.Remove() method.

C#

var vault = new Windows.Security.Credentials.PasswordVault();
vault.Remove(new Windows.Security.Credentials.PasswordCredential(
"My App", username, password));

JavaScript

var vault = new Windows.Security.Credentials.PasswordVault();
vault.remove(new Windows.Security.Credentials.PasswordCredential(
"My App", username, password));

Easy and secure

As you can see, the Credential Locker is an easy-to-use feature that simplifies your task of authenticating users and storing those user credentials for future use—all in a highly secure fashion.

Other Windows 8 app authentication topics include the Web Authentication Broker, which you can use to retrieve an authentication token from a website (for example, OAuth), and personalizing your app based on a user’s Microsoft account.

For more info, see

• Managing user info (JavaScript)
• Managing user info (Windows Store apps using C#/VB/C++ and XAML)
• Credential Locker sample
• Windows.Security.Credentials

--Doug Rothaus, Senior Content Developer, Windows Developer Content

Special thanks to Yashar Bahman for his help and contributions to this post.