Mercurial Authentication Configuration: Three Methods for Securely Storing Usernames and Passwords

Overview of Mercurial Authentication Mechanisms

When using Mercurial for version control, repeatedly entering usernames and passwords can significantly reduce productivity. Mercurial provides multiple authentication configuration methods, allowing users to choose appropriate approaches based on security needs and personal preferences. These methods primarily fall into three categories: plain text storage in configuration files, SSH key authentication, and secure storage using the keyring extension.

Authentication Settings in Configuration Files

Mercurial allows authentication information to be configured in the .hgrc file in the user's home directory (or Mercurial.ini on Windows systems). The correct approach is not to add passwords directly in the [ui] section, but to use the dedicated [auth] section.

Below is a standard configuration example:

[auth]
bb.prefix = https://bitbucket.org/repo/path
bb.username = foo
bb.password = foo_passwd

In this configuration, bb is an arbitrary identifier used to associate the prefix with corresponding username and password. This design is particularly useful for managing authentication information for multiple repositories, with each repository potentially using different identifier prefixes.

The configuration works as follows: when Mercurial accesses a remote repository URL matching the prefix value, it automatically uses the associated username and password for authentication. If only the username is configured without the password, the system will still prompt for the password during operations, providing a balance of security and convenience.

It is important to note that this method stores passwords in plain text within the configuration file, posing security risks. Particularly in shared environments or multi-user systems, other users may access these sensitive credentials.

SSH Key Authentication: The Secure Best Practice

For security-conscious users, SSH key authentication represents the most recommended solution. This approach completely avoids storing passwords in configuration files by leveraging public-private key encryption mechanisms for secure access.

The SSH authentication configuration process involves the following steps:

1. Generate an SSH key pair (public and private keys) locally
2. Upload the public key to the remote server or code hosting platform (such as Bitbucket, GitHub, etc.)
3. Configure Mercurial to use the SSH protocol for repository access

Once configured, Mercurial communicates with remote repositories via SSH, using the private key for authentication without requiring password input. This method not only enhances security but also provides better support for automation, particularly in continuous integration and automated deployment scenarios.

The main advantages of SSH authentication include:

• No sensitive information stored in configuration files
• Support for more complex access control policies
• Seamless integration with existing SSH infrastructure
• Transport layer encryption to protect data transmission

Keyring Extension: Balancing Convenience and Security

For users seeking both convenience and security, the keyring extension offers an ideal solution. This extension stores passwords in the operating system's keyring rather than in plain text configuration files.

The keyring extension workflow operates as follows:

1. During initial access to a remote repository, the system prompts for username and password
2. The extension securely stores the credentials (combination of username and password) in the system keyring
3. For subsequent accesses, the extension automatically retrieves and uses the stored credentials from the keyring

To enable the keyring extension, add the following configuration to the .hgrc file:

[extensions]
keyring =

On Windows platforms, TortoiseHg typically bundles this extension. For other platforms, it can be obtained through package managers or from the official Mercurial repository.

Key features of the keyring extension include:

• Passwords stored in operating system-level secure storage
• Support for multiple repositories and credential management
• Seamless integration with existing workflows
• Reduced frequency of manual password entry

Security Considerations and Best Practices

When selecting an authentication method, it is essential to balance security, convenience, and specific use cases:

For personal development environments with lower security requirements, using the [auth] section configuration may be the simplest solution. However, attention must be paid to file permissions to ensure only authorized users can access the configuration.

For team environments or production systems, SSH key authentication or the keyring extension are strongly recommended. SSH authentication provides the highest security level, while the keyring extension offers a good balance between security and convenience.

Regardless of the chosen method, credentials should be regularly reviewed and updated, particularly when team members change or credential compromise is suspected. For SSH keys, periodic key pair rotation is advised, with private keys properly safeguarded.

Additionally, Mercurial supports other authentication mechanisms such as OAuth and custom authentication extensions, which can be configured based on specific requirements. Understanding these options helps build more flexible and secure version control workflows.