Cofre de credenciaisCredential locker

Este artigo descreve como aplicativos UWP (Plataforma Universal do Windows) podem usar o Cofre de credenciais para armazenar com segurança e recuperar credenciais do usuário, e alternar entre os dispositivos com a conta da Microsoft do usuário.This article describes how Universal Windows Platform (UWP) apps can use the Credential Locker to securely store and retrieve user credentials, and roam them between devices with the user's Microsoft account.

Por exemplo, você possui um aplicativo que se conecta a um serviço para acessar recursos protegidos, como arquivos de mídia ou rede social.For example, you have an app that connects to a service to access protected resources such as media files, or social networking. O seu serviço requer informações de logon para cada usuário.Your service requires login information for each user. Você criou a interface do usuário em seu aplicativo que obtém o nome do usuário e a senha que são então usados para fazer logon do usuário no serviço.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. Usando a API do Cofre de credenciais, você pode armazenar o nome do usuário e a senha do seu usuário e recuperá-los com facilidade e fazer logon do usuário automaticamente na próxima vez em que ele abrir o aplicativo, independentemente do aplicativo em que ele está.Using the Credential Locker API, you can store the username and password for your user and easily retrieve them and log the user in automatically the next time they open your app, regardless of what device they're on.

As credenciais do usuário armazenadas no CredentialLocker não expiram, não são afetadas por ApplicationData.RoamingStorageQuota e não serão limpas devido a inatividade como dados de roaming tradicionais.User credentials stored in the CredentialLocker do not expire, are not affected by the ApplicationData.RoamingStorageQuota, and will not be cleared out due to inactivity like traditional roaming data. No entanto, você só pode armazenar até 20 credenciais por app no CredentialLocker.However, you can only store up to 20 credentials per app in the CredentialLocker.

O Cofre de credenciais funciona um pouco diferente para contas de domínio.Credential locker works a little differently for domain accounts. Se houver credenciais armazenadas à sua conta da Microsoft e você associar essa conta a uma conta de domínio (como a conta que você usa no trabalho), suas credenciais se moverão para essa conta de domínio.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. No entanto, quaisquer credenciais novas adicionadas ao se conectar à conta de domínio não se moverão.However, any new credentials added when signed on with the domain account won’t roam. Isso garante que credenciais privadas para o domínio não serão expostas fora do domínio.This ensures that private credentials for the domain aren’t exposed outside of the domain.

Armazenando credenciais do usuárioStoring user credentials

  1. Obtenha uma referência para o Cofre de credenciais usando o objeto PasswordVault do namespace Windows.Security.Credentials.Obtain a reference to the Credential Locker using the PasswordVault object from the Windows.Security.Credentials namespace.
  2. Crie um objeto PasswordCredential que contenha um identificador para o seu aplicativo, o nome de usuário e a senha, e passe isso para o método PasswordVault.Add para adicionar a credencial ao cofre.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.
var vault = new Windows.Security.Credentials.PasswordVault();
vault.Add(new Windows.Security.Credentials.PasswordCredential(
    "My App", username, password));

Recuperando credenciais do usuárioRetrieving user credentials

Você tem várias opções para recuperar credenciais do usuário do Cofre de credenciais depois que tiver uma referência para o objeto PasswordVault.You have several options for retrieving user credentials from the Credential Locker after you have a reference to the PasswordVault object.

  • É possível recuperar todas as credenciais do usuário fornecidas para o seu aplicativo no cofre com o método PasswordVault.RetrieveAll.You can retrieve all the credentials the user has supplied for your app in the locker with the PasswordVault.RetrieveAll method.

  • Se você souber o nome do usuário para as credenciais armazenadas, poderá recuperar todas elas para esse nome de usuário com o método PasswordVault.FindAllByUserName.If you know the username for the stored credentials, you can retrieve all the credentials for that username with the PasswordVault.FindAllByUserName method.

  • Se você souber o nome do recurso para as credenciais armazenadas, poderá recuperar todas elas para esse nome de recurso com o método PasswordVault.FindAllByResource.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.

  • Finalmente, se você souber o nome do usuário e o nome do recurso de uma credencial, poderá recuperar apenas essa credencial, com o método PasswordVault.Retrieve.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.

Vejamos um exemplo em que armazenamos o nome do recurso globalmente em um aplicativo e faremos logon automaticamente do usuário se encontrarmos uma credencial para ele.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. No caso de encontrarmos várias credenciais para o mesmo usuário, pediremos a ele para selecionar uma credencial padrão a ser usada ao fazer logon.If we find multiple credentials for the same user, we ask the user to select a default credential to use when logging on.

private string resourceName = "My App";
private string defaultUserName;

private void 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;
}

Excluindo credenciais do usuárioDeleting user credentials

Eliminar credenciais do usuário no Cofre de credenciais é um processo rápido em duas etapas.Deleting user credentials in the Credential Locker is also a quick, two-step process.

  1. Obtenha uma referência para o Cofre de credenciais usando o objeto PasswordVault do namespace Windows.Security.Credentials.Obtain a reference to the Credential Locker using the PasswordVault object from the Windows.Security.Credentials namespace.

  2. Passe a credencial a ser excluída para o método PasswordVault.Remove.Pass the credential you want to delete to the PasswordVault.Remove method.

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

Práticas recomendadasBest practices

Use o cofre de credenciais para senhas e não para blobs de dados maiores.Only use the credential locker for passwords and not for larger data blobs.

Salve senhas no cofre de credenciais somente se os seguintes critérios forem atendidos:Save passwords in the credential locker only if the following criteria are met:

  • O usuário entrou com êxito.The user has successfully signed in.
  • O usuário optou por salvar senhas.The user has opted to save passwords.

Nunca armazene credenciais em texto sem formatação usando dados de aplicativo ou configurações de roaming.Never store credentials in plain-text using app data or roaming settings.