Using the Credential Store for Automated Login

To facilitate automated login for unattended applications, the vSphere Web Services SDK includes client-side credential store libraries and tools for automating the login process in a more secure manner. The libraries eliminate the need for system administrators to keep passwords in local scripts.

Important These libraries are built on top of the vSphere Web Services SDK.

The credential store has the following components:

■	A persistence file (credential store backing file) that stores authentication credentials. Currently, only passwords are supported. The persistence file maps a remote user account from an ESXi host to the password for that user on the server.

■	C#, Java, and Perl libraries for managing the credential store programmatically. See Credential Store Client Methods for available methods.

■	Java and Microsoft PowerShell-based command-line utilities for managing the credential store.

In addition to the libraries listed in Credential Store Client Libraries, the vSphere Web Services SDK includes the CredentialStoreAdmin tool for creating, examining, and managing the credential store. You can use the tool to examine the contents of the credential store, for example, the generated user accounts and passwords.

If you use the credential store client libraries, shown in Credential Store Client Libraries in an application, you must set up the credential store on all client machines that run your application.

Credential Store Client Libraries 

Package com.vmware.security.credstore (Java)	Namespace VMware.Security.CredentialStore(C#)
CredentialStore.java	CredentialStoreFactory.cs
CredentialStoreFactory.java	CredentialStore.cs

Several of the helper classes provided with the sample applications use the credential store mechanism.

Credential Store Methods

Credential Store Client Methods 

Java	C#	Description
addPassword(hostname, username, password)	AddPassword(hostname, username, password)	Stores the password for the specified host and user. Overwrites any existing password for that user in the credential store. Creates the default credential store backing file in the default location (if it does not exist).
removePassword(hostname, username)	RemovePassword(hostname, username)	Deletes the password for the specified user from the credential store.
clearPasswords()	ClearPasswords()	Deletes all passwords from the credential store.
getPassword(hostname, username)	GetPassword(hostname, username)	Returns the password for the specified host and user from the credential store.
getHosts()	GetHosts()	Returns the set of hosts contained in the credential store.
getUsernames(hostname)	GetUsernames(hostname)	Returns the collection of all user names that have passwords stored for the specified hostname.
close()	Close()	Closes the credential store, preventing further method invocations. Releases associated resources.

Credential Store Backing File

The credential store backing file is an XML file that is saved locally on the client machine for access at runtime. Unless otherwise specified, the backing file is located in the following location:

■	Linux. $HOME/.vmware/credstore/vicredentials.xml

■	Windows Vista. C:\Users\[user_name]\AppData\Roaming\VMware\credstore\vicredentials.xml

■	Windows XP and Windows 2000. C:\Documents and Settings\[user_name]\Application Data\VMware\credstore\vicredentials.xml

The credential store persists locally on a per-user basis—each user has his or her own credential store backing file.

Caution The credential store backing files use filesystem-level permissions to ensure that passwords remain confidential. Protect the credential store backing file with appropriate file permissions.

Example: Credential Store File Format shows the XML elements that are read and written to the file.

Example: Credential Store File Format

<?xml version="1.0" encoding="UTF-8"?>

<viCredentials>

<version>1.0</version>

<passwordEntry>

<host>mi6.vmware.com</host>

<username>agent007</username>

<password>IhWS1saIhtsw2FbIh0w2F2...</password>

</passwordEntry>

<passwordEntry>

...

</passwordEntry>

...

</viCredentials>

 

Credential Store Samples

The CreateUser and SimpleAgent sample applications demonstrate how to use the credential store client libraries.

■	The CreateUser sample creates a user account and password for the server based on random-number-generation scheme. The sample populates the local credential store backing file with this information. If the backing file does not exist, it is created in the default location.

When you run CreateUser, specify the name of an ESXi system, and an administrator user name and password. A user account name and password are created on the server. Specify --ignorecert unless your system has a secure connection to the target. Do not use --ignorecert in a production environment.

java com.vmware.samples.simpleagent.CreateUser --server <servername> --url https://<servername>/sdk --username <adminuser> --password <pwd> --ignorecert ignorecert

Caution The CreateUser sample application is for demonstration purposes only and should not be used as a model for production code. The sample breaks the principle of least privilege by granting the user account the Administrator role (-1). Never do this in a production environment.

■	The SimpleAgent sample application demonstrates how to use credential store libraries to extract the user account and password at runtime to authenticate a user noninteractively.

java com.vmware.samples.simpleagent.SimpleAgent <servername>

Specifying Roles and Users with the Credential Store

VMware recommends that you apply the principle of least privilege to any agent-like software or automated application that uses the credential store in a production environment. Give user accounts the minimal number of privileges on the system that they require to do their jobs.

Specify roles and users as follows:

1	For each SDK-based application, use one specific role, newly created or predefined, that has appropriate privileges.

For example, if you are developing an agent-like application to automatically start the VMware Consolidated Backup utility, you might use the “VMware Consolidated Backup Utility” role (roleID 7).

If no predefined user role that meets the needs of your application exists, create a role with only those privileges needed for the application. See System and Sample Roles for more information about roles.

2	Create a user account for use with the agent or application.

3	Apply the role created in Step 1 to the user account created in Step 2.

4	Store the user account and password in the credential store, using the CredentialStoreAdministration tool.

Never grant administrator privileges to a user account associated with an automated script or software agent, especially one that uses the credential store.