Registry Authentication

Cargo authenticates to registries with credential providers. These credential providers are external executables or built-in providers that Cargo uses to store and retrieve credentials.

Using alternative registries with authentication requires a credential provider to be configured to avoid unknowingly storing unencrypted credentials on disk. For historical reasons, public (non-authenticated) registries do not require credential provider configuration, and the cargo:token provider is used if no providers are configured.

Cargo also includes platform-specific providers that use the operating system to securely store tokens. The cargo:token provider is also included which stores credentials in unencrypted plain text in the credentials file.

Recommended configuration

It's recommended to configure a global credential provider list in $CARGO_HOME/config.toml which defaults to:

  • Windows: %USERPROFILE%\.cargo\config.toml
  • Unix: ~/.cargo/config.toml

This recommended configuration uses the operating system provider, with a fallback to cargo:token to look in Cargo's credentials file or environment variables:

# ~/.cargo/config.toml
[registry]
global-credential-providers = ["cargo:token", "cargo:libsecret", "cargo:macos-keychain", "cargo:wincred"]

Note that later entries have higher precedence. See registry.global-credential-providers for more details.

Some private registries may also recommend a registry-specific credential-provider. Check your registry's documentation to see if this is the case.

Built-in providers

Cargo includes several built-in credential providers. The available built-in providers may change in future Cargo releases (though there are currently no plans to do so).

cargo:token

Uses Cargo's credentials file to store tokens unencrypted in plain text. When retrieving tokens, checks the CARGO_REGISTRIES_<NAME>_TOKEN environment variable. If this credential provider is not listed, then the *_TOKEN environment variables will not work.

cargo:wincred

Uses the Windows Credential Manager to store tokens.

The credentials are stored as cargo-registry:<index-url> in the Credential Manager under “Windows Credentials”.

cargo:macos-keychain

Uses the macOS Keychain to store tokens.

The Keychain Access app can be used to view stored tokens.

cargo:libsecret

Uses libsecret to store tokens.

Any password manager with libsecret support can be used to view stored tokens. The following are a few examples (non-exhaustive):

cargo:token-from-stdout <command> <args>

Launch a subprocess that returns a token on stdout. Newlines will be trimmed.

  • The process inherits the user's stdin and stderr.
  • It should exit 0 on success, and nonzero on error.
  • cargo login and cargo logout are not supported and return an error if used.

The following environment variables will be provided to the executed command:

  • CARGO --- Path to the cargo binary executing the command.
  • CARGO_REGISTRY_INDEX_URL --- The URL of the registry index.
  • CARGO_REGISTRY_NAME_OPT --- Optional name of the registry. Should not be used as a lookup key.

Arguments will be passed on to the subcommand.

Credential plugins

For credential provider plugins that follow Cargo's credential provider protocol, the configuration value should be a string with the path to the executable (or the executable name if on the PATH).

For example, to install cargo-credential-1password from crates.io do the following:

Install the provider with cargo install cargo-credential-1password

In the config, add to (or create) registry.global-credential-providers:

[registry]
global-credential-providers = ["cargo:token", "cargo-credential-1password --account my.1password.com"]

The values in global-credential-providers are split on spaces into path and command-line arguments. To define a global credential provider where the path or arguments contain spaces, use the [credential-alias] table.