Authenticated Downloads Via `-Z registry-auth`

As of the cargo nightly 2022-11-17, the -Z registry-auth unstable feature is available for fully authenticated downloads without the use of non-standard configuration.

How It Works

The way the -Z registry-auth feature works is by providing an optional auth-required setting in the registry index's config.json file.

When auth-required setting is true, Cargo then requires an auth token for crate downloads and includes an "Authorization" header with the auth token in its download requests to the registry server.

By default, Shipyard.rs sets auth-required to true in new registry index config.json files.

Example `config.json` with `auth-required` setting set to `true`:

{
  "dl": "https://crates.shipyard.rs/api/v1/crates",
  "api": "https://crates.shipyard.rs",
  "allowed-registries": [
    "https://github.com/rust-lang/crates.io-index",
  ],
  "auth-required": true
}

How to Use `-Z registry-auth` Feature

Via Configuration (Recommended)

The -Z registry-auth feature can be enabled via configuration:

# ~/.cargo/config.toml 
[unstable]
registry-auth = true

Via Command Line Flag

Adding -Z registry-auth command line flag to a cargo command will enable the feature, e.g.:

$ cargo check -Z registry-auth

Via Environment Variable

The environment variable CARGO_UNSTABLE_REGISTRY_AUTH can also be used:

$ CARGO_UNSTABLE_REGISTRY_AUTH=true cargo check

Background: Using Nightly

If you have not previously used Rust nightly, you may need to install the nightly channel with rustup:

$ rustup install nightly

Updating Rust Nightly to a Version with `-Z registry-auth` Available

Use the following command to update the nightly channel to the latest version:

$ rustup update nightly

Using Rust Nightly By Default

Use the following command to use rust nightly by default:

$ rustup default nightly

Troubleshooting

"Authenticated Registries Requre a Credential-Provider to be Configured"

See Rust 1.74 and credential-process Changes.

"Authenticated Registries Require `-Z registry-auth`"

Example error message:

$ cargo check
error: failed to download `my-private-crate v0.1.0 (registry `my-registry`)`

Caused by:
  unable to get packages from source

Caused by:
  authenticated registries require `-Z registry-auth`

This error message indicates that the -Z registry-auth feature was not enabled when the Cargo subcommand was invoked. See "How to Use -Z registry-auth Feature".

Rust 1.67 Compatibility Issue

The "authenticated registries require -Z registry-auth" error message can also result from using (stable) Rust version 1.67.

In version 1.67, Cargo will prevent downloads from registries configured with the auth-required setting to true, however, use of the -Z registry-auth feature is not possible using a stable version of rust. This produces a situation where Cargo will not download from the registry unless a mode is enabled that is not permitted to be enabled.

After discussions with the Cargo team, this change was reverted in 1.68. However, in order to use Shipyard.rs with Rust 1.67, you must use the "User-Agent" header-based authorization, and contact support@shipyard.rs to modify the configuration settings for your crate index repository. (Note: Shipyard.rs always requires authentication for all API calls, whether or not the auth-required setting is set to true in the crate index config.json file.)

This problem is not present using Rust 1.66 or below, or Rust 1.68 and above, just 1.67.

"Only Accepted on the Nightly Channel"

Example error message:

$ cargo check
error: the `-Z` flag is only accepted on the nightly channel of Cargo, but this is the `stable` channel
See https://doc.rust-lang.org/book/appendix-07-nightly-rust.html for more information about Rust release channels.

This error indicates that the Cargo subcommand was invoked using the stable version of Cargo/rustc; using Rust nightly is required to enable this feature. See "Using Nightly".

"Failed to Download" (401)

Example error message:

$ cargo check
error: failed to download from `https://crates.shipyard.rs/api/v1/crates/my-private-crate/0.1.0/download`

Caused by:
  failed to get 200 response from `https://crates.shipyard.rs/api/v1/crates/my-private-crate/0.1.0/download`, got 401

You might get this error if the -Z registry-auth feature was not enabled, and the stable version of Cargo was used to invoke the subcommand. In that case, the download request will not have included an "Authorization" header, and Cargo will not have known about the auth-required setting in the registry index's config.json file.

"Unknown `-Z` Flag"

Example error message:

$ cargo +nightly check -Z registry-auth
error: unknown `-Z` flag specified: registry-auth

This error indicates that the nightly version used to invoke the subcommand is from before the -Z registry-auth feature became enabled. To fix, update your nightly version with the rustup update nightly command.

`-Z registry-auth` Stabilization Process

RFC 3139, proposing an auth-required setting that would prompt Cargo to send an authentication token with crate download requests, was approved in March, 2022
A pull request by Arlo Siemsen implementing RFC 3139 was approved Nov. 16, 2022
The -Z registry-auth unstable feature is available in cargo versions as of nightly 2022-11-17

Shipyard.rs: the Book - Private Cargo Registry Service